Difference between revisions of "DeleteRecordingSchedule"

From Gvp-public
Jump to navigation Jump to search
 
(20 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{Api_Method_Spec|
 
{{Api_Method_Spec|
−
Description= Delete each of the given Schedule Recording from the platform. If the external platform provides a Network PVR service, this method will remove contents accessible by the network. In the case of Remote PVR service availability, this method will physically delete contents from the connected STB hard disk.
+
Description= Deletes the provided Recording (ID). This method is mainly intended for deleting recordings ("child recordings") from the user's STB, although it is also allowed (depending on the backend) to delete RecordingDefinition ("parent recording" or "recording definition") from the platform.  
 +
 
 +
Returns an array of [[RecordingSchedule|RecordingSchedule]] objects, filled with the results and status parameters.
 +
 
 +
<p>* '''MiView (ALU) comments''':</p>
 +
* MiView does not establish a clear distinction between RecordingSchedules and Recordings.
 +
* In MiView, since it is a true "network PVR" model, recordings are stored "in the network" (not in the user's STB).
 +
* DeleteRecordingSchedule, when invoked for a MiView backend, deletes (or cancels) the recording (schedules), so subsequent requests for listing the user's "recordings" result in that the recordings/RecordingSchedules do not appear. "Physical" recordings do not make sense in this case, as they are stored and handled by MiView platform (so, although a user removes a recording, the media may be kept to be used by another user).
 +
 
 +
<p>* '''Mirada comments''':</p>
 +
* Clients wanting to cancel (or delete) a recording should have to firstly request a [[GetAllRecordingSchedules|GetAllRecordingSchedules]] call, in order to retrieve the recordings ID and (in the case of Mirada) the associated lastModified value that must be included in the cancel/delete request. ​This parameter will not be available (GetAllRecordingSchedules will return 0) for some other rPVR backends.
 +
* When cancelling things "in the future" (not started yet), such as individual movies/episodes not started yet, or the cancellation of entire series, the final purpose is to "avoid" the future recording of an event. The [[RecordingSchedule|RecordingSchedule]] object would be set to GVP status "Cancelled"
 +
* When cancelling only a thing that is just being recorded at the current moment (at the moment of invoking cancel by the client) the final purpose is to "stop" the ongoing recording (and the status of the schedule, in both Mirada's backend and in the [[RecordingSchedule|RecordingSchedule]] object returned to clients, would be set to "finished"​/completed, not "cancelled"). This is the case when cancelling individual events or episodes within series (but NOT cancelling the whole series) AND the event to cancel is just being recorded at this moment.
 +
 
 +
<p>* '''Mediaroom comments''':</p>
 +
*DeleteRecordingSchedules is '''intended for deleting individual ("child") recordings, existing in the user's STB''', but not cancelling or deleting the whole definition (RecordingDefinition).
 +
* Clients must invoke DeleteRecordingSchedule sending the id of the Recording (not RecordingDefinition in the case of Mediaroom) to delete within the recordingScheduleId. If several recordings must be deleted, client will have to request it through sequential requests (one by one)
 +
* Since the behavior of DeleteRecordingSchedule in Mediaroom is "to remove the completed recordings on the STB", it does not make sense to request the deletion of a whole series, so '''method will return an error if it is invoked requesting an entireSeries deletion in Mediaroom'''.
  
−
Returns an array of [[RecordingSchedule|RecordingSchedule]] objects, filled with the recording related parameters:
 
−
*If the recording was successfully deleted by the platform, its state will be "Deleted"
 
−
*If a given recording could not be deleted, its state will remain "Recorded".
 
−
*If a given recording was not found, its state will be "Not Found".
 
  
 
|Parameters=
 
|Parameters=
Line 15: Line 28:
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
−
ParamName=recordingScheduleId
+
ParamName=scheduleId
 
|ParamType=int
 
|ParamType=int
 
|ParamRequired=required
 
|ParamRequired=required
−
|ParamDescription=ID of the Recording Schedule to be canceled
+
|ParamDescription=schedule Id to be deleted (introduced -and kept for compatability in MiViewTV Phase I; superseded by recordingScheduleId)
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
Line 27: Line 40:
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
−
ParamName=EPGLiveChannelReferenceId
+
ParamName=channelId
 
|ParamType=int
 
|ParamType=int
 
|ParamRequired=required
 
|ParamRequired=required
−
|ParamDescription=Live Channel ID (as appearing in EPG file)
+
|ParamDescription=Live Channel ID (GVP_EPG_LIVE_CHANNELS.REFERENCE_ID; as appearing in EPG file) available in contentApi (LSC.EpgChannelId) info not available in IPI, sent blank in that case
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
−
ParamName=serieId
+
ParamName=LiveChannelId
 +
|ParamType=int
 +
|ParamRequired=required
 +
|ParamDescription= GVP Live Channel ID (GVP_EPG_SCHEDULE. EPG_LIVE_CHANNEL_ID) the ChannelId sent through contentApi (LSC.ChannelId) and IPI (Channel_id: ServiceName)
 +
}}
 +
{{Api_Parameter|
 +
ParamName=seriesId
 
|ParamType=int
 
|ParamType=int
 
|ParamRequired=optional
 
|ParamRequired=optional
−
|ParamDescription=ID of the series associated to the schedule. Value will be set to 0 if the program is not a series episode.
+
|ParamDescription=ID of the series associated to the schedule. Value will be set to 0 if the program is not a series episode. Deletion of series is not allowed in all backends.
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
Line 42: Line 61:
 
|ParamType=bool
 
|ParamType=bool
 
|ParamRequired=optional (default=false)
 
|ParamRequired=optional (default=false)
−
|ParamDescription=If the Schedule Id is a series episode, all the next episodes should also be scheduled for recording when set to true. If set to false, only the single episode will be scheduled.
+
|ParamDescription=Whether delete operation affects a whole series scheduling or not
 +
}}
 +
{{Api_Parameter|
 +
ParamName=recordingScheduleId
 +
|ParamType=string
 +
|ParamRequired=optional (declared "optional" for backwards compatibility; but needed for correct operation)
 +
|ParamDescription=ID (string) of the Recording to be deleted
 +
}}
 +
{{Api_Parameter|
 +
ParamName=lastModified
 +
|ParamType=int
 +
|ParamRequired=optional (needed for correct operation in Mirada)
 +
|ParamDescription=Date-time of the last modification of the recording schedule (must be previously obtained from Mirada's backend)
 +
}}
 +
{{Api_Parameter|
 +
ParamName=targetDeviceId
 +
|ParamType=int
 +
|ParamRequired=optional
 +
|ParamDescription=Allows identifying the user's device (STB) on which the application will be applied, in the case that several DVR devices may exist in the household (does not apply to MiView and Mediaroom)
 +
}}
 +
{{Api_Parameter|
 +
ParamName=SeasonNumber
 +
|ParamType=int
 +
|ParamRequired=optional
 +
|ParamDescription=This parameter is mandatory in OpenPlatform implementation, is the SeasonNumber of the LSC object in contentApi (BBDD GVP_EPG_PROGRAMS.EPG_SEASON_NUMBER)
 
}}
 
}}
−
 
  
 
|Returns=
 
|Returns=
Line 55: Line 97:
 
:    "Limit": 10,
 
:    "Limit": 10,
 
:    "Count": 48,
 
:    "Count": 48,
−
:    [ Array of [[RecordingSchedule|RecordingSchedule]] objects ]
+
:    "List":[ Array of [[RecordingSchedule|RecordingSchedule]] objects ]
 
}
 
}
  
  
 
|Exceptions=
 
|Exceptions=
−
* None.
+
Possible error results (included in the GVP general error list) are:
 +
*8 MissingRequiredParameter ''OpenPlatf, Mirada''
 +
*211 RecordingSubscriberNotFound ''OpenPlatf, MiViewTv, Mirada, Mediaroom''
 +
*212 RecordingSubscriberNotSubscribed ''OpenPlatf, MiViewTv, Mirada, Mediaorom''
 +
*213 RecordingUnknownError ''OpenPlatf, MiViewTv, Mirada, Mediaroom''
 +
*220 RecordingChannelNotFound ''OpenPlatf, Mirada''
 +
*221 RecordingAlreadySubscribed ''OpenPlatf, Mirada''
 +
*223 RecordingProgramNotfound ''OpenPlatf, Mirada''
 +
*228 RecordingProgramNotFinished ''OpenPlatf, MiViewTv''
 +
*235 RequestedLanguagesUnavailable ''OpenPlatf, Mirada''
 +
*236 RecordingUpdatedFromAnotherDevice ''OpenPlatf, Mirada''
 +
*237 RecordingProtected ''OpenPlatf, Mirada''
 +
*238 RecordingHavingChildren ''OpenPlatf, Mirada''
 +
*239 RecordingNotFound ''OpenPlatf, Mirada, Mediaroom''
 +
*240 RecordingRemoteManagementNotEnabled ''OpenPlatf, Mirada''
 +
*241 RecordingIncorrectIntervalDefined ''Mirada''
 +
*242 RecordingIncorrectStartDate ''Mirada''
 +
 
  
 
|Cache=
 
|Cache=
Line 78: Line 137:
 
{{!}} Initial method design
 
{{!}} Initial method design
 
{{!}}  
 
{{!}}  
 +
{{!}}- valign="top"
 +
! 2.4 drop 1
 +
{{!}} Added support for Mirada and Mediaroom. Introduced new parameters recordingScheduleId, lastModified and targetDeviceId
 +
{{!}}
 +
{{!}}- valign="top"
 +
! 3.0
 +
{{!}} Changed behavior for Mediaroom: method deletes completed (child) Recordings, not RecordingDefinitions
 +
{{!}}
 +
{{!}}- valign="top"
 +
! 7.1
 +
{{!}} Changed behavior for OpenPlatform. SeasonNumber
 +
{{!}} José Manuel Escartín
 
{{!}}}
 
