Difference between revisions of "AddRecordingSchedule"

From Gvp-public
Jump to navigation Jump to search
 
(36 intermediate revisions by 3 users not shown)
Line 2: Line 2:
 
Description=Allows scheduling a personal recording for a single event or for a complete series.
 
Description=Allows scheduling a personal recording for a single event or for a complete series.
  
−
Returns an array of [[RecordingSchedule|RecordingSchedule]] objects, filled according to these conditions:
+
Returns an array of [[RecordingSchedule|RecordingSchedule]] objects, filled with the results, properties and status of the recording schedules registered in the remote backend.
  
−
If the recording of the schedule causes a conflict, it won't be scheduled and the state of the returned object will be "Conflicted". StatusCode will be “Recording Service Error Due To Conflicted Record”. This error code is one of the possible error codes returned returned by the method.
+
Please, notice that some backends allows the "successful" creation of recording schedules even when the schedule is in conflict with some other recording schedule. In this case, boolean field "conflicted" of the [[RecordingSchedule|RecordingSchedule]] result object will be set to "true".
  
 +
The list of [[RecordingSchedule|RecordingSchedule]] objects returned in the response may include both "parent recordings" (RecordingSchedules or "definitions") and "children recordings" (the precise and individual recordings that can be associated to a recording schedule). Since creation of "children recordings" is managed by the scheduler of each backend (in the case of MiViewTV and Mediaroom) or by the STB (in the case of Mirada), it is possible that no children recordings are returned at the moment of creating the RecordingSchedule (parent recording). For example, in the cases of series recordings, the new episodes belonging to the series (that may be not "available" in EPG at the moment of scheduling the series recording) will be added automatically by the scheduler or STB.
 +
 +
<p>'''OpenPlatform comments''':</p>
 +
*<span style="color:red">To Be Reviewed: The objects that will come in the response in the singleProgram and full season cases</span>
 +
 +
<p>'''MiViewTV comments''':</p>
 
* If recordEntireSeries is false, returns the only recording schedule
 
* If recordEntireSeries is false, returns the only recording schedule
 
* If recordEntireSeries is true and there is only one occurrence (episode) of the series, return this recording schedule
 
* If recordEntireSeries is true and there is only one occurrence (episode) of the series, return this recording schedule
 
* If recordEntireSeries is true and there are multiple episodes, return the recording schedules of all episodes
 
* If recordEntireSeries is true and there are multiple episodes, return the recording schedules of all episodes
 
   
 
   
 +
<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 33: Line 47:
 
ParamName=channelId
 
ParamName=channelId
 
|ParamType=int
 
|ParamType=int
−
|ParamRequired=required
+
|ParamRequired=required on mediaroom
−
|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 on openPlatform
 +
|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 48: Line 68:
 
|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=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.
 
}}
 
}}
−
 
+
{{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=channelNumber
 +
|ParamType=int
 +
|ParamRequired=optional
 +
|ParamDescription=Allows identifying the ChannelNumber of the Channel inside the Mediaroom channel Map). (LCH channelNumber in the user channel Map)
 +
}}
 +
{{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)
 +
}}
 +
{{Api_Parameter|
 +
ParamName=trackId
 +
|ParamType=string
 +
|ParamRequired=optional
 +
|ParamDescription=trackId of the schedule if it has been recommended to the user
 +
}}
 +
{{Api_Parameter|
 +
ParamName=UXReference
 +
|ParamType=string
 +
|ParamRequired=optional
 +
|ParamDescription=UXReference of the request that returned the recommendation
 +
}}
 
|Returns=
 
|Returns=
 
Returns a JSON object with a list of [[RecordingSchedule|RecordingSchedule]].
 
Returns a JSON object with a list of [[RecordingSchedule|RecordingSchedule]].
Line 59: Line 107:
 
:    "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:
 +
*210    UnexpectedRecordingResponse            ''OpenPlatf''
 +
*211 RecordingSubscriberNotFound ''OpenPlatf, MiViewTV, Mirada, Mediaroom''
 +
*212 RecordingSubscriberNotSubscribed ''OpenPlatf, MiViewTV, Mirada''
 +
*213 RecordingUnknownError ''OpenPlatf, MiViewTV, Mirada, Mediaroom''
 +
*215 RecordingSubscriberQuotaExceeded ''OpenPlatf, MiViewTV''
 +
*216 RecordingPersonalLimitExceeded ''OpenPlatf, MiViewTV''
 +
*217 RecordingSeriesLimitExceeded ''OpenPlatf, MiViewTV''
 +
*218 RecordingChannelNotOwnedBySubscriber ''OpenPlatf, MiViewTV''
 +
*219 RecordingSeriesNotFound ''OpenPlatf, MiViewTV, Mediaroom''
 +
*220 RecordingChannelNotFound ''OpenPlatf, MiViewTV, Mirada, Mediaroom''
 +
