Difference between revisions of "CancelRecordingSchedule"

From Gvp-public
Jump to navigation Jump to search
 
(12 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
{{Api_Method_Spec|
 
{{Api_Method_Spec|
−
Description= Cancel each of the given RecordingSchedule and delete them from the platform.
+
Description= Cancel each of the given RecordingSchedule ("parent recording schedule" or "recording definition") and removes them from the platform.
 
   
 
   
 
Returns an array of [[RecordingSchedule|RecordingSchedule]] objects, filled with the recording related parameters.
 
Returns an array of [[RecordingSchedule|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.
 
  
 
<p>* '''Mirada comments''':</p>
 
<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.
+
* 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.
−
* 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
+
* 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"
−
* 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.  
+
* 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>
 
<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
+
* The Mediaroom API (RemoveRecordingDefinition) method removes a recording definition (the equivalent concept to a [[RecordingSchedule|RecordingSchedule]]), and all associated upcoming recordings, from an account's schedule.​ The behavior of the method depends on whether there are recordings already associated with this recording definition:
−
* 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).
+
<ul>
−
+
  <li>If there are no recordings associated with this definition (there are no matching programs in the current EPG data), the recording definition is deleted.</li>
 +
  <li>If recordings have already been made, the existing recordings are kept, but the recording definition's state is set to "cancelled," preventing any future recordings from being made. After all existing recordings have been deleted, the recording definition is automatically deleted.</li>
 +
  <li>If a recording is currently in progress, it is halted. The recording definition's state is also set to "cancelled," preventing future recordings from being made. Again, after all existing recordings have been deleted, the recording definition is automatically deleted.</li>
 +
</ul>
 +
* In the [[RecordingSchedule|RecordingSchedule]] object handled by GVP (returned to clients), the status would be set to the state "Cancelled" ​(as this state includes both "cancelled" and "deleted" schedules that will be the states managed by Mediaroom when invoking RemoveRecordingDefinition)
 +
 
 
|Parameters=
 
|Parameters=
 
{{Api_Parameter|
 
{{Api_Parameter|
Line 38: Line 42:
 
|ParamType=int
 
|ParamType=int
 
|ParamRequired=required
 
|ParamRequired=required
−
|ParamDescription=Live Channel ID (EPGLiveChannelReferenceId; 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|
 +
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|
 
{{Api_Parameter|
Line 56: Line 66:
 
|ParamType=string
 
|ParamType=string
 
|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 of the Recording Schedule. In rPVR, TO cancel, delete or read a recording, the recordingId sent by OTT devices has to be the same as recordingId sent by STB IPTV, for consistency.
 
}}
 
}}
 
{{Api_Parameter|
 
{{Api_Parameter|
Line 69: Line 79:
 
|ParamRequired=optional
 
|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)
 
|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)
 
}}
 
}}
  
Line 80: Line 96:
 
:    "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, MiViewTv, Mirada''
 +
*224 RecordingProgramAlreadyFinished ''OpenPlatf, MiViewTv''
 +
*226 RecordingNotAllowedToCancel ''OpenPlatf, MiViewTv''
 +
*227 RecordingSeriesNotOwnedBySubscriber ''OpenPlatf, MiViewTv''
 +
*235 RequestedLanguagesUnavailable ''Mirada''
 +
*236 RecordingUpdatedFromAnotherDevice ''Mirada''
 +
*237 RecordingProtected ''OpenPlatf, Mirada''
 +
*238 RecordingHavingChildren ''Mirada''
 +
*239 RecordingNotFound ''OpenPlatf, Mirada, Mediaroom''
 +
*240 RecordingRemoteManagementNotEnabled ''Mirada''
 +
*241 RecordingIncorrectIntervalDefined ''Mirada''
 +
*242 RecordingIncorrectStartDate ''Mirada''
  
 
|Cache=
 
|Cache=
Line 107: Line 141:
 
{{!}} Added support for Mirada and Mediaroom. Introduced new parameters recordingScheduleId, lastModified and targetDeviceId
 
{{!}} Added support for Mirada and Mediaroom. Introduced new parameters recordingScheduleId, lastModified and targetDeviceId
 
{{!}}  
 
{{!}}  
 +
{{!}}- valign="top"
 +
! 7.1
 +
{{!}} Added support to OpenPlatform. SeasonNumber
 +
{{!}}  José Manuel Escartín
 
{{!}}}
 
{{!}}}
  

Latest revision as of 10:55, 18 February 2021

Description

Cancel each of the given RecordingSchedule ("parent recording schedule" or "recording definition") and removes them from the platform.

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


* 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:

  • The Mediaroom API (RemoveRecordingDefinition) method removes a recording definition (the equivalent concept to a RecordingSchedule), and all associated upcoming recordings, from an account's schedule.​ The behavior of the method depends on whether there are recordings already associated with this recording definition:
  • If there are no recordings associated with this definition (there are no matching programs in the current EPG data), the recording definition is deleted.
  • If recordings have already been made, the existing recordings are kept, but the recording definition's state is set to "cancelled," preventing any future recordings from being made. After all existing recordings have been deleted, the recording definition is automatically deleted.
  • If a recording is currently in progress, it is halted. The recording definition's state is also set to "cancelled," preventing future recordings from being made. Again, after all existing recordings have been deleted, the recording definition is automatically deleted.
  • In the RecordingSchedule object handled by GVP (returned to clients), the status would be set to the state "Cancelled" ​(as this state includes both "cancelled" and "deleted" schedules that will be the states managed by Mediaroom when invoking RemoveRecordingDefinition)

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 (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.
  • 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 of the Recording Schedule. In rPVR, TO cancel, delete or read a recording, the recordingId sent by OTT devices has to be the same as recordingId sent by STB IPTV, for consistency.
  • 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)
  • 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, MiViewTv, Mirada
  • 224 RecordingProgramAlreadyFinished OpenPlatf, MiViewTv
  • 226 RecordingNotAllowedToCancel OpenPlatf, MiViewTv
  • 227 RecordingSeriesNotOwnedBySubscriber OpenPlatf, MiViewTv
  • 235 RequestedLanguagesUnavailable Mirada
  • 236 RecordingUpdatedFromAnotherDevice Mirada
  • 237 RecordingProtected OpenPlatf, Mirada
  • 238 RecordingHavingChildren Mirada
  • 239 RecordingNotFound OpenPlatf, Mirada, Mediaroom
  • 240 RecordingRemoteManagementNotEnabled 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
7.1 Added support to OpenPlatform. SeasonNumber José Manuel Escartín


See also

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