{{!}}}
  

Latest revision as of 11:31, 30 May 2019

Description

Deletes the provided Recording (ID). This method is mainly intended for deleting recordings ("child recordings") from the user's STB, although it is also allowed (depending on the backend) to delete RecordingDefinition ("parent recording" or "recording definition") from the platform.

Returns an array of RecordingSchedule objects, filled with the results and status parameters.

* MiView (ALU) comments:

  • MiView does not establish a clear distinction between RecordingSchedules and Recordings.
  • In MiView, since it is a true "network PVR" model, recordings are stored "in the network" (not in the user's STB).
  • DeleteRecordingSchedule, when invoked for a MiView backend, deletes (or cancels) the recording (schedules), so subsequent requests for listing the user's "recordings" result in that the recordings/RecordingSchedules do not appear. "Physical" recordings do not make sense in this case, as they are stored and handled by MiView platform (so, although a user removes a recording, the media may be kept to be used by another user).

* Mirada comments:

  • Clients wanting to cancel (or delete) a recording should have to firstly request a GetAllRecordingSchedules call, in order to retrieve the recordings ID and (in the case of Mirada) the associated lastModified value that must be included in the cancel/delete request. ​This parameter will not be available (GetAllRecordingSchedules will return 0) for some other rPVR backends.
  • When cancelling things "in the future" (not started yet), such as individual movies/episodes not started yet, or the cancellation of entire series, the final purpose is to "avoid" the future recording of an event. The RecordingSchedule object would be set to GVP status "Cancelled"
  • When cancelling only a thing that is just being recorded at the current moment (at the moment of invoking cancel by the client) the final purpose is to "stop" the ongoing recording (and the status of the schedule, in both Mirada's backend and in the RecordingSchedule object returned to clients, would be set to "finished"​/completed, not "cancelled"). This is the case when cancelling individual events or episodes within series (but NOT cancelling the whole series) AND the event to cancel is just being recorded at this moment.

* Mediaroom comments:

  • DeleteRecordingSchedules is intended for deleting individual ("child") recordings, existing in the user's STB, but not cancelling or deleting the whole definition (RecordingDefinition).
  • Clients must invoke DeleteRecordingSchedule sending the id of the Recording (not RecordingDefinition in the case of Mediaroom) to delete within the recordingScheduleId. If several recordings must be deleted, client will have to request it through sequential requests (one by one)
  • Since the behavior of DeleteRecordingSchedule in Mediaroom is "to remove the completed recordings on the STB", it does not make sense to request the deletion of a whole series, so method will return an error if it is invoked requesting an entireSeries deletion in Mediaroom.

Parameters

  • token (String, required)
A valid token for identifying the API session context and logged user.
  • scheduleId (int, required)
schedule Id to be deleted (introduced -and kept for compatability in MiViewTV Phase I; superseded by recordingScheduleId)
  • programId (int, required)
Live Program ID
  • channelId (int, required)
Live Channel ID (GVP_EPG_LIVE_CHANNELS.REFERENCE_ID; as appearing in EPG file) available in contentApi (LSC.EpgChannelId) info not available in IPI, sent blank in that case
  • LiveChannelId (int, required)
GVP Live Channel ID (GVP_EPG_SCHEDULE. EPG_LIVE_CHANNEL_ID) the ChannelId sent through contentApi (LSC.ChannelId) and IPI (Channel_id: ServiceName)
  • seriesId (int, optional)
ID of the series associated to the schedule. Value will be set to 0 if the program is not a series episode. Deletion of series is not allowed in all backends.
  • entireSeries (bool, optional (default=false))
Whether delete operation affects a whole series scheduling or not
  • recordingScheduleId (string, optional (declared "optional" for backwards compatibility; but needed for correct operation))
ID (string) of the Recording to be deleted
  • lastModified (int, optional (needed for correct operation in Mirada))
Date-time of the last modification of the recording schedule (must be previously obtained from Mirada's backend)
  • targetDeviceId (int, optional)
Allows identifying the user's device (STB) on which the application will be applied, in the case that several DVR devices may exist in the household (does not apply to MiView and Mediaroom)
  • SeasonNumber (int, optional)
This parameter is mandatory in OpenPlatform implementation, is the SeasonNumber of the LSC object in contentApi (BBDD GVP_EPG_PROGRAMS.EPG_SEASON_NUMBER)


Returns

Returns a JSON object with a list of RecordingSchedule.

Example:

{

"Offset": 0,
"Limit": 10,
"Count": 48,
"List":[ Array of RecordingSchedule objects ]

}


Exceptions

Possible error results (included in the GVP general error list) are:

  • 8 MissingRequiredParameter OpenPlatf, Mirada
  • 211 RecordingSubscriberNotFound OpenPlatf, MiViewTv, Mirada, Mediaroom
  • 212 RecordingSubscriberNotSubscribed OpenPlatf, MiViewTv, Mirada, Mediaorom
  • 213 RecordingUnknownError OpenPlatf, MiViewTv, Mirada, Mediaroom
  • 220 RecordingChannelNotFound OpenPlatf, Mirada
  • 221 RecordingAlreadySubscribed OpenPlatf, Mirada
  • 223 RecordingProgramNotfound OpenPlatf, Mirada
  • 228 RecordingProgramNotFinished OpenPlatf, MiViewTv
  • 235 RequestedLanguagesUnavailable OpenPlatf, Mirada
  • 236 RecordingUpdatedFromAnotherDevice OpenPlatf, Mirada
  • 237 RecordingProtected OpenPlatf, Mirada
  • 238 RecordingHavingChildren OpenPlatf, Mirada
  • 239 RecordingNotFound OpenPlatf, Mirada, Mediaroom
  • 240 RecordingRemoteManagementNotEnabled OpenPlatf, Mirada
  • 241 RecordingIncorrectIntervalDefined Mirada
  • 242 RecordingIncorrectStartDate Mirada


Caching

This method is not cached.


Known issues

None


Version history

API Version Number Change description Changes author
2.4 Initial method design
2.4 drop 1 Added support for Mirada and Mediaroom. Introduced new parameters recordingScheduleId, lastModified and targetDeviceId
3.0 Changed behavior for Mediaroom: method deletes completed (child) Recordings, not RecordingDefinitions
7.1 Changed behavior for OpenPlatform. SeasonNumber José Manuel Escartín


See also

Retrieved from "https://wikis.tid.es/gvp-public/index.php?title=DeleteRecordingSchedule&oldid=2926"