*221 RecordingAlreadySubscribed ''OpenPlatf, MiViewTV, Mirada, Mediaroom''
 +
*222 RecordingNotAllowedToSchedule ''OpenPlatf, MiViewTV''
 +
*223 RecordingProgramNotFound ''OpenPlatf, MiViewTV, Mirada, Mediaroom''
 +
*224 RecordingProgramAlreadyFinished ''OpenPlatf, MiViewTV, Mirada''
 +
*229 PvrVersionMismatch ''OpenPlatf, Mediaroom''
 +
*232 RecordingUnknownDefinitionType ''OpenPlatf, Mediaroom''
 +
*233 RecordingTimeFrameInvalid ''OpenPlatf, Mediaroom''
  
 
|Cache=
 
|Cache=
Line 82: Line 147:
 
{{!}} Initial method design
 
{{!}} Initial method design
 
{{!}}  
 
{{!}}  
 +
{{!}}- valign="top"
 +
! 2.4 drop 1
 +
{{!}} Added support for Mirada and Mediaroom. Introduced new parameter targetDeviceId
 +
{{!}}
 +
{{!}}- valign="top"
 +
! 7.1
 +
{{!}} Added support for CPVR
 +
{{!}} José Manuel Escartín
 
{{!}}}
 
{{!}}}
  

Latest revision as of 13:03, 10 July 2019

Description

Allows scheduling a personal recording for a single event or for a complete series.

Returns an array of RecordingSchedule objects, filled with the results, properties and status of the recording schedules registered in the remote backend.

Please, notice that some backends allows the "successful" creation of recording schedules even when the schedule is in conflict with some other recording schedule. In this case, boolean field "conflicted" of the RecordingSchedule result object will be set to "true".

The list of RecordingSchedule objects returned in the response may include both "parent recordings" (RecordingSchedules or "definitions") and "children recordings" (the precise and individual recordings that can be associated to a recording schedule). Since creation of "children recordings" is managed by the scheduler of each backend (in the case of MiViewTV and Mediaroom) or by the STB (in the case of Mirada), it is possible that no children recordings are returned at the moment of creating the RecordingSchedule (parent recording). For example, in the cases of series recordings, the new episodes belonging to the series (that may be not "available" in EPG at the moment of scheduling the series recording) will be added automatically by the scheduler or STB.

OpenPlatform comments:

  • To Be Reviewed: The objects that will come in the response in the singleProgram and full season cases

MiViewTV comments:

  • If recordEntireSeries is false, returns the only recording schedule
  • If recordEntireSeries is true and there is only one occurrence (episode) of the series, return this recording schedule
  • If recordEntireSeries is true and there are multiple episodes, return the recording schedules of all episodes

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)
Live Schedule ID
  • programId (int, required)
Live Program ID
  • channelId (int, required on mediaroom)
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 on openPlatform)
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))
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.
  • 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)
  • channelNumber (int, optional)
Allows identifying the ChannelNumber of the Channel inside the Mediaroom channel Map). (LCH channelNumber in the user channel Map)
  • 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)
  • trackId (string, optional)
trackId of the schedule if it has been recommended to the user
  • UXReference (string, optional)
UXReference of the request that returned the recommendation


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:

  • 210 UnexpectedRecordingResponse OpenPlatf
  • 211 RecordingSubscriberNotFound OpenPlatf, MiViewTV, Mirada, Mediaroom
  • 212 RecordingSubscriberNotSubscribed OpenPlatf, MiViewTV, Mirada
  • 213 RecordingUnknownError OpenPlatf, MiViewTV, Mirada, Mediaroom
  • 215 RecordingSubscriberQuotaExceeded OpenPlatf, MiViewTV
  • 216 RecordingPersonalLimitExceeded OpenPlatf, MiViewTV
  • 217 RecordingSeriesLimitExceeded OpenPlatf, MiViewTV
  • 218 RecordingChannelNotOwnedBySubscriber OpenPlatf, MiViewTV
  • 219 RecordingSeriesNotFound OpenPlatf, MiViewTV, Mediaroom
  • 220 RecordingChannelNotFound OpenPlatf, MiViewTV, Mirada, Mediaroom
  • 221 RecordingAlreadySubscribed OpenPlatf, MiViewTV, Mirada, Mediaroom
  • 222 RecordingNotAllowedToSchedule OpenPlatf, MiViewTV
  • 223 RecordingProgramNotFound OpenPlatf, MiViewTV, Mirada, Mediaroom
  • 224 RecordingProgramAlreadyFinished OpenPlatf, MiViewTV, Mirada
  • 229 PvrVersionMismatch OpenPlatf, Mediaroom
  • 232 RecordingUnknownDefinitionType OpenPlatf, Mediaroom
  • 233 RecordingTimeFrameInvalid OpenPlatf, Mediaroom


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 parameter targetDeviceId
7.1 Added support for CPVR José Manuel Escartín


See also

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