Difference between revisions of "CancelRecordingSchedule"

From Gvp-public
Jump to navigation Jump to search
Line 2: Line 2:
 
Description= Cancel each of the given RecordingSchedule and delete them from the platform.
 
Description= Cancel each of the given RecordingSchedule and delete them from the platform.
 
   
 
   
−
Returns an rray of [[RecordingSchedule|RecordingSchedule]] objects, filled with the recording related parameters:
+
Returns an array of [[RecordingSchedule|RecordingSchedule]] objects, filled with the recording related parameters.
−
* If the recording schedule was successfully cancelled and deleted by the platform, its state will be "Canceled"
+
 
−
* If a given recording schedule could not be canceled, its state will remain "Scheduled".  
+
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.
−
* If a given recording schedule was not found, its state will be "Not Found".  
+
 
 +
<p>* '''Mirada comments''':</p>
 +
* Recordings from Go devices will be based on (GVP internal) scheduleID, but must be converted (by GVP gateway/UNIAPI) to the equivalent time frame (start time + duration) in order to be invoked to Mirada (as event-based recording is not possible without the mirada internal eventID). This will be done through a parameter in Mirada's create recording method, indicating Mirada back-end that the provided time window must be converted to the associated internal event ID.
 +
* Mirada requires the identification of the "target" device (STB) affected by the method. GVP API allows two ways of selecting the "target device" for each method (this only applies to Mirada backend, as Mediaroom backend has an internal mechanism for managing the STBs associated to a subscriber and only allows a "master" STB which performs all the PVR operations; so in Mediaroom it is not possible to select the target Device): Through the "targetDeviceId" parameter, or, if the "targetDeviceId" parameter is not sent by the client, an automatic device selection will be used instead
 +
* In the case of "series recording schedules", the method will only create a kind of "container recording schedule" where the actual recordings will be added. After creating the "container" (parent recording for the series), the STB will later (automatically and periodically, after detecting the parent recording schedule) add the recording for each episode linked to the series.
 +
 
 +
<p>* '''Mediaroom comments''':</p>
 +
* Mediaroom service allows two types of recordings: Dynamic ("event-based") and "manual" (or "time-based" specifying channel ID, program, and time frame). GVP nPVR API only uses the Dynamic (event-based) mode, as the devices (such as Go) schedule recordings based on info from the EPG
 +
* In principle, Mediaroom allows creation or recordings even when they are in conflict with other recording(s). In this case, it will be reflected it in the [[RecordingSchedule|RecordingSchedule]] struct of the response (using the boolean member "Conflicted").​​ Tt is also possible that some "conflicting" recordings are automatically detected and not registered by Mediaroom, so the process could result in an error (exception).
 
   
 
   
 
|Parameters=
 
|Parameters=
Line 49: Line 57:
 
|ParamRequired=optional (declared "optional" for backwards compatibility; but needed for correct operation)
 
|ParamRequired=optional (declared "optional" for backwards compatibility; but needed for correct operation)
 
|ParamDescription=ID (string) of the Recording Schedule to be canceled
 
|ParamDescription=ID (string) of the Recording Schedule to be canceled
 +
}}
 +
{{Api_Parameter|
 +
ParamName=lastModified
 +
|ParamType=int
 +
|ParamRequired=optional (needed for correct operation in Mirada)
 +
|ParamDescription=Date-time of last modification of the recording schedule (must be previously obtained from Mirada's backend)
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
Line 91: Line 105:
 
{{!}}- valign="top"
 
{{!}}- valign="top"
 
! 2.4 drop 1
 
! 2.4 drop 1
−
{{!}} Added support for Mirada and Mediaroom. Introduced new parameters recordingScheduleId and targetDeviceId
+
{{!}} Added support for Mirada and Mediaroom. Introduced new parameters recordingScheduleId, lastModified and targetDeviceId
 
{{!}}  
 
{{!}}  
 
{{!}}}
 
{{!}}}

Revision as of 08:59, 31 October 2014

Description

Cancel each of the given RecordingSchedule and delete them from the platform.

Returns an array of RecordingSchedule objects, filled with the recording related parameters.

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.

* Mirada comments:

  • Recordings from Go devices will be based on (GVP internal) scheduleID, but must be converted (by GVP gateway/UNIAPI) to the equivalent time frame (start time + duration) in order to be invoked to Mirada (as event-based recording is not possible without the mirada internal eventID). This will be done through a parameter in Mirada's create recording method, indicating Mirada back-end that the provided time window must be converted to the associated internal event ID.
  • Mirada requires the identification of the "target" device (STB) affected by the method. GVP API allows two ways of selecting the "target device" for each method (this only applies to Mirada backend, as Mediaroom backend has an internal mechanism for managing the STBs associated to a subscriber and only allows a "master" STB which performs all the PVR operations; so in Mediaroom it is not possible to select the target Device): Through the "targetDeviceId" parameter, or, if the "targetDeviceId" parameter is not sent by the client, an automatic device selection will be used instead
  • In the case of "series recording schedules", the method will only create a kind of "container recording schedule" where the actual recordings will be added. After creating the "container" (parent recording for the series), the STB will later (automatically and periodically, after detecting the parent recording schedule) add the recording for each episode linked to the series.

* Mediaroom comments:

  • Mediaroom service allows two types of recordings: Dynamic ("event-based") and "manual" (or "time-based" specifying channel ID, program, and time frame). GVP nPVR API only uses the Dynamic (event-based) mode, as the devices (such as Go) schedule recordings based on info from the EPG
  • In principle, Mediaroom allows creation or recordings even when they are in conflict with other recording(s). In this case, it will be reflected it in the RecordingSchedule struct of the response (using the boolean member "Conflicted").​​ Tt is also possible that some "conflicting" recordings are automatically detected and not registered by Mediaroom, so the process could result in an error (exception).

Parameters

  • token (String, required)
A valid token for identifying the API session context and logged user.
  • scheduleId (int, required)
schedule Id to be cancelled (introduced -and kept for compatability in MiViewTV Phase I; superseded by recordingScheduleId)
  • programId (int, required)
Live Program ID
  • channelId (int, required)
Live Channel ID (EPGLiveChannelReferenceId; as appearing in EPG file)
  • 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.
  • entireSeries (bool, optional (default=false))
Whether cancel 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 Schedule to be canceled
  • lastModified (int, optional (needed for correct operation in Mirada))
Date-time of 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)


Returns

Returns a JSON object with a list of RecordingSchedule.

Example:

{

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

}


Exceptions

  • None.


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


See also

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