OIPF - Release 2 Specification - Volume 5, Declarative Application Environment, V2.3

Abstract

This Technical Specification (TS) has been produced by the Open IPTV Forum.

This specification provides multiple options for some features. The Open IPTV Forum Profiles specification complements the Release 2 specifications by defining the Open IPTV Forum implementation and deployment profiles.

Term	Definition
Audio from memory	Audible notifications and audio clips intended to be played from memory.
Broadcast related application	Interactive application associated with a television or radio channel, with part of a television channel (e.g. a particular program or show) or other television content. Often referred to as “red button” applications in the industry, regardless of how they are actually started by the end user.
Broadcast independent application	Interactive application not related to any TV channel or TV content or to the currently selected service provider.
Control UI	The Remote UI that controls DAE applications in the OITF, sent from an IPTV Applications server via the OITF or pre-stored in the OITF, and rendered in the DLNA RUIC on the Remote Control Device.
DLNA RUIC	A DLNA device with the role of finding and loading remote UI content exposed by a DLNA RUIS capability and rendering and interacting with the UI content. Note: This terminology references the DLNA RUI specification.
DLNA RUIS	A DLNA Function in the OITF with the role of exposing and sourcing UI content. Note: This terminology references the DLNA RUI specification.
Embedded object	A software module that extends the capabilities of the OITF browser. Features provided by an embedded object are made available to DAE applications through the methods and properties of a specific JavaScript object.
HTML document	An XHTML document and associated style and script files conforming to the restrictions and extensions defined in the present document.
Key Event	Event sent to a DAE application in response to input from the end-user. This input is typically generated in response to the end-user pressing a button on a conventional remote control. It may also be generated by some other mechanism on alternative input devices such as game controllers, touch screens, wands or drastically reduced remote controls.
Mandatory	The feature is an absolute requirement of the specification (a “must” as defined by [RFC2119]).
MB or megabyte	2²⁰ bytes
Non-visual embedded object	A non-visual embedded object is an embedded object that has no visible representation and cannot get input focus
Optional	The feature is truly optional (a “may” as defined by [RFC2119])
Remote Control Device	A mobile or portable device which has the functionality of the DLNA RUIC.
Remote UI	The display of a UI from one device on a second (remote) device across a network.
Service provider related application	Interactive application related to the service provider selected through the service provider selection process.
Trick Mode	Facility to allow the User to control the playback of Content, such as pause, fast and slow playback, reverse playback, instant access, replay, forward and reverse skipping.

Acronym	Explanation
AJAX	Asynchronous JavaScript and XML
CRID	Content Reference Identifier
CSS	Cascading style sheets
DOM	Document object model
GIF	Graphics Interchange Format
HAS	HTTP Adaptive Streaming
HE-AAC	High Efficiency AAC
IR	Infra Red
JPEG	Joint Photographic Experts Group
MPD	Media Presentation Description
PNG	Portable Network Graphics
PSI	Public Service Identifier
RDF	Remote Control Function
SVG	Scalable Vector Graphics
TLS	Transport Layer Security
WAVE	Waveform audio format

Table 1: Events applicable for cross application event handling
System event	Description
`KeyPress`	Generated when a key has been pressed by the user. May also be generated when a key is held down during a key-repeat.
`KeyUp`	Generated when a key pressed by the user has been released.
`KeyDown`	Generated when a key has been pressed by the user.

Table 3: DAE application control codes
Value	Description
`AUTOSTART`	The application is eligible to be started automatically. Sections 5.2.3.1 and 5.2.4.1 above define the order in which AUTOSTART applications are started if more than one is signalled.
`PRESENT`	The OITF shall take no action. The OITF may provide a mechanism to allow the end-user to start applications signalled as PRESENT. However since there is no requirement for such a mechanism, an IPTV service provider who signals applications with this control code shall provide an application able to start them.
`KILL`	The application shall be terminated (see `ApplicationDestroyRequest` in section 7.2.6).
`PREFETCH`	The OITF may start fetching files, data or other information needed to start the application but shall not start the application. Implementations may consider this control code to be the same as `PRESENT`.

Table 5: Key to status column
Status	Description
M	MANDATORY The signalling may be restricted to a subset specified in the "Notes" column. In that case all additional signalling is optional.
O	optional
-	NOT INCLUDED The referenced signalling is not included in this specification.

7. APIs

7.1 Object Factory API

This section defines the methods to check and create an instance of the DAE defined embedded objects within JavaScript.

The OITF shall support a globally accessible object of type "OipfObjectFactory" as a static property "oipfObjectFactory" of the Window interface with the API as defined in this section. The object factory shall ensure that the referenced objects are correctly set up. This is an alternative to instantiating embedded objects (or plug-ins) outside of JavaScript.

The factory object can be accessed as a property of the window object (i.e. window.oipfObjectFactory or oipfObjectFactory).

7.1.1 Methods

Boolean isObjectSupported( String mimeType )

Description This method shall return true if and only if an object of the specified type is supported by the OITF. The method shall return false if the MIME type passed as a parameter is not supported by the client.

Arguments

mimeType

The mimeType may have any of the MIME types defined in tables 1 to 4 of [OIPF_MEDIA2] or any of the DAE defined mime types listed below.

DAE MIME Type
`application/notifsocket`
`application/oipfApplicationManager`
`application/oipfCapabilities`
`application/oipfCodManager`
`application/oipfCommunicationServices`
`application/oipfConfiguration`
`application/oipfDownloadManager`
`application/oipfDownloadTrigger`
`application/oipfDrmAgent`
`application/oipfGatewayInfo`
`application/oipfMDTF`
`application/oipfParentalControlManager`
`application/oipfRecordingScheduler`
`application/oipfRemoteManagement`
`application/oipfSearchManager`
`application/oipfStatusView`
`video/broadcast`

7.1.1.1 Visual Objects

The methods in this section all return HTMLObjectElement objects which can be inserted in the DOM tree. All objects in section which have a visual representation on the screen can be created using methods in this section. Only for objects defined in section , that are supported by the device (i.e. as indicated through the client capability description), a corresponding method name to instantiate the object through the OipfObjectFactory class can be assumed to be present on the oipfObjectFactory object. For any other object, a corresponding method name cannot be assumed to be present.

HTMLObjectElement createVideoBroadcastObject( StringCollection requiredCapabilites )
HTMLObjectElement createVideoMpegObject( StringCollection requiredCapabilites )
HTMLObjectElement createStatusViewObject()

Description

If the object type is supported, each of these methods shall return an instance of the corresponding embedded object.

Since objects do not claim scarce resources when they are instantiated, instantiation shall never fail if the object type is supported. If the method name to create the object is not supported, the OITF shall throw an error with the error.name set to the value "TypeError".

If the object type is supported, the method shall return an HTMLObjectElement equivalent to the specified object. The value of the type attribute of the HTMLObjectElement shall match the mimetype of the instantiated object, for example "application/oipfVideoBroadcast" in case of method oipfObjectFactory.createVideoBroadcastObject().

Arguments

requiredCapabilites

An optional argument indicating the formats to be supported by the resulting player. Each item in the argument shall be one of the formats specified in [OIPF_MEDIA2]. Scarce resources will be claimed by the object at the time of instantiation. The allocationMethod property shall be set STATIC_ALLOCATION. If the OITF is unable to create the player object with the requested capabilities, the method shall return null.

If this argument is omitted, objects do not claim scarce resources so instantiation shall never fail if the object type is supported. The allocationMethod property shall be set to DYNAMIC_ALLOCATION.

7.1.1.2 Non-Visual Objects

The methods in this section all return JavaScript objects which implement the interfaces of their corresponding objects. They can not be inserted in the DOM tree. All objects in chapter 7 which do not have a visual representation on the screen can be created using methods in this section. Only for objects defined in chapter 7, that are supported by the device (i.e. as indicated through the client capability description), a corresponding method name to instantiate the object through the OipfObjectFactory class can be assumed to be present on the oipfObjectFactory object. For any other object, a corresponding method name cannot be assumed to be present.

Object createApplicationManagerObject()
Object createCapabilitiesObject()
ChannelConfig createChannelConfig()
Object createCodManagerObject()
Object createConfigurationObject()
Object createDownloadManagerObject()
Object createDownloadTriggerObject()
Object createDrmAgentObject()
Object createGatewayInfoObject()
Object createIMSObject()
Object createMDTFObject()
Object createNotifSocketObject()
Object createParentalControlManagerObject()
Object createRecordingSchedulerObject()
Object createRemoteControlFunctionObject()
Object createRemoteManagementObject()
Object createSearchManagerObject()

Description

If the object type is supported, each of these methods shall return an instance of the corresponding embedded object. This may be a new instance or existing instance. For example, the object will likely be a global singleton object and calls to this method may return the same instance.

Since objects do not claim scarce resources when they are instantiated, instantiation shall never fail if the object type is supported. If the method name to create the object is not supported, the OITF shall throw an error with name property set to the value "TypeError".

If the object is supported, the method shall return a JavaScript Object which implements the interface for the specified object.

7.1.2 Examples

This section provides examples of the usage of the methods.

The first example shows how to query whether an instance of the A/V Control object for a specified MIME type can be created without the application having to attempt to instantiate the object.

var videoPlayer;
if (window.oipfObjectFactory.isObjectSupported("video/mpeg")) {
  videoPlayer = window.oipfObjectFactory.createVideoMpegObject();
  // append object to document
  document.getElementById('playerDiv').appendChild(videoPlayer);
  videoPlayer.data = "rtsp://server/barker_channel";
}

If the OITF does not support the created object the OITF shall throw an error with the error.name set to the value "TypeError". The example below shows how this can be used by applications:

try {
  configuration = window.oipfObjectFactory.createConfigurationObject();
}
catch (error) {
  alert("application/oipfConfiguration object could not be created - error name: " 
        + error.name + " - error message: " + error.message);
}

7.2 Applications Management APIs

An OITF providing DAE application capability shall implement the behaviour of the classes defined in this section.

7.2.1 The application/oipfApplicationManager embedded object

An OITF shall support a non-visual embedded object of type "application/oipfApplicationManager", with the following JavaScript API, to enable applications to access the privileged functionality related to application lifecycle and management that is provided by the application model defined in this section.

If one of the methods on the application/oipfApplicationManager is called by a webpage that is not a privileged DAE application, the OITF shall throw an error as defined in section 10.1.1.

7.2.1.1 Constants

Name	Value	Use
WIDGET_INSTALLATION_STARTED	0	The Widget installation has started. This state shall be used to indicate that the download of the Widget package is completed (possibly because the Widget was already stored locally) and the OITF is ready to start the Widget installation process. This state shall not be signalled if the package download fails.
WIDGET_INSTALLATION_COMPLETED	1	The Widget installation has completed successfully
WIDGET_INSTALLATION_FAILED	2	The Widget installation has failed either because the Widget package download failed or because, after the download, the Widget installation process failed.
WIDGET_UNINSTALLATION_STARTED	3	The Widget uninstallation has started
WIDGET_UNINSTALLATION_COMPLETED	4	The Widget uninstallation has completed successfully
WIDGET_UNINSTALLATION_FAILED	5	The Widget uninstallation has failed
WIDGET_ERROR_STORAGE_AREA_FULL	10	The local storage device is full
WIDGET_ERROR_DOWNLOAD	11	The Widget cannot be downloaded
WIDGET_ERROR_INVALID_ZIP_ARCHIVE	12	The Widget package is corrupted or is an Invalid Zip Archive (as defined in [Widgets-Packaging] )
WIDGET_ERROR_INVALID_SIGNATURE	13	Widget's Signature Validation failed
WIDGET_ERROR_GENERIC	14	Other reason
WIDGET_ERROR_SIZE_EXCEEDED	15	The Widget exceeded the maximum size for a single widget allowed by the platform, as defined in section 9.1.
WIDGET_ERROR_PERMISSION_DENIED	16	The user and/or the OITF denied the installation or update of a Widget

7.2.1.2 Properties

function onLowMemory( )

The function that is called when the OITF is running low on available memory for running DAE applications. The exact criteria when to generate such an event is implementation specific.

function onApplicationLoaded( Application appl )

The function that is called immediately prior to a load event being generated in the affected application. The specified function is called with one argument appl, which provides a reference to the affected application.

function onApplicationUnloaded( Application appl )

The function that is called immediately prior to an unload event being generated in the affected application. The specified function is called with one argument appl, which provides a reference to the affected application.

function onApplicationLoadError( Application appl )

The function that is called when the OITF fails to load either the file containing the initial HTML document of an application or an XML AIT file (e.g. due to an HTTP 404 error, an HTTP timeout, being unable to load the file from a DSM-CC object carousel or due to the file not being either an HTML file or a XML AIT file as appropriate), All properties of the Application object referred to by appl shall have the value undefined and calling any methods on that object shall fail.

function onWidgetInstallation( WidgetDescriptor wd, Integer state, Integer reason )

The callback function that is called during the installation process of a Widget. The function is called with three arguments:

WidgetDescriptor wd - the WidgetDescriptor for the installed Widget. Some attributes of this argument may not have been initialised and may be null when the function is called until the Widget is successfully installed.
Integer state - the state of the installation; valid values are:
- WIDGET_INSTALLATION_STARTED
- WIDGET_INSTALLATION_COMPLETED
- WIDGET_INSTALLATION_FAILED
  as defined in section 7.2.1.1.
Integer reason - indicates the reason for installation failure. This is only valid if the value of the state argument is WIDGET_INSTALLATION_FAILED otherwise this argument shall be null. Valid values for this field are:
- WIDGET_ERROR_STORAGE_AREA_FULL
- WIDGET_ERROR_DOWNLOAD
- WIDGET_ERROR_INVALID_ZIP_ARCHIVE
- WIDGET_ERROR_INVALID_SIGNATURE
- WIDGET_ERROR_GENERIC
- WIDGET_ERROR_SIZE_EXCEEDED
- WIDGET_ERROR_PERMISSION_DENIED
  as defined in section 7.2.1.1.

function onWidgetUninstallation( WidgetDescriptor wd, Integer state )

The function that is called during the uninstallation process of a Widget. The function is called with two arguments, defined below:

WidgetDescriptor wd - the WidgetDescriptor of the Widget to be uninstalled.
Integer state - the state of the installation; valid values are:
- WIDGET_UNINSTALLATION_STARTED
- WIDGET_UNINSTALLATION_COMPLETED
- WIDGET_UNINSTALLATION_FAILED
  as defined in section 7.2.1.1.

readonly WidgetDescriptorCollection widgets

A collection of WidgetDescriptor objects for the Widgets currently installed on the OITF.

7.2.1.3 Methods

Integer getApplicationVisualizationMode( )

Description

Returns the current mode used by the OITF to visualize applications, whereby a return value:

1	corresponds to the application visualization mode as defined by bullet 1) of 4.4.6, i.e. multiple applications visible simultaneously with DAE applications managing their own size, position and visibility
2	corresponds to the application visualization mode as defined by bullet 2) of 4.4.6, i.e. multiple applications visible simultaneously with OITF managing the size, position, visibility of applications
3	corresponds to the application visualization mode as defined by bullet 3) of 4.4.6, i.e. only a single application visible at any time.

Application getOwnerApplication( Document document )
Description	Get the application that the specified document is part of. If the document is not part of an application, or the calling application does not have permission to access that application, this method will return `null`.
Arguments	document	The document for which the Application object should be obtained.

ApplicationCollection getChildApplications( Application application )
Description	Get the applications that are children of the specified application.
Arguments	application	The application whose children should be returned.

void gc( )
Description	Provide a hint to the execution environment that a garbage collection cycle should be initiated. The OITF is not required to act upon this hint.

void installWidget( String uri )

Description

Attempts to install on the OITF a Widget located at the URI passed. If the Widget is stored on a remote server it shall first be downloaded. This specification does not specify where the OITF stores the Widget package, nor does it define what happens to the original package after the installation process has finished (regardless of whether it succeeded or failed).

When trying to install a Widget with an “id” that collides with the id of an already installed Widget (where the “id” is defined in section 7.6.1 of [Widgets-Packaging] along with the extension defined in section 11.1 of this specification), the OITF should ask the user for confirmation before installing the Widget. The OITF should provide information about the conflict (e.g. the version numbers, if available) to allow the user to decide whether to proceed with the installation or to cancel it.

If the user confirms the installation, then the new Widget shall replace the one already installed; any storage area associated with the replaced Widget shall be retained. Note that the user can also choose to downgrade a Widget, i.e. install an old version of the Widget to replace the installed, more recent, one.

Arguments

uri

The resource locator in form of a URI, which points to a Widget package to be installed.

void uninstallWidget( WidgetDescriptor wd )
Description	Uninstalls a Widget. If this Widget is running it will be stopped. Any storage areas associated with the uninstalled Widget shall be deleted.
Arguments	wd	A WidgetDescriptor object for a Widget installed on the OITF.

7.2.1.4 Events

For the intrinsic events listed in the table below a corresponding DOM event shall be generated in the following manner:

Intrinsic Event	Corresponding DOM event	DOM Event properties
onLowMemory	LowMemory	Bubbles: No Cancellable: No Context Info: None
onApplicationLoaded	ApplicationLoaded	Bubbles: No Cancellable: No Context Info: `appl`
onApplicationUnloaded	ApplicationUnloaded	Bubbles: No Cancellable: No Context Info: `appl`
onApplicationLoadError	ApplicationLoadError	Bubbles: No Cancellable: No Context Info: `appl`
onWidgetInstallation	WidgetInstallation	Bubbles: No Cancellable: No Context Info: `wd`, `state`, `reason`
onWidgetUninstallation	WidgetUninstallation	Bubbles: No Cancellable: No Context Info: `wd`, `state`

NOTE: the above DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving the events listed above during the bubbling or the capturing phase. Applications that use DOM event handlers shall call the addEventListener() method on the application/oipfApplicationManager object. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.2.2 The Application class

The Application class is used to implement the characteristics of a DAE application.

If the document of an application is modified (or even replaced entirely), the Application object shall be retained. This means that the permission set granted when the application is created applies to all “edits” of the document or other pages in the application, until the application is destroyed.

7.2.2.1 Properties

readonly Boolean visible

true if the application is visible, false otherwise. The value of this property is not affected by the application's Z-index or position relative to other applications. Only calls to the show() and hide() methods will affect its value.

readonly Boolean active

true if the application is in the list of currently active applications, false otherwise (as defined in section 4.3.8).

readonly StringCollection permissions

StringCollection object containing the names of the permissions granted to this application.

readonly Boolean isPrimaryReceiver

true if the application receives cross application events before any other application, false otherwise.

readonly Window window

A strict subset of the DOM Window object representing the application. No symbols from the Window object are accessible through this property except the following:

void postMessage( any message, String targetOrigin )

readonly ApplicationPrivateData privateData

Access the current application’s private data object.

If an application attempts to access the privateData property of an Application object for a different application, the OITF shall throw an error as defined in section 10.1.1.

function onApplicationActivated
function onApplicationDeactivated
function onApplicationShown
function onApplicationHidden
function onApplicationPrimaryReceiver
function onApplicationNotPrimaryReceiver
function onApplicationTopmost
function onApplicationNotTopmost
function onApplicationDestroyRequest
function onApplicationHibernateRequest
function onKeyPress
function onKeyUp
function onKeyDown

Each of these event handlers represents a DOM 0 event handler that corresponds to one of the events listed in sections 4.4.7 and 7.2.6

7.2.2.2 Methods

void show( )

Description

If the application visualization mode as defined by method getApplicationVisualizationMode() in section 7.2.1.3, is:

1 : Make the application visible.
2 : Make the application visible. Calling this method from the application itself may have no effect.
3 : Request to make the application visible.

This method only affects the visibility of an application. In the case where more than one application is visible, calls to this method will not affect the z-index of the application with respect to any other visible applications.

void hide( )

Description

If the application visualization mode as defined by method getApplicationVisualizationMode() in section 7.2.1.3, is:

1 : Make the application invisible.
2 : Make the application invisible. Calling this method from the application itself may have no effect.
3 : Request to make the application invisible.

Calling this method has no effect on the lifecycle of the application.

Note: Broadcast independent applications should not call this method. Doing so may result in only the background being visible to the user.

void activateInput( Boolean gainFocus )

Description

Move the application to the front of the active applications list. If the application has been hidden using Application.hide(), this method does not cause the application to be shown. If the application visualization mode as defined by method getApplicationVisualizationMode() in section 7.2.1.3, is:

1 : The application’s Window object shall be moved to the top of the stack of visible applications. In addition, the application’s Window object shall gain input focus if argument gainFocus has value true.
2 : The application’s Window object shall be moved to the top of the stack of visible applications. In addition, the application’s Window object shall gain input focus if argument gainFocus has value true. Calling this method from the application itself may have no effect.
3 : Request to make the application’s Window object visible. Once visible, the application shall be given input focus, irrespective of the value for argument gainFocus.

void deactivateInput( )

Description

Remove the application from the active applications list. This has no effect on the lifecycle of the application and may have no effect on the resources it uses. Applications which are not active will receive no cross-application events, unless their Application object is the target of the event (as for the events defined in section 7.2.6). Applications may still be manipulated via their Application object or their DOM tree.

Application createApplication( String uri, Boolean createChild )
Description	Create a new application and add it to the application tree. Calling this method does not automatically show the newly-created application. This call is asynchronous and may return before the new application is fully loaded. An `ApplicationLoaded` event will be targeted at the Application object when the new application has fully loaded. If the application cannot be created, this method shall return `null`.
Arguments	uri	The URI of the first page of the application to be created or the `localURI` of a Widget as defined in section 7.2.8.1.1
	createChild	Flag indicating whether the new application is a child of the current application. A value of `true` indicates that the new application should be a child of the current application; a value of `false` indicates that it should be a sibling.

void destroyApplication( )
Description	Terminate the application, detach it from the application tree, and make any resources used available to other applications. When an application is terminated, any child applications shall also be terminated.

Application startWidget( WidgetDescriptor wd, Boolean createChild )
Description	Create a Widget installed on the OITF. The behaviour of this method is equivalent to that of Application.createApplication(). The Widget is identified by its WidgetDescriptor. To get a list of the WidgetDescriptor objects for the installed Widgets one can check ApplicationManager.widgets property. If the Widget is already running or fails to start this call will return `null`.
Arguments	wd	a WidgetDescriptor object for a Widget installed on the OITF.
	createChild	Flag indicating whether the new application is a child of the current application. A value of `true` indicates that the new application should be a child of the current application; a value of `false` indicates that it should be a sibling.

Application stopWidwet( WidgetDescriptor wd )

Description

Terminate a running Widget. The behaviour of this method is equivalent to that of Application.destroyApplication().

Calling this method will detach the Widget from the application tree, and make any resources used available to other applications. When a Widget is terminated, any child applications shall also be terminated.

Arguments wd a WidgetDescriptor object for a Widget installed on the OITF.

7.2.3 The ApplicationCollection class

typedef Collection<Application> ApplicationCollection

The ApplicationCollection class represents a collection of Application objects. See Annex K for the definition of the collection template.

7.2.4 The ApplicationPrivateData class

7.2.4.1 Properties

readonly Keyset keyset

The object representing the user input events sent to the DAE application.

readonly Channel currentChannel

For a broadcast-related application, the value of the property contains the channel whose AIT is currently controlling the lifecycle of this application. If no channel is being presented, or if the application is not broadcast-related, the value of this property shall be null.

readonly Boolean wakeupApplication

The wakeupApplication property is set if there has been a prepareWakeupApplication() request by that application.

readonly Boolean wakeupOITF

The wakeupOITF property is set if there has been a call to the prepareWakeupOITF() method.

7.2.4.2 Methods

Integer getFreeMem( )

Description

Let application developer query information about the current memory available to the application. This is used to help during application development to find application memory leaks and possibly allow an application to make decisions related to its caching strategy (e.g. for images).

Returns the available memory to the application or -1 if the information is not available.

For example:

var app = appman.getOwnerApplication(window.document);
debug("[APP] free mem = " + app.privateData.getFreeMem() + "\n");

Boolean prepareWakeupApplication( String URI, String token, Date time )
Description	The `prepareWakeupApplication()` method allows the DAE application to set-up the OITF to wake-up at a specified time. The wake-up is limited to the OITF being in the `PASSIVE_STANDBY` state at the specified time. If the timer expires while the DAE application is in a different state it is silently ignored. Only one wake-up is to be supported for a DAE application. If a previous wake-up request had been registered it shall be overwritten. If the wake-up fails to be set-up this operation shall return `false`. Failure may be due to OITF expecting to change to an `OFF` power state which would not allow the wake-up request to survive.
Arguments	URI	The URI from which the content can be fetched.
	token	The token is a string which the application may retrieve with clearWakeupToken().
	time	The time when the wake-up is to occur.

Boolean prepareWakeupOITF( Date time )

Description

The prepareWakeupOITF() method allows the DAE application to set-up the OITF to wake-up at a specified time. The wake-up is limited to the OITF being in the PASSIVE_STANDBY or PASSIVE_STANDBY_HIBERNATE state at the specified time. If the timer expires while the DAE application is in a different state it is silently ignored.

Unlike prepareWakeupApplication() this method applies to all the DAE applications and not limited to a single DAE application.

If the wake-up fails to be set-up this operation shall return false. Failure may be due to OITF expecting to change to an OFF power state which would not allow the wake-up request to survive.

Arguments time The time when the wake-up is to occur.

String clearWakeupToken( )
Description	The `clearWakeupToken()` method shall return the token set in prepareWakeupApplication() method. The wake-up token should be cleared once it is read in order to limit usage to only when the DAE application starts up.

7.2.5 The Keyset class

The Keyset object permits applications to define which key events they request to receive. There are two means of defining this. Common key events are represented by constants defined in this class which are combined in a bit-wise mask to identify a set of key events. Less common key events are not included in one of the defined constants and form part of an array.

The supported key events indicated through the capability mechanism in section 9.3 shall be the same as the maximum set of key events available to the browser as indicated through this object.

The default set of key events available to broadcast-related applications shall be none. The default set of key events available to broadcast-independent or service provider related applications which do not call Keyset.setValue() shall be all those indicated by the constants in this class which are supported by the OITF excluding those indicated by OTHER.

7.2.5.1 Constants

Constant name	Numeric Value	Use
RED	0x1	Used to identify the `VK_RED` key event.
GREEN	0x2	Used to identify the `VK_GREEN` key event.
YELLOW	0x4	Used to identify the `VK_YELLOW` key event.
BLUE	0x8	Used to identify the `VK_BLUE` key event.
NAVIGATION	0x10	Used to identify the `VK_UP`, `VK_DOWN`, `VK_LEFT`, `VK_RIGHT`, `VK_ENTER` and `VK_BACK` key events.
VCR	0x20	Used to identify the `VK_PLAY`, `VK_PAUSE`, `VK_STOP`, `VK_NEXT`, `VK_PREV`, `VK_FAST_FWD`, `VK_REWIND`, `VK_PLAY_PAUSE` key events.
SCROLL	0x40	Used to identify the `VK_PAGE_UP` and `VK_PAGE_DOWN` key events.
INFO	0x80	Used to identify the `VK_INFO` key event.
NUMERIC	0x100	Used to identify the number events, 0 to 9.
ALPHA	0x200	Used to identify all alphabetic events.
OTHER	0x400	Used to indicate key events not included in one of the other constants in this class.

7.2.5.2 Properties

readonly Integer value

The value of the keyset which this DAE application will receive.

readonly Integer otherKeys[ ]

If the OTHER bit in the value property is set then this indicates those key events which are available to the browser which are not included in one of the constants defined in this class, If the OTHER bit in the value property is not set then this property is meaningless.

readonly Integer maximumValue

In combination with maximumOtherKeys, this indicates the maximum set of key events which are available to the browser. When a bit in this maximumValue has value 0, the corresponding key events are never available to the browser.

readonly Integer maximumOtherKeys[ ]

If the OTHER bit in the maximumValue property is set then, in combination with maximumValue, this indicates the maximum set of key events which are available to the browser. For key events which are not included in one of the constants defined in this class, if they are not listed in this array then they are never available to the browser. If the OTHER bit in the value property is not set then this property is meaningless.

Boolean supportsPointer

Applications that have been designed to handle Mouse Events can express it by using this property.

Applications shall set this property to true to indicate that they support a pointer based interaction model, i.e. that they listen to and handle Mouse Events as included in the Web Standards TV profile [OIPF_WSTVP2]. They shall set it to false otherwise. If not set, an OITF shall assume that the application does not support a pointer based interaction model.

Based on the value of this property, an OITF may decide to enable or disable the rendering of a free moving cursor.

Note: OITFs are not required to support a pointer based input device even though they are recommended to do so. If pointer based input devices are supported, this is expressed via the +POINTER UI Profile fragment as described in section 9.2

7.2.5.3 Methods

Integer setValue( Integer value, Integer otherKeys[ ] )
Description	Sets the value of the keyset which this DAE application requests to receive. Where more than one DAE application is running, the events delivered to the browser shall be the union of the events requested by all running DAE applications. Under these circumstances, applications may receive events which they have not requested to receive. The return value indicates which keys will be delivered to this DAE application encoded as bit-wise mask of the constants defined in this class.
Arguments	value	The value is a number which is a bit-wise mask of the constants defined in this class. For example; myKeyset = myApplication.privateData.keyset; myKeyset.setValue(0x00000013); myKeyset.setValue(myKeyset.INFO \| myKeyset.NUMERIC);
	otherkeys	This parameter is optional. If the value parameter has the OTHER bit set then it is used to indicate the key events that the application wishes to receive which are not represented by constants defined in this class.

String getKeyIcon( Integer code )
Description	Return the URI of the icon representing the physical key or other mechanism that is used by the terminal to generate the key event for the given keycode passed. It shall return `null` if the key has no icon associated with it.
Arguments	code	The `VK_` constant for the key whose icon should be returned.

String getKeyLabel( Integer code )
Description	Return the textual label representing the physical key or other mechanism that is used by the terminal to generate the key event for the given keycode passed. It shall return `null` if the key has no icon associated with it.
Arguments	code	The `VK_` constant for the key whose textual label should be returned.

7.2.6 New DOM events for application support

New events have been created that are raised on the Application objects in the application tree. These are normal events, not cross-application events, and are used to indicate changes in the state of an application.

Table 6: New DOM events for application support
Event	Description
`ApplicationActivated`	Issued when an application focus change occurs to inform the recipient of the event that the application is now focussed.
`ApplicationDeactivated`	Issued when an application focus change occurs to inform the recipient of the event that the application is now no longer focussed.
`ApplicationShown`	Issued when an application has become visible.
`ApplicationHidden`	Issued when an application has become hidden.
`ApplicationPrimaryReceiver`	This event is issued to indicate that the target is now at the front of the active application list.
`ApplicationNotPrimaryReceiver`	This event is issued to indicate that the target is no longer at the front of the active application list.
`ApplicationTopmost`	This event is issued to indicate that the target is now the topmost (i.e. it has the highest Z-index and is not obscured by any other visible applications, for OITFs where multiple applications are visible simultaneously.
`ApplicationNotTopmost`	This event is issued to indicate that the target is no longer at the topmost application. For OITFs where only one application is visible at a time, this event indicates that the application is no longer visible to the user.
`ApplicationDestroyRequest`	This event is issued to indicate that the target application is about to be terminated. It is not issued when an application calls destroyApplication() method for itself (i.e. to exit itself). Non-responsive applications should be forcibly terminated by the OITF, including the case where listeners for ApplicationDestroyRequest events do not return promptly. The determination of when an application is "non-responsive" is terminal-specific. If an application does not register a listener for this event and there is a need for the system to terminate the application, then the application shall be terminated immediately.
`ApplicationHibernateRequest`	This event is issued to indicate that the OITF is about to enter a hibernate mode. The OITF shall start a short watchdog timer (e.g. 2 seconds). During this period the application may take any actions (for example to store the currently viewed channel in case of an unsuccessful start-up).

These events do not bubble and cannot be cancelled. Each of these events has a corresponding DOM 0 event handler property on the Application object.

7.2.7 Examples (informative)

The examples below illustrate some aspects of the application model.

7.2.7.1 Locating the Application object

The ApplicationManager class provides the getOwnerApplication() method, which returns the document's owning application node:

 
// Assumes that the application/oipfApplicationManager object has the ID 
// “applicationmanager”
var appMgr = document.getElementById( "applicationmanager" );
var self = appMgr.getOwnerApplication( Window.document );

All other application functionality is available from this object.

7.2.7.2 Creating a new application

Creating a new application is a simple matter of creating a new Application object.

// Assumes that the application/oipfApplicationManager object has the ID 
// “applicationmanager”
var appMgr = document.getElementById( "applicationmanager" );
var self = appMgr.getOwnerApplication( Window.document );
var child = self.createApplication( url_of_application, true );

A typical requirement on an application is to only become visible once it has fully loaded. To do this, it can take advantage of load events. Here is an example from a clock application, which wants to load an image to become the background of the clock, upon which it can write the text of the clock.

<script>
function loaded() {

    var screen = document.defaultView.screen;
    var clock = document.getElementById( 'clock' );

    setup_clock( clock.width, clock.height );

    // Assumes that the application/oipfApplicationManager object has the ID 
    // “applicationmanager”
    var appMgr = document.getElementById( "applicationmanager" );
    var self = appMgr.getOwnerApplication( Window.document );
    self.show();
}
</script>

<style> * { margin: 0cm } </style>

<body onload="loaded()">
   <img id="clock" src="clockbackground.png" style="position: absolute; 
     top: 0px; left=0px">
</body>

7.2.8 Widget APIs

This section defines APIs an author can use to interact with Widgets installed on the OITF. Note that the Widget lifecycle is managed through the application manager as defined in the previous sections.

7.2.8.1 The WidgetDescriptor class

The WidgetDescriptor class is used to implement the characteristics of a DAE Widget. It extends the Widget interface defined in section 11.3 of this specification with the properties below.

7.2.8.1.1 Properties

readonly String localURI

The URI of the installed Widget. It can be used as an argument to ApplicationManager.createApplication() to run the Widget. The value of this property should not represent the actual location of the Widget on the OITF’s local storage.

readonly String downloadURI

The URI of the location from where the Widget package was downloaded. This property shall match the URI used as argument of createApplication() or installWidget() when installing the Widget.

readonly StringCollection defaultIcon

A collection of URI strings for all the available default icons. Default icons are defined in [Widgets-Packaging]. This collection only contains URIs for the icons currently available in the Widget package.

readonly StringCollection customIcons

A collection of URI strings for all the custom icons of the current Widget. Custom icons are defined in [Widgets-Packaging].

readonly Boolean running

This flag indicates the running state of the Widget.

7.2.8.1.2 Clarifications

The WidgetDescriptor class is used to identify an installed Widget regardless of whether it is running or not, and so some clarification on the attribute values defined for the Widget interfaces [Widgets-APIs] is needed. The attributes height and width are defined in [Widgets-APIs] on the "Widget instance’s viewport". When the Widget is not running those attributes shall take the value defined in the Widget Manifest (if any) otherwise they shall be null. When the Widget is running these attributes shall adhere to what is defined in [Widgets-APIs].

7.2.8.2 The WidgetDescriptorCollection class

typedef Collection<WidgetDescriptor> WidgetDescriptorCollection

The WidgetDescriptorCollection class represents a collection of WidgetDescriptor objects. See Annex K for the definition of the collection template.

7.3 Configuration and setting APIs

This section defines the interface to configuration and user settings information. Hardware configuration of the OITF is managed via an instance of the LocalSystem object. This provides access to hardware information and provides an entry point to configure the outputs and network interfaces of the OITF. Settings relating to the user interface and behaviour of the platform software are managed via an instance of the Configuration object.

This section is subject to security control, (see section 10.1.3.7) and only applies if <configurationChanges> has value true.

7.3.1 The application/oipfConfiguration embedded object

The OITF shall implement the “application/oipfConfiguration” object as defined below. This object provides an interface to the configuration and user settings facilities within the OITF.

7.3.1.1 Properties

readonly Configuration configuration

Accesses the configuration object that sets defaults and shows system settings.

readonly LocalSystem localSystem

Accesses the object representing the platform hardware.

function onIpAddressChange( NetworkInterface item, String ipAddress )

The function that is called when the IP address of a network interface has changed. The specified function is called with two arguments item and ipAddress. The ipAddress may have the value undefined if a previously assigned address has been lost.

7.3.1.2 Events

For the intrinsic event “onIpAddressChange”, a corresponding DOM event shall be generated, in the following manner:

Intrinsic Event	Corresponding DOM event	DOM Event properties
onIpAddressChange	IpAddressChange	Bubbles: No Cancellable: No Context Info: `item`, `ipAddress`

NOTE: the above DOM event is directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving an IpAddressChange event during the bubbling or the capturing phase. Applications that use DOM event handlers shall call the addEventListener() method on the application/oipfConfiguration object. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.3.2 The Configuration class

The Configuration object allows configuration items within the system to be read and modified. This includes settings such as audio and subtitle languages, display aspect ratios and other similar settings. Unlike the LocalSystem object, this is concerned with software- and application-related settings rather than hardware configuration and control.

7.3.2.1 Properties

String preferredAudioLanguage

A comma-separated set of languages to be used for audio playback, in order of preference.

Each language shall be indicated by its ISO 639-2 language code as defined in [ISO639-2].

String preferredSubtitleLanguage

A comma-separated set of languages to be used for subtitle playback, in order of preference. The subtitle component (see section 7.16.5.5) that matches the highest ordered language shall be activated (equivelant to the selectComponent method) and all other subtitle components shall be deactivated (equivelant to the unselectComponent method).

Each language shall be indicated by its ISO 639-2 language code as defined in [ISO639-2] or as a wildcard specifier "***".

If the wildcard is included it shall be the last item in the set. If no subtitle component in the content matches a language in this property and the wildcard is included then the first (lowest) subtitle component shall be selected.

String preferredUILanguage

A comma-separated set of languages to be used for the user interface of a service, in order of preference.

Each language shall be indicated by its ISO 639-2 language code as defined in [ISO639-2].

If present, the HTTP Accept-language header shall contain the same languages as the preferredUILanguage property with the same order of preference. NOTE: The order of preference in the Accept-language header is indicated using the quality factor.

String countryId

An ISO-3166 three character country code identifying the country in which the receiver is deployed.

Integer regionId

An integer indicating the time zone within a country in which the receiver is deployed. A value of 0 shall represent the eastern-most time zone in the country, a value of 1 shall represent the next time zone to the west, and so on.

Valid values are in the range 0 – 60.

Integer pvrPolicy

The policy dictates what mechanism the system should use when storage space is exceeded.

Valid values are shown in the table below.

Value	Description
0	Indicates a recording management policy where no recordings are to be deleted.
1	Indicates a recording management policy where only watched recordings may be deleted.
2	Indicates a recording management policy where only recordings older than the specified threshold (given by the pvrSaveDays and pvrSaveEpisodes properties) may be deleted.

Integer pvrSaveEpisodes

When the pvrPolicy property is set to the value 2, this property indicates the minimum number of episodes that shall be saved for series-link recordings.

Integer pvrSaveDays

When the pvrPolicy property is set to the value 2, this property indicates the minimum save time (in days) for individual recordings. Only recordings older than the save time may be deleted.

Integer pvrStartPadding

The default padding (measured in seconds) to be added at the start of a recording.

Integer pvrEndPadding

The default padding (measured in seconds) to be added at the end of a recording.

Integer preferredTimeShiftMode

The time shift mode indicates the preferred mode of operation for support of timeshift playback in the video/broadcast object. Valid values are defined in the timeShiftMode property in section 7.13.2.2. The default value is 0, timeshift is turned off.

7.3.2.2 Methods

String getText( String key )
Description	Get the system text string that has been set for the specified key.
Arguments	key	A key identifying the system text string to be retrieved.

String setText( String key, String value )

Description

Set the system text string that has been set for the specified key. System text strings are used for automatically-generated messages in certain cases, e.g. parental control messages.

Arguments

key

A key identifying the system text string to be retrieved.

Key

Description

no_title

Text string used as the title for programmes and channels where no guide information is available.

Defaults to “No information”

no_synopsis

Text string used as the synopsis for programmes where no guide information is available.

Defaults to “No further information available”

manual_recording

Text string used to identify a manual recording.

Defaults to “Manual Recording”

value

The new value for the system text string.

7.3.3 The LocalSystem class

The LocalSystem object allows hardware settings related to the local device to be read and modified.

Note: The standbyState property has been removed from this class.

7.3.3.1 Constants

The following values are defined for the standby state of the OITF:

Name	Value	Use
OFF	0	The OITF is in the off state and no power is consumed. This is the case of a power outage or if the OITF has the ability to be completely turned off. Scheduled recording is not expected to work.
ON	1	The OITF is in normal working mode with user interaction. The DAE applications may render any presentation graphically.
PASSIVE_STANDBY	2	The OITF is in the lowest possible power consumption state (meeting regulations and certifications). The OITF may support wake-up from a passive standby in order, for example, to perform a scheduled recording.
ACTIVE_STANDBY	3	The OITF is in an intermediate power consumption state. The output to the display shall be inactive. In this state DAE applications may continue to operate.
PASSIVE_STANDBY_HIBERNATE	4	The OITF is in the lowest possible power consumption state (meeting regulations and certifications). If the platform supports hibernate mode then the OITF stores all applications in volatile memory to allow for quick startup.
RESTART	5	The OITF shall restart and return to a ON state.
FACTORY_RESET	6	Restart the OITF and reset all settings and data to an initial/factory state. The exact settings and data to be reset are implementation dependant. The use of the this operation with the setPowerState method is subject to security control defined in section 10.1.3.8

The following values are defined for the startup URL of the OITF:

Name	Value	Use
STARTUP_URL_NONE	0	No startup URL is known.
STARTUP_URL_DHCP	1	The startup URL is derived from DHCP procedures.
STARTUP_URL_TR069	2	The startup URL is derived through TR-069 procedures.
STARTUP_URL_PRECONFIGURED	3	The startup URL is that which is configured through the OITF firmware.
STARTUP_URL_OTHER	9	The startup URL is obtained through other (perhaps non-standardized) procedures.

7.3.3.2 Properties

readonly String deviceID

Private OITF Identifier. This property shall take the value undefined except when accessed by applications meeting either of the following criteria:

The application is signalled in an SD&S service provider discovery record with an application usage of urn:oipf:cs:ApplicationUsageCS:2009:hni-igi where the SD&S service provider discovery record was obtained by the OITF through the procedure defined in section 5.4.1.2 of [OIPF_PROT2].
The R2v2.3 version of the Metadata specification defines these as :2010
The URL of the application was discovered directly through the procedure defined in section 5.4.1.2 of [OIPF_PROT2].

In these two cases, it shall take the same value as defined for the DHCP client identifier in DHCP option 61 in section 12.1.1.1 of [OIPF_PROT2].

readonly Boolean systemReady

Indicates whether the system has finished initialising. A value of true indicates that the system is ready.

readonly String vendorName

String identifying the vendor name of the device.

readonly String modelName

String identifying the model name of the device.

readonly String familyName

String identifying the name of the family that the device belongs to. Devices in a family differ only by details that do not impact the behaviour of the OITF aspect of the device, e.g. screen size, remote control, number of HDMI ports, size of hard disc. Family names are allocated by the vendor and the combination of vendorName and familyName should uniquely identify a family of devices. Different vendors may use the same familyName, although they are recommended to use conventions that avoid this.

readonly String softwareVersion

String identifying the version number of the platform firmware.

readonly String hardwareVersion

String identifying the version number of the platform hardware.

readonly String serialNumber

String containing the serial number of the platform hardware.

readonly Integer releaseVersion

Release version of the OIPF specification implemented by the OITF.

For instance, if the OITF implements release 2 version “1.0”, this property should be set to 2.

readonly Integer majorVersion

Major version of the OIPF specification implemented by the OITF.

For instance, if the OITF implements release 2 version “2.0”, this property should be set to 2.

readonly Integer minorVersion

Minor version of the OIPF specification implemented by the OITF.

For instance, if the OITF implements release 2 version “2.0”, this property should be set to 0.

readonly String oipfProfile

Profile of the OIPF specification implemented by the OITF. Values of this field are not defined in this specification.

readonly Boolean pvrEnabled

Flag indicating whether the platform has PVR capability (local PVR).

Note: This property is deprecated in favour of the pvrSupport property.

readonly Boolean ciplusEnabled

Flag indicating whether the platform has CI+ capability.

readonly Integer powerState

The powerState property provides the DAE application the ability to determine the current state of the OITF. The property is limited to the ACTIVE_STANDBY or ON states.

readonly Integer previousPowerState

The previousPowerState property provides the DAE application the ability to retrieve the previous state.

readonly Integer timeCurrentPowerState

The time that the OITF entered the current power state. The time is represented in seconds since midnight (GMT) on 1/1/1970.

function onPowerStateChange( Integer powerState )

The function that is called when the power state has changed. The specified function is called with the argument powerState:

Integer powerState – the new power state.

Integer volume

Get or set the overall system volume. Valid values for this property are in the range 0 - 100. The OITF shall store this setting persistently.

Boolean mute

Get or set the mute status of the default audio output(s). A value of true indicates that the default output(s) are currently muted.

readonly AVOutputCollection outputs

A collection of AVOutput objects representing the audio and video outputs of the platform. Applications may use these objects to configure and control the available outputs.

readonly NetworkInterfaceCollection networkInterfaces

A collection of NetworkInterface objects representing the available network interfaces.

readonly TunerCollection tuners

A collection of Tuner objects representing the physical tuners available in the OITF.

readonly Integer tvStandardsSupported

Get the TV standard(s) which are supported on the analogue video outputs.

This property can take one or more of the following values:

Value	Description
1	Indicates platform support for the NTSC TV standard.
2	Indicates platform support for the PAL-BGH TV standard.
4	Indicates platform support for the SECAM TV standard.
8	Indicates platform support for the PAL-M TV standard.
16	Indicates platform support for the PAL-N TV standard.

Values are stored as a bitfield.

readonly Integer tvStandard

Get the TV standard for which the analogue video outputs are currently configured.

This property can take one or more of the following values:

Value	Description
0	Indicates there are no analogue video outputs.
1	Indicates platform support for the NTSC TV standard.
2	Indicates platform support for the PAL-BGH TV standard.
4	Indicates platform support for the SECAM TV standard.
8	Indicates platform support for the PAL-M TV standard.
16	Indicates platform support for the PAL-N TV standard.

Values are stored as a bitfield.

readonly Integer pvrSupport

Flag indicating the type of PVR support used by the application. This property may take zero or more of the following values:

Value	Description
0	PVR functionality is not supported. This is the default value if `<recording>` as specified in section 9.3.3 has value `false`.
1	PVR functionality is supported in the OITF. This is the default value if `<recording>` as specified in section 9.3.3 has value `true`.

Values are stored as a bitfield.

readonly StartupInformation startupInformation

Indicates any information used at startup time of the OITF.

function onStartupInfoChange( StartupInformation startupInfo )

The function that is called when any property in the startup information is changed.

The specified function is called with the argument startupInfo:

StartupInformation startupInfo – the new startup information.

7.3.3.3 Methods

Boolean setScreenSize( Integer width, Integer height )
Description	Set the resolution of the graphics plane. If the specified resolution is not supported by the OITF, this method shall return `false`. Otherwise, this method shall return `true`.
Arguments	width	The width of the display, in pixels.
	height	The height of the display, in pixels.

Boolean setTVStandard( Integer tvStandard )
Description	Set the TV standard to be used on the analogue video outputs. Returns `false` if the requested mode cannot be set.
Arguments	tvStandard	The TV standard to be set. Valid values are defined in the description of the tvStandard property in section 7.3.3.2.

Integer setPvrSupport( Integer state )

Description Set the type of PVR support used by the application. The types of PVR supported by the receiver may not be supported by the application; in this case, the return value indicates the pvr support that has been set.

Arguments

state

The type of PVR support desired by the application. More than one type of PVR functionality may be specified, allowing the receiver to automatically select the appropriate mechanism. Valid values are:

Value	Description
0	PVR functionality is not supported. This is the default value if `<recording>` as specified in section 9.3.3 has value `false`.
1	PVR functionality is supported in the OITF. This is the default value if `<recording>` as specified in section 9.3.3 has value `true`.

Values are stored as a bitfield.

Boolean setPowerState( Integer type )

Description

The setPowerState() method allows the DAE application to modify the OITF state.

The power state change may be restricted for some values of type, for example OFF, PASSIVE_STANDBY, RESTART and FACTORY_RESET. A call to setPowerState() with a restricted value of type shall return false.

Arguments type The type values that may be specified are defined in section 7.3.3.1

Boolean setDigestCredentials( String protocol, String domain, String username, String password )
Description	Set the credentials for the specified protocol to use for digest authentication negotiation for all subsequent requests to the specified domain. The credentials are persistently stored overwriting any previous set credentials. If domain is null the provided credentials shall apply for all domains. Returns `true` if credentials are successfully set, `false` otherwise. If digest authentication is not supported for the specified protocol then return `false`. The valid values are the strings “`http`” and “`https`”. Setting of Digest Credentials on the same protocol and domain shall update the username and password. If the credentials, when used, are incorrect then the behaviour shall be the same as any other time that stored credentials are incorrect, e.g. saved values from a user prompt. The credentials shall be used (if necessary) in all requests made by DAE applications. The credentials may be used in requests made by other components such as media players, DLNA clients, etc.
Arguments	protocol	The protocol to apply the credentials.
	domain	The domain to which the credentials apply.
	username	The username to be used in the digest authentication.
	password	The password to be used in the digest authentication.

Boolean clearDigestCredentials( String protocol, String domain )
Description	Clear any previously set digest credentials for the specified domain. If domain is `null` all set credentials are cleared. Returns `true` if the digest credentials for the given `protocol` and `domain` were cleared or do not exist, or `false` if credentials failed to be cleared.
Arguments	protocol	The protocol to apply the credentials. The value should be the same as one of those specified for the setDigestCredentials() method.
	domain	The domain to which the credentials apply.

Boolean hasDigestCredentials( String protocol, String domain )
Description	Check if digest credentials are currently defined for the specified protocol and domain. Returns `true` if credentials have been set by a previous call to setDigestCredentials(), otherwise returns `false`.
Arguments	protocol	The protocol to apply the credentials. The value should be the same as one of those specified for the setDigestCredentials() method.
	domain	The domain to which the credentials apply.

7.3.3.4 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated in the following manner:

Intrinsic Event	Corresponding DOM event	DOM Event properties
onPowerStateChange	PowerStateChange	Bubbles: No Cancellable: No Context Info: `powerState`
onStartupInfoChange	StartupInfoChange	Bubbles: No Cancellable: No Context Info: `startupInfo`

7.3.4 The NetworkInterface class

The NetworkInterface class represents a physical or logical network interface in the receiver.

7.3.4.1 Properties

readonly String ipAddress

The IP address of the network interface, in dotted-quad notation for IPv4 or colon-hexadecimal notation for IPv6. This property shall take the value undefined if no IP address has been assigned. The IP address may be link local, private or global, depending on which address block it belongs to, as reserved by IANA.

readonly String macAddress

The colon-separated MAC address of the network interface.

readonly Boolean connected

Flag indicating whether the network interface is currently connected.

Boolean enabled

Flag indicating whether the network interface is enabled. Setting this property shall enable or disable the network interface.

7.3.5 The AVOutput class

The AVOutput class represents an audio or video output on the local platform.

7.3.5.1 Properties

readonly String name

The name of the output. Each output shall have a name that is unique on the local system. At least one of the outputs shall have the name "all" and shall represent all available outputs on the platform. The results of reading properties from the "all" AVOutput are implementation specific.

readonly String type

The type of the output. Valid values are “audio”, “video”, or “both”.

Boolean enabled

Flag indicating whether the output is enabled. Setting this property shall enable or disable the output.

Boolean subtitleEnabled

Flag indicating whether the subtitles are enabled. The language of the displayed subtitles is determined by a combination of the value of the Configuration.preferredSubtitleLanguage property (see section 7.3.2) and the subtitles available in the stream. For audio outputs, setting this property will have no effect.

String videoMode

Read or set the video format conversion mode, for which hardware support may be available on the device. Valid values are:

normal
stretch
zoom

The following table provides guidance as to the relationship between videoMode, aspectRatio (output) and the aspectRatio (input) of the AVVideoComponent class.

aspectRatio (input/output) value	videoMode value
aspectRatio (input/output) value	Normal	Stretch	Zoom
16:9 input / 4:3 output	Black bars at top and bottom, all video visible	No black bars, picture stretched vertically	No black bars, picture clipped on left and right sides
4:3 input / 16:9 output	Black bars on left and right, all video visible	No black bars, picture stretched horizontally	No black bars, picture clipped top and bottom
4:3 input / 4:3 output	No change	No change	No change
16:9 input / 16:9 output	No change	No change	No change

The DAE application graphical layer is unaffected by the videoMode.

For audio-only outputs, setting this property shall have no effect.

String digitalAudioMode

Read or set the output mode for digital audio outputs for which hardware support may be available on the device. Valid values are shown below.

Value	Behaviour
`ac3`	Output AC-3 audio.
`uncompressed`	Output uncompressed PCM audio.

For video-only outputs, setting this property shall have no effect.

String audioRange

Read or set the range for digital audio outputs for which hardware support may be available on the device. Valid values are shown below

Value	Behaviour
`normal`	Use the normal audio range.
`narrow`	Use a narrow audio range.
`wide`	Use a wide audio range.

For video-only outputs, setting this property shall have no effect.

String hdVideoFormat

Read or set the video format for HD and 3D video outputs for which hardware support may be available on the device. Valid values are:

480i
480p
576i
576p
720i
720p
1080i
1080p
720p_TaB
720p_SbS
1080i_SbS
1080p_TaB
1080p_SbS

For audio-only or standard-definition outputs, setting this property shall have no effect.

String tvAspectRatio

Indicates the output display aspect ratio of the display device connected to this output for which hardware support may be available on the device. Valid values are:

4:3
16:9

For audio-only, setting this property shall have no effect.

readonly StringCollection supportedVideoModes

Read the video format conversion modes that may be used when displaying a 4:3 input video on a 16:9 output display or 16:9 input video on a 4:3 output display. The assumption is that the hardware supports conversion from either format and there is no distinction between the two. See the definition of the videoMode property for valid values.

For audio outputs, this property will have the value null.

readonly StringCollection supportedDigitalAudioModes

Read the supported output modes for digital audio outputs. See the definition of the digitalAudioMode property for valid values.

For video outputs, this property will have the value null.

readonly StringCollection supportedAudioRanges

Read the supported ranges for digital audio outputs. See the definition of the audioRange property for valid values.

For video outputs, this property will have the value null.

readonly StringCollection supportedHdVideoFormats

Read the supported HD and 3D video formats. See the definition of the hdVideoFormat property for valid values.

For audio outputs, this property will have the value null.

readonly StringCollection supportedAspectRatios

Read the supported TV aspect ratios. See the definition of the tvAspectRatio property for valid values.

For audio outputs, this property will have the value null.

readonly Integer current3DMode

Read whether the display is currently in a 2D or 3D mode. Return values are:

Value	Description
0	The display is in a 2D video mode
1	The display is in a 3D video mode

function on3DModeChange( Integer action )

This function is the DOM 0 event handler for events relating to actions carried out on an item in a content catalogue. The specified function is called with the following arguments:

Integer action - The type of action that the event refers to. Valid values are:

Value Description

0 The display changed from a 3D to a 2D video mode

1 The display changed from a 2D to a 3D video mode

7.3.5.2 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated, in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
on3DModeChange	3DModeChange	Bubbles: No Cancellable: No Context Info: `action`

7.3.6 The NetworkInterfaceCollection class

typedef Collection<NetworkInterface> NetworkInterfaceCollection

The NetworkInterfaceCollection class represents a collection of NetworkInterface objects. See Annex K for the definition of the collection template.

7.3.7 The AVOutputCollection class

typedef Collection<AVOutput> AVOutputCollection

The AVOutputCollection class represents a collection of AVOutput objects. See Annex K for the definition of the collection template.

7.3.8 The TunerCollection class

typedef Collection<Tuner> TunerCollection

The TunerCollection class represents a collection of Tuner objects. See Annex K for the definition of the collection template.

7.3.9 The Tuner class

A Tuner object represents the source of broadcast content provided through a physical tuner in the OITF. Each Tuner object is represented by a <video_broadcast> element in the capability description as defined in section 9.3.1.

A Tuner object that is capable of tuning at the same time to multiple transponders shall have the nrstreams attribute of the <video_broadcast> element set to a value equal to the number of transponders.

A Tuner object that is capable of tuning to transponders of different types shall include all those types in the types attribute of the <video_broadcast> element.

NOTE: An OITF may contain a physical tuner that has its capabilities split into multiple Tuner objects to fit the restrictions on the <video_broadcast> element outlined above and in section 9.3.1.

7.3.9.1 Properties

readonly Integer id

A unique identifier of the tuner.

readonly String name

The name of the tuner as designated in OITF.

readonly IntegerCollection idTypes

Returns a collection of the types supported by the tuner. The types are according to the ID types in section 7.13.11.1 under Channel object.

Boolean enableTuner

The property enables (true) and disables (false) the tuner. Reading the property provides the current state, enabled or disabled. Attempting to disable the tuner while the resource is in use has no effect and the tuner shall continue to be enabled. While disabled:

any external power feed (if applicable) shall be turned off;
the value of the signalInfo property is not defined;
the value of the lnbInfo property is not defined;
the tuner shall not be available for use by any JavaScript object (e.g. the video/broadcast object) or by the underlying OITF system (e.g. to perform a scheduled recording). Note the property enableTuner is available in order to re-enable the tuner and get access to the tuner again.

The set value of the property shall persist after OITF restarts.

readonly SignalInfo signalInfo

The property returns a SignalInfo object with signal information for example signal strength.

readonly LNBInfo lnbInfo

The property returns a LNBInfo object with information regarding the LNB associated with the tuner.

readonly Integer frontEndPosition

Indicates the physical interface associated with the tuner.

Boolean powerOnExternal

The property turns on (true) and off (false) the power applied to the external interface of the tuner unless the tuner is disabled. Reading the property provides the current value, on or off. Attempting to modify the property while the resource is in use has no effect. The value of the property shall persist after OITF restarts.

For DVB-S/S2 power is supplied to the LNB(s) and if present the DiSEqC switch.

For DVB-T/T2 a supply +5V is supplied to the antenna with built in amplifier. Note that applying power may have adverse effects to the external equipment if it has its own power supply. It is a strong recommendation to indicate to the end user a possible adverse effect before using this method.

For DVB-C/C2 there is no effect.

Reading the property provides the current value.

7.3.10 The SignalInfo class

The SignalInfo object provides details on the signal strength of the tuner. If the tuner is not tuned to a transponder the all properties shall have the value undefined.

7.3.10.1 Properties

readonly Number strength

Signal strength measured in dBm, for example -31.5dBm.

readonly Integer quality

Signal quality with range from 0 to 100. Calculation of quality is a function of ber and snr. The specification remains silent as to how the calculation is made.

readonly Integer ber

Bit error rate.

readonly Number snr

Signal to noise ratio (dB), for example 22.3dB.

readonly Boolean lock

True if the tuner is locked to a transponder.

7.3.11 The LNBInfo class

The LNBInfo object provides details on the LNB attached to a tuner. Setting any of the properties in this class results in an immediate update of the LNB configuration that is active for the associated Tuner. The LNB configuration is stored persistently.

7.3.11.1 Constants

The following constants are defined in the LNBInfo class:

Name	Value	Use
DUAL_LO_FREQ_LNB	30	A universal LNB that has two local oscillator frequency settings available. The selection between the frequencies is done by the presence of a 22 kHz control signal.
SINGLE_LO_FREQ_LNB	31	Only a single local oscillator frequency is available in the LNB.

7.3.11.2 Properties

Integer lnbType

The type of LNB connected to the frontend. Valid values are listed in section 7.3.11.1.

Number lnbLowFreq

The low or only, if a single local oscillator frequency LNB is used, LNB local oscillator frequency in MHz.

Number lnbHighFreq

If a dual local oscillator frequency LNB is used this is the high LNB local oscillator frequency in MHz. If a single local oscillator frequency LNB is used this argument shall be set to 0.

Number crossoverFrequency

Indicates the frequency (in MHz) when to switch between the high- and low-band oscillator frequencies (lnbLowFreq and lnbHighFreq respectively).

Number lnbStartFrequency

Indicates the lowest frequency, in MHz, that the LNB can be used for.

Number lnbStartFrequency

Indicates the highest frequency, in MHz, that the LNB can be used for.

Number orbitalPosition

Indicates the orbital position of the satellite in degrees, negative value for west, positive value for east. For example, Astra 19.2 East would have orbitalPosition 19.2. Thor 0.8 West would have orbitalPosition -0.8.

This property, if provided, will be used to select a Tuner instance (when scanning and tuning). Setting any value which is not a valid orbital position (an absolute value greater than 180) indicates that the orbital position need not be considered when using the associated tuner.

7.3.12 The StartupInformation class

This class contains information pertaining to the startup characteristics and configuration of the OITF.

7.3.12.1 Properties

readonly Integer urlSource

The mechanism used to obtain the url property. Any of the STARTUP_URL_* values defined in section 7.3.3.1 are valid.

readonly String url

The URL used at startup of the OITF.

If the urlSource property is STARTUP_URL_NONE then the value of this property shall be NULL.

If the urlSource property is STARTUP_URL_PRECONFIGURED then the value of this property shall be undefined.

7.4 Content Download APIs

This section defines the content-on-demand download interfaces for both DRM-protected and non-DRM protected content.

An OITF and a DAE application which have indicated support for downloading content by providing value “true” for element <download> in their capability profile as specified in section 9.3.4 shall adhere to the following requirements.

NOTE: Annex D clarifies the purpose and the use of these interfaces in more detail.

7.4.1 The application/oipfDownloadTrigger embedded object

An OITF shall support a non-visual embedded object of type application/oipfDownloadTrigger, with the following JavaScript API to enable passing a content-access descriptor to an underlying download manager using JavaScript.

The functionality as described in this section is subject to the security model of section 10.

7.4.1.1 Methods

String registerDownload( String contentAccessDownloadDescriptor, Date downloadStart, Integer priority )
Description	Send `contentAccessDownloadDescriptor` to the underlying download manager as a String formatted according to the Content Access Download Descriptor XML Schema as specified in Annex E. Returns a `String` value representing a unique identifier to identify the download, if the `contentAccessDownloadDescriptor` is valid and is accepted for triggering a download. If the OITF supports the application/oipfDownloadManager as specified in section 7.4.3, this shall be the value of the “id” attribute of the associated Download object. Note that if the Content Access Download Descriptor contains multiple content items to be downloaded, the associated Download objects for each of these content items shall have the same value for the “id” value. The associated Download objects can be retrieved through the method getDownloads() as defined in section 7.4.3.3. The OITF shall guarantee that download identifiers are unique in relation to recording identifiers and `CODAsset`identifiers. The method returns `undefined` if the `contentAccessDownloadDescriptor` is not accepted for triggering a download.
Arguments	contentAccessDownloadDescriptor	String formatted according to the Content Access Download Descriptor XML Schema as specified in Annex E.
	downloadStart	Optional argument indicating the time at which the download should be started. If the argument is not included, or takes a value of `null` then the download should start as soon as possible.
	priority	Optional argument indicating the relative priority of the download with respect to other downloads registered by the same organisation as the calling application. Higher values indicate a higher priority. If the argument is not included then a priority of 0 shall be assigned.

String registerDownloadURL( String URL, String contentType, Date downloadStart, Integer priority )
Description	This method triggers the OITF to initiate a download of the content pointed to by the URL and the given content type. The `contentType` attribute shall reflect the expected type of content returned by the content server when connecting to the URL. The `contentType` can be used to evaluate if the content type is part of the list of accepted content types of the OITF. For example, if the OITF does not support content type “`video/MP2T`”, then the `registerDownloadURL` method could return undefined to indicate this to the application in advance of the download. If `contentType` has value “`application/vnd.oipf.ContentAccessDownload+xml`”, the method shall return a download identifier, after which the OITF shall immediately fetch the Content Access Download Descriptor, after which the same shall happen as if registerDownload() as defined in section 4.6.3.1 with the given Content Access Download Descriptor as argument was called. The downloadStart argument only applies to the individual Download objects described by the Content Access Download Descriptor and shall not apply to the retrieval of the Content Access Download Descriptor itself. Note that if the Content Access Download Descriptor contains multiple content items to be downloaded, the associated Download objects for each of these content items shall have the same value for the “id” value. The associated Download objects can be retrieved through method getDownloads() as defined in section 7.4.3.3. Returns a String value representing a unique identifier to identify the download, if the given arguments are acceptable by the OITF to trigger a download. If the OITF supports the application/oipfDownloadManager as specified in section 7.4.3, this shall be the value of the “id” attribute of the associated Download object(s). The OITF shall guarantee that download identifiers are unique in relation to recording identifiers and `CODAsset` identifiers. The method returns `undefined` if the given arguments are not acceptable by the OITF to trigger a download.
Arguments	URL	The URL from which the content can be fetched.
	contentType	The type of content referred to by the URL attribute. The `contentType` can be used to evaluate if the content type is part of the list of supported content types of the OITF.
	downloadStart	Optional argument indicating the time at which the download should be started. If the argument is not included, or takes a value of `null` then the download should start as soon as possible.
	priority	Optional argument indicating the relative priority of the download with respect to other downloads registered by the same organisation as the calling application. Higher values indicate a higher priority. If the argument is not included then a priority of 0 shall be assigned.

Integer checkDownloadPossible( Integer sizeInBytes )

Description

Checks whether a download of a given sizeInBytes would be possible at this moment in time. The value is application specific. For an application whose organization has a reservation, only the free space in the reservation shall be considered when making the check.

Possible return values are:

Value	Description
0	Successful, i.e. the download could be successfully completed if it would be started at this moment in time.
1	Insufficient Storage, i.e. the download could be started, but is unlikely to complete successfully, since insufficient storage capacity is available to fully store the content to be downloaded.
2	Storage not available, i.e. the download would fail, since the storage is currently unavailable, e.g. in case of removable storage.

Arguments sizeInBytes Integer value with the given size of the download in bytes.

7.4.2 Extensions to application/oipfDownloadTrigger

If an OITF has indicated support for both BCG metadata (i.e. by giving element <clientMetadata> value “true” and a “type” attribute with value “bcg”), and the download management APIs defined in section 7.4.3 (i.e. by giving attribute “manageDownloads” of the <download> element a value unequal to “none”) in the client capability description, then the following additional method shall be supported by the application/oipfDownloadTrigger object defined in section 7.4.1.

The functionality as described in this section is subject to the security model of section 10

String registerDownloadFromCRID( String CRID, String IMI, Date downloadStart, Integer priority )
Description	Send `(CRID,IMI)` to underlying download manager. Returns a `String` value representing a unique identifier to identify the download if the `(CRID,IMI)` tuple is valid and is accepted for triggering a download. If the OITF supports the application/oipfDownloadManager as specified in section 7.4.3, this shall be the value of the “id” attribute of the associated Download object(s), which corresponds to the `CRID` in this case. The OITF shall guarantee that download identifiers are unique in relation to recording identifiers and `CODAsset` identifiers. The method returns `undefined` if the given `(CRID,IMI)` tuple is not accepted for triggering a download. The values of the `name`, `description`, `parentalRating` and `DRMControl` properties shall be based on the metadata provided for the item matching that CRID.
Arguments	CRID	The TV-Anytime Content reference ID that points to the general information about the item to download that does not change regardless of how the content is published or broadcast.
	IMI	The TV-Anytime Instance Metadata ID that points to the specific information related to the item to download, such as content location, usage rules (pay-per-view, etc.) and delivery parameters (e.g. video format).
	downloadStart	Optional argument indicating the time at which the download should be started. If the argument is not included, or takes a value of `null` then the download should start as soon as possible.
	priority	Optional argument indicating the relative priority of the download with respect to other downloads registered by the same organisation as the calling application. Higher values indicate a higher priority. If the argument is not included then a priority of 0 shall be assigned.

7.4.3 The application/oipfDownloadManager embedded object

In a managed deployment, privileged applications may need access to the download management functionality in a CoD system. This access may be required to implement a UI to the download manager, to queue a download or to display the progress of a specific download. OITFs should support an “application/oipfDownloadManager” object with the following interface.

Clients supporting the download management APIs as specified in this section shall indicate this by adding the attribute “manageDownloads” to the <download> element with a value unequal to “none” in the client capability description as defined in section 9.3.4.

The functionality as described in this section is subject to the security model of section 10.

7.4.3.1 State diagram of the application/oipfDownloadManager object

The following state machine provides an overview of the state changes that are possible in the download manager. The states reflect the changes signalled to applications via the onDownloadStateChange event handler.

Figure 12: State diagram for embedded application/oipfDownloadManager objects (normative)

Note that newly-registered downloads may pre-empt downloads which are currently in progress, if they have a higher priority than in-progress downloads. This may cause downloads to be paused or resumed without application intervention.

7.4.3.2 Properties

function onDownloadStateChange( Download item, Integer state, Integer reason )

The function that is called when the status of a download has changed. The specified function is called with three arguments item, state and reason, which are defined as follows:

Download item – the Download object whose state has changed.

Integer state – the new state of the download. Valid values include:

Status	Semantics
1	The download has completed successfully.
2	The download is in progress.
4	The download has been paused (either by an application or automatically by the OITF).
8	The download has failed.
16	The download has been queued but has not yet started.
32	The download has stalled due to a transient failure and the Download Manager is attempting to recuperate and re-establish the download.

Integer reason - Extended reason code. This is only valid if the value of the state argument is 8.

Reason	Semantics
0	The local storage device is full.
1	The item cannot be downloaded (e.g. because it has not been purchased).
2	The item is no longer available for download.
3	The item is invalid due to bad checksum or length.
4	Other reason.

If no error has occurred, this argument shall take the value undefined.

readonly DiscInfo discInfo

Get information about the status of the local storage device. The DiscInfo class is defined in section 7.16.4.

readonly Integer hasReserved

Returns the size (in megabytes) of any current reservation for the applications from the same organisation as the calling application otherwise -1.

readonly Integer allocated

Returns the size (in megabytes) of any current reservation for the applications from the same organisation as the calling application otherwise -1.

7.4.3.3 Methods

Boolean pause( Download download )

Description

Pause an in-progress, queued or stalled download and return true. For in-progress downloads, more data shall not be downloaded until the download is resumed. The HTTP request and TCP socket are interrupted and closed.

For completed or failed downloads, this operation shall return false.

Arguments download The download to be paused.

Boolean resume( Download download )
Description	Resume a paused download. If the download is not paused, this operation shall return `false`.
Arguments	download	The download to be resumed.

Boolean remove( Download download )

Description

Remove the download and any data and media content associated with it and return true. Return false if the download attribute does not refer to a valid download.

As a side effect of this method, all properties on download shall be set to undefined. Any method calls subsequently performed by an application which pass download as an argument shall return false.

If an A/V Control object is referring to the indicated download for playback then the state of the A/V Control object shall be automatically changed to state 6 (the error state).

Arguments download The download to be deleted.

DownloadCollection getDownloads( String id )

Description

Returns a collection of downloads, for which the value of the Download.id property corresponds to the given id parameter. The downloads returned in the collection shall be filtered according to the value of the manageDownloads attribute of the <download> element in the OITF’s capability description (i.e. from the same application, same domain or from all applications).

For downloads initiated from registerDownloadURL() with a contentType value “application/vnd.oipf.ContentAccessDownload+xml” shall return null until the Content Access Download Descriptor has been retrieved and parsed.

If the value of id is null, it returns all downloads for the scope indicated by the manageDownloads attribute.

Arguments id Optional argument identifying the downloads to be retrieved. If present and not null, this is an identifier corresponding to the “id” attribute of zero or more Download objects. If the value of id is null, or the argument is not included, all downloads for the scope indicated by the manageDownloads attribute in the capability description are returned.

DownloadCollection createFilteredList( Boolean currentDomain, Integer states )

Description

Create a filtered list of downloads. Returns a subset of downloads that are managed by the receiver.

The currentDomain flag indicates whether downloads from FQDNs other than the current page are included in the returned collection. This flag may be set to one of three values:

Value

Meaning

true

The download is added if and only if it was initiated from the FQDN of the calling document.

If the application has the permission permission_downloadmanager (see section 10.1.4), only downloads initiated by the calling application shall be added.

false

The download is added if and only if it was not initiated from the FQDN of the calling document.

If the application does not have the permission permission_downloadmanager_all (see section 10.1.4), the OITF shall return an empty collection.

undefined

The download is added regardless of the domain that the download was initiated from.

If the application has the permission permission_downloadmanager (see section 10.1.4), only downloads initiated by the calling application shall be added.

If the application has the permission permission_downloadmanager_samedomain (see section 10.1.4), only downloads initiated by applications from the same FQDN shall be added.

The states flag indicates which state(s) of downloads that should be included in the list. The value of this flag is the arithmetic sum of one or more possible values of the state property of the Download object; only downloads whose state matches one of the values included in this sum are included in the returned collection.

Arguments currentDomain Flag indicating whether downloads from other domains shall be added to the list.

states Indicates that states of downloads that should be included in the returned list.

Boolean updateRegisteredDownload( Download download, String newURL )
Description	The method `updateRegisteredDownload()` provides a way to update the URL to be used for a download. The OITF shall use the new URL for any future retrieval. If the download is already in progress or paused (indicated by a state property value of 4), it shall be stopped. The download shall continue from the last byte received during the previous download. If the state property of the `download` argument has the value 8 (download failed) or 32 (download stalled) then the OITF shall resume the download from the last byte received during the previous download but using the new URL. If the state property of the `download` argument has the value 16 (download not started) no further action is taken until the download is started or resumed. If the state property of the `download` argument has the value 1 (download completed) then this method shall return `false`. Otherwise it shall return `true`.
Arguments	download	The download object to be updated.
	newURL	The new URL from which the content can be retrieved.

Integer reserve( Integer bytes )

Description

Requests the reservation of space for downloads to be made by applications from the same organization as the calling application. Reservation is optional for applications to use and applications may use the Download API without reserving space in advance.

If there is already a reservation for the calling application’s organization, this requests adjusting the reservation to the new value. If a call to reserve shrinks an already existing reservation then the application should ensure that the new size is sufficient for all the completed, in progress and requested downloads by applications from the calling application’s organization. The OITF shall refuse to shrink the reservation if this has not been done.

This specification intentionally does not define the criteria that are used in deciding whether or not to make or adjust a reservation.

Either the OITF or the end-user may cancel a reservation completely, shrink one to recover some or all of the free space in the reservation or expand it. This specification intentionally does not define circumstances when this may happen. If a request to reserve space is granted to an organisation then applications from that organisation shall have the reserved space available to them for downloads. Attempts to use more than the reserved space shall fail.

A reservation is cancelled by calling this method with size zero.

Returns one of the RESERVE_ constants defined in section 7.4.3.5 below.

Arguments

bytes

The number of bytes to reserve.

7.4.3.4 Events

For the intrinsic event “onDownloadStateChange”, a corresponding DOM event shall be generated, in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onDownloadStateChange	DownloadStateChange	Bubbles: No Cancellable: No Context Info: `item`, `state`, `reason`

NOTE: the above DOM event is directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving a DownloadStateChange event during the bubbling or the capturing phase. Applications that use DOM event handlers shall call the addEventListener() method on the application/oipfDownloadManager object. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.4.3.5 Constants

Name	Use
RESERVE_OK	Reservation succeeded.
RESERVE_NEVER	Reservations by the calling application will never succeed.
RESERVE_USER_INTERVENTION_REQD	Reservation failed and user intervention is required. This result shall only be returned by OITFs that include a platform provided UI enabling end-users to manage storage. RESERVE_TOO_LARGE shall be returned in preference to this if both apply.
RESERVE_USER_DECLINED	Reservation failed as the user was asked to approve this request and declined.
RESERVE_TOO_LARGE	Reservation failed as the size requested was larger than what is permitted by the OITF.
RESERVE_SMALLER_THAN_USED	Request to shrink an already existing reservation failed as the requested size is smaller than the space currently used from the reservation.
RESERVE_UNKNOWN	Reservation failed for another reason.

7.4.4 The Download class

A Download object being made available by the application/oipfDownloadManager embedded object represents a content item that has either been downloaded from a remote server or is in the process of being downloaded.

If the ID of a download is a TV-Anytime CRID, then the values of the name, description and parentalRatings properties shall be set by the OITF based on the metadata provided for the item matching that CRID.

In order to preserve backwards compatibility with already existing DAE content the JavaScript toString() method shall return the Download.id for Download objects.

7.4.4.1 Properties

readonly Integer totalSize

The total size (in bytes) of the download.

readonly Integer state

The current state of the download. When this changes, a DownloadStateChange event shall be generated. Valid values are:

Value	Description
1	The download has completed.
2	The download is in progress.
4	The download has been paused (either by an application or automatically by the platform).
8	The download has failed.
16	The download is queued but has not yet started.
32	The download has stalled due to a transient failure and the Download Manager is attempting to recuperate and re-establish the download.

Note: these values are used as a bitfield in the DownloadManager.createFilteredList() method.

readonly Integer reason

The reason property is only valid if the value of the state property is 8 (download failed).

Value	Description
0	The local storage device is full.
1	The item cannot be downloaded (e.g. because it has not been purchased).
2	The item is no longer available for download.
3	The item is invalid due to bad checksum or length.
4	Other reason.

If no error has occurred, this argument shall take the value undefined.

readonly Integer amountDownloaded

The amount of data that has been downloaded returned in bytes, or zero if no data has been downloaded.

readonly Integer currentBitRate

The bitrate (in bits per second) at which the download is currently transferred. This value is non-zero only when the Download object is in state 2 (in progress). If this is unknown the value of this property shall be undefined.

String name

The name of the download or undefined if this information is not present. In case the download is triggered through a Content Access Download Descriptor, this corresponds to the value for the <Title> element in the Content Access Download Descriptor.

If the Content Access Download Descriptor is not specified then the property may be set by the origin site. Note that the property may only be set by the site that initiated the download. The DAE application may store data related to the Download. The OITF shall support a minimum of 200 bytes for the property. If DAE application attempts to store a string larger than the available size the OITF shall set the property to NULL. The maximum length of the property value is implementation dependent.

readonly String id

The ID of the download as determined by the OITF.

readonly String uri

A uri identifying the content item in local storage according to [RFC3986]. The format of the URI is outside the scope of this specification except that:

the scheme shall not be one that is included in this specification
the URI shall not include a fragment

readonly String contentURL

The URL the content is being fetched from, or undefined if this information is not available.

readonly String contentURL

A description of the download or undefined if this information is not present. In case the download is triggered through a Content Access Download Descriptor, this corresponds to the value for the <Synopsis> element in the Content Access Download Descriptor, or undefined if this element is not present.

If the Content Access Download Descriptor is not specified the property may be set by the origin site. Note that the property may only be set by the site that initiated the download. The DAE application may store data related to the Download. The OITF shall support a minimum of 2000 bytes for the property. If DAE application attempts to store a string larger than the available size the OITF shall set the property to NULL. The maximum length of the property value is implementation dependent.

readonly ParentalRatingCollection parentalRatings

The parental rating collection related to the downloaded content item, or undefined if this information is not present. In case the download is triggered through a Content Access Download Descriptor, this corresponds to the value for the <ParentalRating> element in the Content Access Download Descriptor, or undefined if this element is not present.

readonly DRMControlInfoCollection drmControl

The DRMControlInformation object corresponding to the DRM Control information of the downloaded content item, or undefined if this information is not present. In case the download is triggered through a Content Access Download Descriptor, this corresponds to the value for the <DRMControlInformation> element associated with the same DRMSystemID of the selected <ContentURL>, or is undefined if this information is not present. The related DRMControlInformation object is defined in section 7.4.6.

readonly Date startTime

The time that the download is scheduled to start (in the case of scheduled downloads) or undefined if no start time was set.

readonly Integer timeElapsed

The time (in seconds) that has elapsed since the download of the item was started. The elapsed time shall be based on the time spent in the in-progress and stalled download states. This shall not include any time the item spent queued for download.

readonly Integer timeRemaining

The estimated time remaining (in seconds) for the download to complete. The estimated time shall be based on the time spent in the in-progress and stalled download states. The estimate shall not include any time the item spent queued for download or paused. If an estimate cannot be calculated, the value of this property shall be undefined.

readonly String transferType

In case the download was triggered through a Content Access Download Descriptor, this is the value of property TransferType of the selected <ContentURL>. In the case where the download was not triggered through a Content Access Download Descriptor, the OITF is responsible for returning either the value “playable_download” or “full_download”, based on criteria defined by the OITF.

readonly String originsite

In the case where the download was triggered through a Content Access Download Descriptor, this is the value of element <OriginSite>. In case the download was not triggered through a Content Access Download Descriptor, this is the FQDN of the site that initiated the download.

readonly String originSiteName

In case the download is triggered through a Content Access Download Descriptor, this is the value of element <OriginSiteName>, or undefined if this information is not present. In case the download is not triggered through a Content Access Download Descriptor, this property is undefined.

String contentID

A unique identification of the content item relative to originSite. In case the download is triggered through a Content Access Download Descriptor, and a <ContentID> element has been defined for the given content item, this is the value of element <ContentID>. If the download is started using registerDownloadFromCRID(), this is the TV Anytime CRID. This property shall take the value undefined if no content ID is available.

If the Content Access Download Descriptor is not specified the property may be set by the originSite. Note that the property may only be set by the site that initiated the download. The DAE application may store data related to the Download. The OITF shall support a minimum of 2000 bytes for the property. If DAE application attempts to store a string larger than the available size the OITF shall set the property to NULL. The maximum length of the property value is implementation dependent.

String iconURL

The URL of an image that provides a visual representation of the item that is being downloaded. In the case where the download was triggered a Content Access Download Descriptor, this is the value of element <IconURL>, or undefined if this element is not present. In the case where the download was not triggered through a content access descriptor document, this property is undefined.

readonly Document metadata

For downloads registered through a Content Access Download Descriptor, this function shall return the contents of the Content Access Download Descriptor as an XML Document object using the syntax as defined in section E.1 without using any namespace definitions.

For downloads registered using a URL, the value of this property shall be null.

readonly Integer priority

The relative priority of the download with respect to other downloads registered by that application. Higher values indicate a higher priority.

readonly Integer suspendedByTerminal

Flag indicating whether the download has been paused automatically by the OITF, either because the download has been pre-empted by higher priority downloads or because the number of simultaneous downloads supported by the OITF has been exceeded.

7.4.5 The DownloadCollection class

typedef Collection<Download> DownloadCollection

The DownloadCollection class represents a collection of Download objects. See Annex K for the definition of the collection template.

7.4.6 The DRMControlInformation class

A DRMControlInformation object represents the DRM Control information structure defined in section 3.3.2 of [OIPF_META2].

7.4.6.1 Properties

readonly String drmType

URN containing the decimal number format of the DVB CASystemID, prefixed with the string "urn:dvb:casystemid:". For example, the hexadecimal value 0x4AF4 is assigned as the CASystemID for Marlin by DVB, and so for Marlin the value of this property would be “urn:dvb:casystemid:19188”.

readonly String rightsIssuerURL

A URL used by OITF to obtain rights for this content item.

readonly String silentRightsURL

A URL used by OITF to obtain rights silently, e.g. a Marlin Action Token.

readonly String drmContentID

DRM Content ID for CoD or scheduled content item, e.g. the Marlin Content ID.

readonly String previewRightsURL

A URL used by OITF to obtain rights silently for preview of this content item, e.g. a Marlin Action Token.

readonly String drmPrivateData

Private data for the DRM scheme indicated in drmType to be applied for this content item. Private DRM Data is actually structured as an XML document whose schema is specific to the considered DRM system. One example is Marlin DRM private data schema defined in [OIPF_CSP2].

readonly Boolean doNotRecord

A flag indicating whether this content item is recordable or not.

readonly Boolean doNotTimeShift

A flag indicating if this content item is allowed for time shift play back.

7.4.7 The DRMControlInfoCollection class

typedef Collection<DRMControlInformation> DRMControlInfoCollection

The DRMControlInfoCollection class represents a collection of DRMControlInformation objects. See Annex K for the definition of the collection template.

7.5 Content On Demand Metadata APIs

This section shall apply for OITFs that have indicated <clientMetadata> with value “true” and a “type” attribute with value “bcg” in the capability description and may apply for OITFs that have indicated <clientMetadata> with value “true” and a “type” attribute with value “dvb-si”

7.5.1 The application/oipfCodManager embedded object

OITFs that have indicated <clientMetadata> with value “true” and a “type” attribute with value “bcg” shall implement an “application/oipfCodManager” embedded object with the following interface.

Content is organised into catalogues, where each catalogue contains a hierarchy of folders that are used to organise individual content items. The structure of the catalogue shall be determined by the server managing that catalogue and shall be reflected in the structure of the metadata passed to the OITF.

The three types of content in a CoD catalogue are:

Assets, represented by the CODAsset class. A CODAsset is a user-level description of a piece of CoD content, and so it is more concerned with information such as the price, rental period, description and parental rating rather than detailed technical information about the asset such as encoding format. A CoD asset may represent a single movie, or a bundle of movies offered for a single price.
Folders, represented by the CODFolder class.
Services represented by the CODService class. CODService objects are a specific type of container representing subscription VoD (SVOD) services, where users purchase a group of assets which may change over time rather than a single movie or TV show.

The CODAsset, CODFolder and CODService classes define a type property that allows these classes to be distinguished by applications. For each class, this property shall take the value defined below:

Class	Value
CODFolder	0
CODAsset	1
CODService	2

This specification defines the mapping between the CoD API and BCG metadata. Mappings between the CoD API and other CoD metadata sources are not specified in this document.

7.5.1.1 Properties

readonly ContentCatalogueCollection catalogues

A collection of all available CoD catalogues, as listed in an SD&S BCG Discovery record.

function onContentCatalogueEvent( Integer action )

This function is the DOM 0 event handler for events relating to changes in a content catalogue collection. The specified function is called with the argument action:

Integer action - The type of event. For current versions of the specification, this property shall always have the value 0 to indicate a change in the list of available catalogues.

function onContentAction( Integer action, Integer result, Object item, ContentCatalogue catalogue )

This function is the DOM 0 event handler for events relating to actions carried out on an item in a content catalogue. The specified function is called with the following arguments:

Integer action - The type of action that the event refers to. Valid values are:

Value	Description
0	An operation to browse a content collection (e.g. getting a page from the collection).
1	Indicates that more information is available about this item (e.g. that more information has been retrieved from the server).

Integer result - TThe result of the action. Valid values are:

Value Description

0 The operation succeeded.

1 The item no longer exists in the catalogue.

2 The server has not responded in the timeout period.

3 Communication with the server has been interrupted.
Object item - The item in the catalogue that the event refers to.
ContentCatalogue catalogue - The parent catalogue of the affected object.

7.5.1.2 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onContentCatalogueEvent	ContentCatalogueEvent	Bubbles: No Cancellable: No Context Info: `action`
onContentAction	ContentAction	Bubbles: No Cancellable: No Context Info: `action`, `result`, `item`, `catalogue`

NOTE: the above DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving the events listed above during the bubbling or the capturing phase. Applications that use DOM event handlers shall call the addEventListener() method on the LocalSystem object. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.5.2 The ContentCatalogueCollection class

typedef Collection<ContentCatalogue> ContentCatalogueCollection

The ContentCatalogueCollection class represents a collection of ContentCatalogue objects. See Annex K for the definition of the collection template.

7.5.3 The ContentCatalogue class

A ContentCatalogue represents a content catalogue for a content on demand service.

To receive events relating to operations on items in a catalogue, applications may add listeners for “ContentAction” events to the application/oipfCodManager object.

7.5.3.1 Properties

readonly String name

The name of the content catalogue that should be displayed to the user. The value of this property is given by the Name element in the catalogue's BCG discovery record.

readonly CODFolder rootFolder

The root folder of the content catalogue.

7.5.3.2 Methods

CODFolder getPurchaseHistory()

Description

Get the list of items that have been purchased from the catalogue by the current user, including currently active rentals.

Items in this list will be derived from children of the BCG UserActionList element which have an ActionType of buy. If the ActionList element is not present, this method shall return null.

7.5.4 The ContentCatalogueEvent class

This section is intentionally left empty.

7.5.5 The CODFolder class

CODFolder represents a folder in a CoD catalogue. Folders may contain other folders, and an asset may be present in more than one folder.

Because a content list may contain a large number of items, the contents of the list are made available on demand using a paging model. Applications may request the contents of the list in ‘pages’ of an arbitrary size. The data shall be fetched from the appropriate source, and application shall be notified when the data is available.

Each folder is described by a GroupInformation element in the BCG Group Information Table.

7.5.5.1 Properties

readonly Integer type

The type of the item, used to distinguish between the types of objects that may be contained in a folder in a CoD catalogue. This shall always have the value 0 for folders.

readonly String uri

The URI used to refer to the folder. The value of this property is given by the GroupId attribute of the GroupInformation element representing this folder.

readonly String name

The name of the folder. The value of this property is given by the Title element that is a descendant of the GroupInformation element representing this folder.

readonly String description

A description of the folder, for display to an end user. The value of this property is given by the Synopsis element that is a descendant of the GroupInformation element representing this folder.

readonly String thumbnailUri

The URI of an image associated with this folder.

For assets whose BCG description contains a RelatedMaterial element indicating a relationship of Promotional Still Image, the value of this property is given by the MediaURI element that is a descendant of that element. For assets without an appropriate RelatedMaterial element, the value of this property shall be undefined.

readonly Integer length

The number of items in the current page. If getPage() has not yet been called, the value of this property shall be undefined.

readonly Integer currentPage

The page number of the currently-available results, as specified in the last call to getPage(). If getPage() has not yet been called, the value of this property shall be undefined.

readonly Integer pageSize

The number of items that were requested from the content catalogue in a call to getPage(). This may be different form the number of items that are available (e.g. the last page in the collection).

If getPage() has not yet been called, the value of this property shall be undefined.

readonly Integer totalSize

The total number of items in the folder. This may be undefined until getPage() has been called.

The value of this property may be given by the numOfItems attribute of the GroupInformation element representing this folder.

7.5.5.2 Methods

Object item( Integer index )

Description

Return the item at position index in the current page, or undefined if no item is present at that position. This function shall only return objects that are instances of CODAsset, CODFolder, or CODService.

Applications shall be able to access items in the collection using array notation instead of calling this method directly.

Arguments index The index into the collection.

void getPage( Integer page, Integer pageSize )
Description	Retrieve one page of the folder’s contents. The application shall be notified by an event targeted at the folder's parent content catalogue when the data is available. Calls to this method shall cancel any outstanding requests.
Arguments	page	The number of the page for which data should be retrieved, indexed from zero.
	pageSize	The size of the page.

void abort( )
Description	Abort the current request for a new page of folder contents. Any results for this folder shall be removed (i.e. the value of the length property will be 0 and any calls to the item() method shall return `undefined`)

7.5.6 The CODAsset class

The CODAsset represents a piece of CoD content that can be purchased and played. A CODAsset object may refer to a bundle of content items that are purchased together but which can only be played individually.

Some fields of a CODAsset object may not be populated until an application requests them; in this case the data may be fetched asynchronously from a server. Fields where the data has not been fetched from the server shall have a value of undefined. Fields for which data is not available on the server shall have a value of null.

Note: The lookupMetadata() method has been removed from this class.

7.5.6.1 Properties

readonly Integer type

The type of the item, used to distinguish between the types of objects that may be contained in a folder in a CoD catalogue. This property shall always have the value 1 for CoD assets.

readonly String uri

The CRID of the asset. The value of this property is given by the programId attribute of the BCG ProgramInformation element that describes the asset.

readonly String name

The title of the asset that will be displayed to the user. The value of this property is given by the BCG Title element that is a child of the asset’s BasicDescription element.

readonly String description

A description of the asset, for display to an end user. The value of this property is given by the BCG Synopsis element that is a child of the asset’s BasicDescription element.

readonly StringCollection genres

A collection of genres that describe this asset. Genres are represented by the values of any Name elements that are children of Genre elements in the asset’s description.

readonly ParentalRatingCollection parentalratings

A collection of genres that describe this asset. Genres are represented by the values of any Name elements that are children of Genre elements in the asset’s description.

readonly Boolean blocked

Flag indicating whether the asset is blocked due to parental control settings (i.e. whether its parental rating value exceeds the current system threshold).

readonly Boolean locked

Flag indicating whether the current state of the parental control system prevents the asset from being viewed (e.g. a correct parental control PIN has not been entered to allow the item to be viewed).

readonly String thumbnailUri

The URI of an image associated with this asset.

For assets without an appropriate RelatedMaterial element, the value of this property shall be undefined.

readonly String price
The price of the asset, in a form that can be displayed to the user. The value of this property is the concatenation of the value of the `Price` element that is a child of a `PurchaseItem` element in the asset’s description and the value of the `Price` element’s currency attribute. For example, a Price element of <Price currency="JPY">500</Price> would give the value `500 JPY` for this field. Implementations may replace the currency code with the appropriate currency symbol (e.g. ¥ ).

readonly Integer rentalPeriod

The period for which the asset can be rented, in hours.

For assets descriptions containing a Purchase element with a PurchaseType of urn:tva:metadata:cs:PurchaseTypeCS:2004:playForPeriod, the value of this property is derived from the QuantityUnit and QuantityRange elements that are children of that Purchase element. If a Purchase element with the appropriate PurchaseType is not present, the value of this field shall be undefined.

readonly Integer playCount

The number of plays allowed for this asset when it is purchased.

For assets descriptions containing a Purchase element with a PurchaseType of urn:tva:metadata:cs:PurchaseTypeCS:2004:playCounts, the value of this property is derived from the QuantityUnit and QuantityRange elements that are children of that Purchase element. If a Purchase element with the appropriate PurchaseType is not present, the value of this field shall be undefined.

readonly Integer duration

The duration of the asset, in seconds. The value of this property is given by the BCG Duration element that is a child of the asset’s BasicDescription element.

readonly String previewUri

The URI used to refer to a preview of the asset.

For assets whose BCG description contains a RelatedMaterial element indicating a relationship of Trailer or Preview, the value of this property is given by the MediaURI element of the MediaLocator contained in that element.

For assets without an appropriate RelatedMaterial element, the value of this property shall be undefined.

readonly BookmarkCollection bookmarks

A collection of the bookmarks set in a recording. If no bookmarks are set, the collection shall be empty.

7.5.6.2 Methods

Boolean isReady( )

Description

Check whether sufficient information is available to make a purchase or play the asset. Due to the asynchronous nature of CoD catalogues, not all of the information required to play or purchase a CoD asset may have been received by the OITF at any given time. If all of the required information is available, this method shall return true. Otherwise, this method shall request the missing information and return false. When the information is available, the application shall be notified via a ContentAction event with the reason code 1.

7.5.7 The CODService class

The CODService class is a subclass of CODFolder that represents a subscription CoD service. A subscription CoD service is similar to a folder, except that:

The service shall be purchased in its entirety, rather than purchasing individual items from the service.
Business rules may prevent browsing of the content within a service unless the service has already been purchased.

A CODService may contain a number of assets, folders and services.

Note: The lookupMetadata() method and uid property has been removed from this class.

7.5.7.1 Properties

readonly Integer length

The number of items in the current page of the service.

readonly Integer currentPage

The page number of the currently-available results, as specified in the last call to getPage(). If getPage() has not yet been called, the value of this property shall be undefined.

readonly Integer pageSize

The number of items that were requested from the content catalogue in a call to getPage(). This may be different from the number of items that are available (e.g. the last page in the collection).

If getPage() has not yet been called, the value of this property shall be undefined.

readonly Integer totalSize

The total number of items in the service. This may be undefined until getPage() has been called.

The value of this property may be given by the numOfItems attribute of the GroupInformation element representing this folder.

readonly Integer type

The type of the item, used to distinguish between the types of objects that may be contained in a folder in a CoD catalogue. This property shall always have the value 2 for a CoD service.

readonly String uri

The URI used to refer to the service. The value of this property is given by the BCG ServiceURL element that is a child of the ServiceInformation element that describes the service.

readonly String name

The name of the service that will be displayed to the user. The value of this property is given by the BCG Name element that is a child of the ServiceInformation element that describes the service.

readonly String description

A description of the service, for display to an end user. The value of this property is given by the BCG ServiceDescritpion element that is a child of the ServiceInformation element that describes the service.

readonly String thumbnailUri

The URI of an image associated with this service. The value of this property is derived from the value of the first Logo element that is a child of the BCG ServiceInformation element describing the service. If this element specifies anything other than the URL of an image, the value of this property shall be undefined.

Alternatively, for services whose BCG description contains a RelatedMaterial element indicating a relationship of Promotional Still Image, the value of this property is given by the MediaURI element of the MediaLocator contained in that element.

For assets without an appropriate RelatedMaterial or Logo element, the value of this property shall be undefined.

readonly String previewUri

The URI used to refer to a preview of the content.

For services whose BCG description contains a RelatedMaterial element indicating a relationship of Trailer or Preview, the value of this property is given by the MediaURI element of the MediaLocator contained in that element.

For assets without an appropriate RelatedMaterial element, the value of this property shall be undefined.

7.5.7.2 Methods

Boolean isReady( )

Description

Check whether sufficient information is available to make a purchase. Due to the asynchronous nature of CoD catalogues, not all of the information required to play or purchase a CoD service may have been received by the OITF at any given time. If all of the required information is available, this method shall return true. Otherwise, this method shall request the missing information and return false. When the information is available, the application shall be notified via a ContentAction event with the action code 1.

Object item( Integer index )

Description

Applications shall be able to access items in the collection using array notation instead of calling this method directly.

Arguments index The index into the collection.

void getPage( Integer page, Integer pageSize )
Description	Retrieve one page of the services contents. The application shall be notified by an event targeted at the services parent content catalogue when the data is available. Calls to this method shall cancel any outstanding requests.
Arguments	page	The number of the page for which data should be retrieved, indexed from zero.
	pageSize	The size of the page.

void abort( )
Description	Abort the current request for a new page of folder contents. Any results for this folder shall be removed (i.e. the value of the length property will be 0 and any calls to the item() method shall return `undefined`)

7.6 Content Service Protection API

The following requirements shall apply to OITF and/or server devices which have indicated support for DRM protection by providing one or more <drm> elements as specified in section 9.3.10:

7.6.1 The application/oipfDrmAgent embedded object

An OITF shall support a non-visual embedded object of type “application/oipfDrmAgent”, with the following JavaScript API, to enable in-session message exchange from the web page with an underlying DRM agent.

Access to the functionality of the application/oipfDrmAgent embedded object shall adhere to the security requirements as defined in section 10.1.

Note: Annex D provides a clarification to the browser interaction model when dealing with protected content.

7.6.1.1 Properties

function onDRMMessageResult( String msgID, String resultMsg, Integer resultCode )

The function that is called when the underlying DRM agent has a result message to report to the current HTML document as a consequence of a call to sendDRMMessage. The specified function is called with three arguments msgID, resultMsg and resultCode which are defined as follows:

String msgID – identifies the original message which has led to this resulting message.
String resultMsg – DRM system specific result message.

Integer resultCode – result code. Valid values include:

Result message	Description	Semantics
0	Successful	The action(s) requested by sendDRMMessage() completed successfully.
1	Unknown error	sendDRMMessage() failed because an unspecified error occurred.
2	Cannot process request	sendDRMMessage() failed because the DRM agent was unable to complete the request.
3	Unknown MIME type	sendDRMMessage() failed, because the specified Mime Type is unknown for the specified DRM system indicated in the DRMSystemId.
4	User consent needed	sendDRMMessage() failed because user consent is needed for that action.
5	Unknown DRM system	sendDRMMessage() failed, because the specified DRM System in DRMSystemId is unknown.
6	Wrong format	sendDRMMessage() failed, because the message in msg has the wrong format.

function onDRMSystemStatusChange( String DRMSystemID )

The function that is called when the status of a DRM system changes.

The specified function is called with one argument DRMSystemID which is defined as follows:

String DRMSystemID – argument that specifies the DRM System ID of the DRM system that generated the event as defined by element DRMSystemID in Table 9 of section 3.3.2 of [OIPF_META2].

function onDRMSystemMessage( String msg, String DRMSystemID )

The function that is called when the underlying DRM system has a message to report to the current HTML document.

The specified function is called with two arguments, msg and DRMSystemID, which are defined as follows:

String msg – DRM system specific message.
String DRMSystemID – argument that specifies the DRM System ID of the DRM system that generated the event as defined by element DRMSystemID in table 9 of section 3.3.2 of [OIPF_META2].

7.6.1.2 Methods

String sendDRMMessage( String msgType, String msg, String DRMSystemID )
Description	Send message to the DRM agent, using a message type as defined by the DRM system. Returns a unique ID to identify the message, to be passed as the ‘msgID’ argument for the callback function registered through onDRMMessageResult. This is an asynchronous method. Applications will be notified of the results of the operation via events dispatched to onDRMMessageResult and corresponding DOM events.
Arguments	msgType	A globally unique message type as defined by the DRM system, for example: application/vnd.marlin.drm.actiontoken+xml (i.e. MIME type of Marlin Action Token). Valid values for the msgType parameter include the MIME types described in Annex C of [OIPF_CSP2].
	msg	The message to be provided to the underlying DRM agent formatted according to the message type as indicated by attribute `msgType`. Valid format for the `msg` parameter are message formats described in Annex C of [OIPF_CSP2].
	DRMSystemID	DRMSystemID as defined by element DRMSystemID in table 9 of section 3.3.2 of [OIPF_META2]. For example, for Marlin, the DRMSystemID value is “`urn:dvb:casystemid:19188`”. In the case that parameter `msgType` indicates a CSPG-CI+ message as described in section 4.2.3.4.1.1.2 of [OIPF_CSP2] or an embedded CSPG message (see Annex F of [OIPF_CSP2]), the `DRMSystemID` parameter shall be specified. Otherwise, the value may be `null`.

Integer DRMSystemStatus( String DRMSystemID )

Description

Returns the status of the indicated DRM system, as defined below:

Value	Description	Semantics
0	READY	The DRM system is fully initialised and ready.
1	UNKNOWN	Unknown DRM system.
2	INITIALISING	The DRM system is initialising and not ready to start communicating with the application.
3	ERROR	There is a problem with the DRM system. It may be possible to communicate with it to obtain more information.

Arguments DRMSystemID The DRM System ID of the DRM system that is being queried as defined by the element DRMSystemID in table 9 of section 3.3.2 of [OIPF_META2]. For example, for Marlin, the DRMSystemID value is “urn:dvb:casystemid:19188”.

Boolean canPlayContent( String DRMPrivateData, String DRMSystemID )
Description	Checks the local availability of a valid license for playing a protected content item. The function returns true if there is a valid license available locally that may allow playing the content. For example the actual playing may be blocked due to other constraints (e.g. video/audio output restrictions on selected output). The DRMPrivateData may be retrieved by the application via a means out of scope of this specification (e.g. retrieved from Service Platform, or from a manifest file). For already downloaded content, the private data may be retrieved via the getDRMPrivateData() method of the Download class. In case the download is triggered through a Content Access Download Descriptor, the private data may be retrieved from the drmControl property.
Arguments	DRMPrivateData	DRM proprietary private data.
	DRMSystemID	DRMSystemID as defined by the element `DRMSystemID` in table 9 of section 3.3.2 of [OIPF_META2]. For example, for Marlin, the DRMSystemID value is “`urn:dvb:casystemid:19188`”.

Boolean canRecordContent( String DRMPrivateData, String DRMSystemID )
Description	Checks the local availability of a valid license for recording a protected content item. The function returns true if there is a valid license available locally that may allow recording the content. The DRMPrivateData may be retrieved by the application via a means out of scope of this specification (e.g. retrieved from Service Platform, or from a manifest file).
Arguments	DRMPrivateData	DRM proprietary private data.
	DRMSystemID	DRMSystemID as defined by the element `DRMSystemID` in table9 of section 3.3.2 of [OIPF_META2]. For example, for Marlin, the DRMSystemID value is “`urn:dvb:casystemid:19188`”.

7.6.1.3 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onDRMMessageResult	DRMMessageResult	Bubbles: No Cancellable: No Context Info: `msgID`, `resultMsg`, `resultCode`
onDRMSystemStatusChange	DRMSystemStatusChange	Bubbles: No Cancellable: No Context Info: `DRMSystemID`
onDRMSystemMessage	DRMSystemMessage	Bubbles: No Cancellable: No Context Info: `msg`, `DRMSystemID`

NOTE: the above DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving these events during the bubbling or the capturing phase. The addEventListener() method should be called on the application/oipfDrmAgent object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.7 Gateway Discovery and Control APIs

The application/oipfGatewayInfo object shall provide the information of the gateway and subsequently interact with the gateway (e.g. IMS Gateway, Application Gateway, CSPG-CI+ Gateway and CSPG-DTCP Gateway) as defined in section 4.2. The OITF shall support the gateway discovery and control though the use of the following non-visual embedded object:

<object id="gatewayinfo" type="application/oipfGatewayInfo">

Access to the functionality of the application/oipfGatewayInfo embedded object is privileged and shall adhere to the security requirements defined in section 10.1.

7.7.1 The application/oipfGatewayInfo embedded object

7.7.1.1 Properties

readonly Boolean isIGDiscovered

Readonly property that indicates whether an IMS Gateway is discovered or not.

NOTE: This property was formerly referred to as IGDiscovery.

readonly Boolean isAGDiscovered

Readonly property that indicates whether an Application Gateway is discovered or not.

NOTE: This property was formerly referred to as AGDiscovery.

readonly Boolean isCSPGCIPlusDiscovered

Readonly property that indicates whether a CSPG-CI+ Gateway is discovered or not.

NOTE: This property was formerly referred to as cspGatewayDiscovery. The former cspGatewayDiscovery property is now replaced with isCSPGCIPlusDiscovered for CSPG-CI+ case and isCSPGDTCPDiscovered for CSPG-DTCP case.

readonly Boolean isCSPGDTCPDiscovered

Readonly property that indicates whether a CSPG-DRCP Gateway is discovered or not.

NOTE: This property was formerly referred to as cspGatewayDiscovery. The former cspGatewayDiscovery property is now replaced with isCSPGCIPlusDiscovered for CSPG-CI+ case and isCSPGDTCPDiscovered for CSPG-DTCP case.

readonly String igURL

Readonly property that indicates the base Gateway’s URL for interacting between an OITF and an IMS Gateway.

readonly String agURL

Readonly property that indicates the base Gateway’s URL for interacting between an OITF and an Application Gateway.

readonly String cspgDTCPURL

Readonly property that indicates the base Gateway’s URL for interacting between an OITF and an CSPG-DTCP Gateway.

NOTE: This property was formerly referred to as cspGatewayURL which was relevant for CSPG-DTCP case only.

Integer interval

Read-write property that specifies the periodic interval time(seconds) to discover the gateways. When the interval property is set, an UPnP Discovery mechanism is executed.

function onDiscoverIG( )

The function that shall be called when an IMS Gateway is discovered or lost by the OITF which uses a UPnP Discovery mechanism described in [OIPF_PROT2] section 10.1.1.1. The actual status of the gateway (discovered or not) can be determined by reading the isIGDiscovered property.

The specified function is called with no arguments.

function onDiscoverAG( )

The function that shall be called when an Application Gateway is discovered or lost by the OITF which uses a UPnP Discovery mechanism described in [OIPF_PROT2] section 10.1.1.2. The actual status of the gateway (discovered or not) can be determined by reading the isIGDiscovered property.

The specified function is called with no arguments.

function onDiscoverCSPGDTCP( )

The function that shall be called when an CSPG-DTCP Gateway is discovered or lost by the OITF. The CSPG-DTCP gateway shall be discovered using a UPnP Discovery mechanism described in [OIPF_PROT2] section 10.1.1.3. The actual status of the gateway (discovered or not) can be determined by reading the isCSPGDTCPDiscovered property.

The specified function is called with no arguments.

NOTE: This property was formerly referred to as onDiscoverCSPG. The former onDiscoverCSPG property is now replaced with onDiscoverCSPGCIPlus for CSPG-CI+ case and onDiscoverCSPGDTCP for CSPG-DTCP case.

readonly Boolean isIGSupported

Readonly property that indicates whether an IMS Gateway is supported or not.

readonly Boolean isAGSupported

Readonly property that indicates whether an Application Gateway is supported or not.

readonly Boolean isCSPGCIPlusSupported

Readonly property that indicates whether a CSPG-CI+ Gateway is supported or not.

readonly Boolean isCSPGDTCPSupported

Readonly property that indicates whether a CSPG-DTCP Gateway is supported or not.

function onDiscoverCSPGCIPlus( )

The function that shall be called when a CSPG-CI+ Gateway is discovered or lost by the OITF (including any change to the DRM systems supported by that gateway). The CSPG-CI+ Gateway shall be discovered as defined in [OIPF_CSP2]. The actual status of the gateway (discovered or not) can be determined by reading the isCSPGCIPlusDiscovered property.

The specified function is called with no arguments.

NOTE: This property was formerly referred to as onDiscoverCSPG. The former onDiscoverCSPG property is now replaced with onDiscoverCSPGCIPlus for CSPG-CI+ case and onDiscoverCSPGDTCP for CSPG-DTCP case.

readonly StringCollection CSPGCIPlusDRMType

Readonly property that indicates the list of CA Systems supported by the CSPG-CI+ Gateway under the form of URN with the DVB CASystemID (16 bit number) in there. Each element of CSPGCIPlusDRMType shall be signalled by prefixing the decimal number format of CA_System_ID with "urn:dvb:casystemid:".

7.7.1.2 Methods

Boolean isIGSupportedMethod( String methodName )
Description	Shall return `true` when the IG supports the method specified in the ‘`methodName`’ argument. If the function returns `false`, it indicates that IG does not support the specified method.
Arguments	methodName	The name of the method to be checked for support.

7.7.1.3 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated, in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onDiscoverIG	DiscoverIG	Bubbles: No Cancellable: No
onDiscoverAG	DiscoverAG	Bubbles: No Cancellable: No
onDiscoverCSPGDTCP	DiscoverCSPGDTCP	Bubbles: No Cancellable: No
onDiscoverCSPGCIPlus	DiscoverCSPGCIPlus	Bubbles: No Cancellable: No

NOTE: the above DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving these events during the bubbling or the capturing phase. Applications that use DOM event handlers shall call the addEventListener() method on the application/oipfGatewayInfo object. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.8 Communication Services APIs

If an OITF has indicated support for the control of its Communication Services functionality by a server by stating <communicationServices>true</communicationServices> as defined in section 9.3.9 in its capability description, the OITF shall support communication services through the use of the following non-visual object:

<object type="application/oipfCommunicationServices"/>

The Communication Services API provides the necessary JavaScript methods to register new users. It also provides methods to register users (registerUser), along with the supported feature tags. A method getRegisteredUsers is also defined to view all the registered users. A method getAllUsers retrieves all users provisioned in the IG. Once registered it is possible to switch users for using communication services by using method setUser.

A property is defined to view the current user to be used for a service (currentUser).

In order to handle the out-of-session communication services notifications, namely, the new dialogues, there is a method for subscribing to these events (subscribeNotification). All new dialogues are communicated through a callback function (onNotification) to the application instance performing the subscription.

The Communication Services APIs apply only to privileged applications and shall adhere to the security model as defined in section 10.

7.8.1 The application/oipfCommunicationServices embedded object

7.8.1.1 Constants

Name	Value	Use
STATE_REGISTERED	0	Specifies that the user has been successfully registered (not subscribed to registration event). This also represents the state when the registration event subscription has been terminated for some reason by network.
STATE_REGISTERED_SUBSCRIPTION_PENDING	1	Indicates that user is registered successfully but the subscription-state for the registration event indicates a status of "pending".
STATE_REGISTERED_SUBSCRIPTION_ACTIVE	2	Specifies that the user has been successfully registered and subscribed to registration event (i.e. subscription-state for registration event indicates a status of "active").
STATE_DEREGISTERED	3	Specifies that the user has been successfully deregistered. This can be result of network initiated/locally initiated deregistration request.
STATE_FAILURE	4	Represents a failure condition.

7.8.1.2 Properties

function onNotification( String responseHeaders, String msgText, Document msgXML )

This function is called on the application which called subscribeNotification when an unsolicited notification arrives. The application will be notified of all notifications corresponding to any of the subscribed-to feature tags regardless of which application subscribed to it.

The specified function is called with 3 arguments.

String responseHeaders – The concatenated list of all HTTP headers, as a single string, with each header line separated by a U+000D (CR) U+000A (LF) pair excluding the status line. In absence of HNI-IGI interface, the responseHeaders will be a concatenated list all SIP headers, as a single string, with each header line separated by a U+000D (CR) U+000A (LF) pair excluding the status line.
String msgText - the response entity body as a string, as defined in the XMLHttpRequest specification as referenced in [OIPF_WSTVP2].
Document msgXML – the response entity body as a Document, as defined in the XMLHttpRequest specification as referenced in [OIPF_WSTVP2].

function onNotificationResult( Integer resultMsg )

This function is called with return result from the subscribeNotification method.

This function is not invoked in the case when there is no re-registration as part of subscribeNotification.

The specified function is called with a single argument – resultMsg.

Integer resultMsg – result message from performing subscribeNotification method.

Result message	Description	Semantics
0	Successful	The action performed by the underlying functionality was successful.
1	Unknown error	The action performed by the underlying functionality failed because an unspecified error occurred.
2	Wrong user credentials	The user credentials was not accepted by the server.
3	The user doesn’t exist	The user id doesn’t exist in the local user table.

function onRegistrationContextUpdate( String user, Integer state, Integer errorCode )

This function is called with return result from the methods registerUser and deRegisterUser. In addition, the function is also called whenever there is an update to the registration status of specified user.

The specified function is called with 3 arguments – user, state and errorCode.

String user – The IMPU of the user.
Integer state – The current state of the registration as indicated using the constant values defined in section 7.8.1.1.

Integer errorCode – In case of STATE_FAILED state, provides more information on reason for failure.

errorCode	Description	Semantics
1	Unknown error	The action performed by the underlying functionality failed because an unspecified error occurred.
2	Wrong user credentials	The user credentials were not accepted by the server. The DAE may request from the user a new PIN which can then be used to perform a new registerUser with the provided PIN.
3	The user doesn’t exist	The user id doesn’t exist in the local user table.

readonly UserData currentUser

The current user property represents the public user identity which is being used or shall be used for HNI-IGI communication. If not set then the default user shall be used or indicated. It shall be set to the default user if a user has not been explicitly set using the setUser() method.

7.8.1.3 Methods

UserDataCollection getRegisteredUsers( )
Description	Return all the users that are currently registered with the IG.

void registerUser( String userId, String pin )
Description	This method performs user registration to the network. Results from this method is sent to the callback method onRegistrationContextUpdate.
Arguments	userId	The user identifier represents the public user identity or IMPU.
	pin	The pin is optional and carries the password to be used towards the IG in case of HTTP Digest over HNI-IGI interface or SIP Digest if there is no HNI-IGI. If pin is not specified then the default user password shall be used. The pin used for digest authentication is limited to the HNI-IGI interface with the IG and shall not impact the HTTP Digest requests from within the DAE application. Support for this parameter is not applicable for non-native HNI-IGI.

void deRegisterUser( String userId )

Description

The indicated user is de-registered. Any sessions that may be open are closed. De-registration of default user has no effect nor de-registration of any users registered from a native application in the OITF.

Results from this method is sent to the callback method onRegistrationContextUpdate.

Arguments

userId

The user identifier represents the public user identity or IMPU.

UserDataCollection getAllUsers( )
Description	Return all the users that are currently provisioned in the IG. The first entry in the collection is the default user. The users are retrieved according to [OIPF_PROT2] section 5.4.6.4

void setUser( String userId )

Description

When invoked, any ongoing sessions for the current user shall be closed.

If setUser is unsuccessful due to user not being registered, it is necessary to first register the user and wait for a successful response to the onRegistrationContextUpdate callback function.

If the user gets deregistered (either by the local application or by the network), any ongoing sessions for the user shall be closed. The default user shall be automatically assumed for all services until overridden again by the setUser method.

Arguments

userId

The user identifier represents the public user identity or IMPU.

void subscribeNotification( FeatureTagCollection featureTagCollection, Boolean performUserRegistration )
Description	This method subscribes for new IMS out-of-session dialogues for the indicated application for the currently active user. The notification shall be notified using onNotification callback method. If the application that made the subscription closes then there is an automatic un-subscription to new notifications. Otherwise it is possible to perform unsubscribeNotification. Any new dialogues shall be notified over the callback method onNotification.
Arguments	featureTagCollection	The featureTagCollection object of the DAE application. If the value of this argument is NULL then all dialogs shall be reported.
	performUserRegistration	If this is `true` a new user registration is required. should be set to `false` if it is know that other applications will be registered shortly. This parameter is ignored in the case when the filtering of notifications is done locally. In this case, the initial registration for active user will include all feature tags.

void unsubscribeNotification( )

Description

The DAE application calling this method will be de-registered for notifications. Associated feature tag(s) for the DAE application are removed from the featureTagCollection object for the user. A re-registration will be performed for the corresponding user if notifications are not locally filtered.

Results from this method is sent to the callback method onNotificationResult.

7.8.1.4 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated, in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onNotificationResult	NotificationResult	Bubbles: No Cancellable: No Context Info: `resultMsg`
onNotification	Notification	Bubbles: No Cancellable: No Context Info: `callId`, `contact`, `from`, `to`
onRegistrationContextUpdate	RegistrationContextUpdate	Bubbles: No Cancellable: No Context Info: `user`, `state`, `errorCode`

Note: these DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving these events during the bubbling or the capturing phase. Applications that use DOM event handlers shall call the addEventListener() method on the application/oipfCommunicationServices object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.8.2 Extensions to application/oipfCommunicationServices for presence and messaging services

If a client has indicated support for the control of its presence and messaging functionality by a server by stating <presenceMessaging>true</presenceMessaging> as defined in section 9.3.9 in its capability description, the client shall support Communication Services through the use of the following non-visual embedded object:

<object type="application/oipfCommunicationServices"/>

The presence and messaging API provides for instant messaging, presence and contact list services. The messages can either be in a chat session using MSRP (see [OIPF_PROT2]) or page mode messages sent without a session. The support of presence and messaging shall follow the OMA specification [PRES], [IM].

The Communication Services API shall be supported in combined OITF and IG deployment cases. It may be supported in other deployment cases. The use of the HNI-IGI interface is optional between the OITF and IG when these are co-deployed.

7.8.2.1 Properties

function onIncomingMessage( String fromURI, String msg, Integer cid )

The function that is called when an incoming chat message is received for the active user.

The specified function is called with 3 arguments:

String fromURI – The sender address of the message.
String msg – The text message sent by the remote peer.
Integer cid – Chat session identifier, either the same as one received from the openChatSession() method or new if session is started by remote peer. Empty identifier if message is sent without a session.

function onContactStatusChange( String remoteURI, Integer state )

This function is called when status has changed for a contact in the contact list or a user used with the method subscribeToStatus().

The specified function is called with 2 arguments:

String remoteURI - The user address for which the status has changed.
Integer state – Set to 1 if the user is present, and 0 if not. Other values may be defined in the future.

function onNewWatcher( String remoteURI )

This function is called when a remote URI is requesting watcher authorization of the local user’s presentity.

The specified function is called with one argument:

String remoteURI - The remote user address which requested watcher authorization.

7.8.2.2 Methods

Integer openChatSession( String toURI )

Description

Opens a chat session with a remote user.

Returns an integer identifier for the chat session to be used when a message is sent in the chat session or to match when incoming message is received.

Arguments

toURI

The address of the remote chat user.

void sendMessageInSession( Integer cid, String msg )
Description	Sends a new text message in a chat session. The chat can either be started by the user by calling the method openChatSession() or can be a session received in the onIncomingMessage callback function.
Arguments	cid	The chat session identifier.
	msg	Text message to send.

void closeChatSession( Integer cid )
Description	Closes a chat session.
Arguments	cid	The chat session identifier.

void sendMessage( String toURI, String msg )
Description	Sends a new text message to a remote peer without starting a session.
Arguments	toURI	The address of the remote chat user.
	msg	Text message to send.

void setStatus( Integer state )
Description	Sets the presence state of the local user.
Arguments	state	Set to 1 if the user is present, and 0 if not. Other values may be defined in the future.

void subscribeToStatus( String remoteURI )
Description	Subscribe to status for a remote user.
Arguments	remoteURI	The address of the remote user.

ContactCollection getContacts( )
Description	Get the users contact list.

void allowContact( String remoteURI )
Description	Allows the watcher authorization to subscribe to the local user’s presentity.
Arguments	remoteURI	The address of the remote user.

void blockContact( String remoteURI )
Description	Blocks the watcher authorization to subscribe to the local user’s presentity.
Arguments	remoteURI	The address of the remote user.

void createContactList( String contactListUri, ContactCollection contacts )
Description	Creates a contact list.
Arguments	contactListUri	The public user identity or IMPU of the contact list.
	contacts	The collection of contact objects representing the members of the list.

ContactCollection getContacts( String contactListUri )
Description	Get the users in the specified contact list.
Arguments	contactListUri	The public user identity or IMPU of the contact list.

Boolean addToContactList( String contactListUri, Contact member )
Description	Updates the specified contact list by adding a new member to that list.
Arguments	contactListUri	The public user identity or IMPU of the contact list to be updated.
	member	The new contact to be added to the list.

Boolean removeFromoContactList( String contactListUri, Contact member )
Description	Updates the specified contact list by removing specified member from that list.
Arguments	contactListUri	The public user identity or IMPU of the contact list to be updated.
	member	The new contact to be removed from the list.

Boolean deleteContactList( String contactListUri )
Description	Deletes the specified contact list.
Arguments	contactListUri	The public user identity or IMPU of the contact list to be deleted.

void allowAllContacts( String domain )
Description	Allows all watchers belonging to specified domain authorization to subscribe to local user’s presentity. If `null`, then all contacts will be allowed.
Arguments	domain	Watchers belonging to this domain are authorized to subscribe. If `null`, then all watchers are authorized to subscribe irrespective of domain.

void blockAllContacts( String domain )
Description	Blocks all watchers belonging to specified domain authorization to subscribe to local user’s presentity. If `null`, then all contacts will be blocked.
Arguments	domain	Watchers belonging to this domain are denied authorization to subscribe. If `null`, then all watchers are blocked from subscribing irrespective of domain.

7.8.2.3 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onIncomingMessage	IncomingMessage	Bubbles: No Cancellable: No Context Info: `fromURI`, `msg`, `cid`
onContactStatusChange	ContactStatusChange	Bubbles: No Cancellable: No Context Info: `remoteURI`, `present`
onNewWatcher	NewWatcher	Bubbles: No Cancellable: No Context Info: `remoteURI`

7.8.3 The UserData class

7.8.3.1 Properties

readonly String userId

The user identifier represents the public user identity or IMPU.

readonly FeatureTagCollection featureTags

The feature tag data is optional. It carries a collection of feature tag objects associated with an application. For example the feature tag may be an ICSI or IARI or a feature tag identifying the service for. an incoming instant messages. The object includes feature tags related to both DAE and native applications in OITF.

readonly String friendlyName

The friendly name for the user. Used as display name in outgoing messages.

7.8.4 The UserDataCollection class

typedef Collection<UserData> UserDataCollection

The UserDataCollection class represents a collection of UserData objects. See Annex K for the definition of the collection template.

7.8.5 The FeatureTag class

7.8.5.1 Properties

readonly String featureTag

A string containing a featureTag value associated to an application. The featureTag value may have a value of null when used with the subscribeNotification() method on the application/oipfCommunicationServices object. This indicates that all dialogues are reported.

The feature tag shall populate the X-OITF- headers as specified in [TISPAN] section 5.6.2, [IM], [3GPPTS24.229], [RFC3840] and [RFC3841].

7.8.6 The FeatureTagCollection class

typedef Collection<FeatureTag> FeatureTagCollection

The FeatureTagCollection class represents a collection of FeatureTag objects. See Annex K for the definition of the collection template.

7.8.7 The Contact class

7.8.7.1 Properties

String contactId

The contact identifier represents the public user identity or IMPU used in communication with the contact.

String friendlyName

The friendly name for the user. Used as display name in outgoing messages.

7.8.8 The ContactCollection class

typedef Collection<Contact> ContactCollection

The ContactCollection class represents a collection of Contact objects. See Annex K for the definition of the collection template.

In addition to the methods and properties defined for generic collections, the ContactCollection class supports the additional methods defined below.

7.8.8.1 Methods

Boolean remove( String contactId )

Description

Removes the contact represented by contactId from the users contact list.

Returns true on success.

Arguments contactId Contact identifier of the user in the contact list.

Boolean add( Contact contact )

Description

Adds the contact represented by the Contact object to the users contact list.

Returns true on success.

Arguments contact Contact object to be added from users contact list.

7.8.9 Extensions to application/oipfCommunicationServices for voice telephony services

If an OITF has indicated support for full-duplex Voice Telephony Services functionality by a server by stating <telephony_services>true</telephony_services>, or <telephony_services video=“false”>true</telephony_services>, or <telephony_services video=“true”>true</telephony_services> as defined in section 9.3.9 in its capability description, the OITF shall support IMS through the use of the following non-visual embedded object:

<object type="application/oipfCommunicationServices"/>

The full-duplex Voice Telephony Services API provides support for managing the setup and life-cycle of a telephony call session. It also provides the methods to manage the capture devices and the list of preferred codecs to be used.

The full-duplex Voice Telephony Services API may be supported in the combined OITF and IG deployment cases as well as the separated OITF and IG case. It may be supported in other deployment cases. The use of the HNI-IGI interface is optional between the OITF and IG when these are co-deployed.

7.8.9.1 Properties

function onCallEvent( Integer eventType, Integer cid, Integer status, String info )

The function that is called when an event related to the identified call is notified. The specified function is called with four arguments:

Integer eventType – the type of event. Valid values are:

Value	Description
0	EVENT_INCOMING_CALL: an incoming call is received for the active user
1	EVENT_CALL_PROGRESS: called when the outgoing call is in progress (the request has been received by the remote peer and the local signalling engine is waiting for an answer).
2	EVENT_CALL_RESULT: notifies the result of an outgoing call.
3	EVENT_HANGUP: called when the remote peer hang-up the call.
4	EVENT_SESSION_START: the call session is established and running (media streams can be transmitted and rendered).
5	EVENT_SESSION_END: the call session ended and the related resources are released.
6	EVENT_INCOMING_UPDATE: an incoming update request is received for the active user. (*)
7	EVENT_UPDATE_RESULT: notifies the result of an outgoing update request. (*)
8	EVENT_SESSION_UPDATE: the update of the identified call session is active (e.g.: additional media streams can be transmitted and rendered). (*)
9	EVENT_ERROR: notifies an error event raised during the identified call session.

(*) Values not supported for voice only telephony services

Integer cid – call session identifier for the application (Call ID). Call IDs are unique, locally generated positive integer values used to identify a call session.
Integer status – status information on the event. The content depends on the event
String info – text field with additional information. The content depends on the event.

The values of the cid, status and info parameters are defined according to the type of event. Any parameters which are unused for an event shall have the value undefined.

EVENT_INCOMING_CALL

cid: call session identifier for the application (Call ID).
status: call type Identifier. Valid Call Type values are:

Value Description

0 AUDIO_ONLY: full-duplex voice only call

1 VIDEO_ONLY: full-duplex video only call (*)

2 AUDIO_VIDEO: full-duplex video call (voice + video) (*)

(*) Values not supported for voice only telephony services
info: originating URI. The sender address of the call.

EVENT_CALL_PROGRESS

cid: call session identifier for the application (Call ID).
status: The type of notification coming from the call in progress. This release provides support for a single value; extensions may be defined in future versions.

Value Description

0 RINGING

EVENT_CALL_RESULT

cid: call session identifier for the application (Call ID).

status: the result of an outgoing call. Valid values are:

Value	Description
0	ACCEPT: the call request has been accepted by the remote peer
1	REFUSE: the call request has been refused by the remote peer
2	TIMEOUT: the call request has been refused due to no response by the remote peer
3	BUSY: the remote peer is currently busy
4	ABORT: a general error occurred

info: if status is equal to 0 (ACCEPT), then the info parameter contains the string representing the value of call type Identifier resulting from the negotiation between the peers. Valid Call Type values are shown in the table below:

Value Description

0 AUDIO_ONLY: full-duplex voice only call

1 VIDEO_ONLY: full-duplex video only call (*)

2 AUDIO_VIDEO: full-duplex video call (voice + video) (*)

(*) Values not supported for voice only telephony services

EVENT_HANGUP

cid: call session identifier for the application (Call ID).

EVENT_SESSION_START

cid: call session identifier for the application (Call ID).

EVENT_SESSION_END

cid: call session identifier for the application (Call ID).

EVENT_SESSION_INCOMING

cid: call session identifier for the application (Call ID).
status: call type Identifier. Valid Call Type values are:

Value Description

0 AUDIO_ONLY: full-duplex voice only call

1 VIDEO_ONLY: full-duplex video only call

2 AUDIO_VIDEO: full-duplex video call (voice + video)

EVENT_UPDATE_RESULT

cid: call session identifier for the application (Call ID).

status: the result of an outgoing call. Valid values are:

Value	Description
0	ACCEPT: the call request has been accepted by the remote peer
1	REFUSE: the call request has been refused by the remote peer
2	TIMEOUT: the call request has been refused due to no response by the remote peer
3	ABORT: a general error occurred

EVENT_SESSION_UPDATE

cid: call session identifier for the application (Call ID).

EVENT_ERROR

cid: call session identifier for the application (Call ID).
status: the error code of the referenced call. Valid values are:

Value Description

0 ERROR_MEDIA: A media subsystem error

1 ERROR_SIGNALING: A signaling subsystem error
info: supplementary textual information for the error identified by the status parameter.

readonly StringCollection callParameters

The list of call parameters supported.

7.8.9.2 Methods

Integer call( String toURI, Integer callType )

Description

Opens a telephony session with a remote user. Returns a unique, locally generated, positive integer identifier for the call session (call session ID). Returns null if an error occurred. The current specification provides support for a single active call session only.

Arguments toURI The address of the remote user.

callType

Valid Call Type values are shown in the table below.

Value	Description
0	AUDIO_ONLY: activate a full-duplex voice only call
1	VIDEO_ONLY: activate a video only call (*)
2	AUDIO_VIDEO: activate a full-duplex video call (*)

(*) Parameters and values not supported for voice only telephony services

Integer answer( Integer cid, Integer response )

Description

Answers an incoming call. Returns true if the method is successfully executed; false if an error occurred.

Arguments cid Call session identifier for the application (Call ID).

response

Valid response values are shown in the table below.

Value	Description
0	ANSWER_ACCEPT: Accepts the incoming call
1	ANSWER_REFUSE: Refuses the incoming call
2	ANSWER_TIMEOUT: Refuses the incoming call due to no answer from user
3	ANSWER_BUSY: Refuses the incoming call sending a busy

Integer hangup( Integer cid )
Description	Closes a telephony session. Returns `true` if the method is successfully executed; `false` if an error occurred.
Arguments	cid	Call session identifier for the application (Call ID).

DeviceInfoCollection getDeviceList( Integer deviceType )

Description

Returns the list of devices installed on the terminal (or connected) for a specific device type. The device in the first position of the returned list is the default device to be used by the terminal. The position of each device is consistent between method invocations as long as no new devices are connected to the OITF or removed. If an error occurs, the method returns null.

Arguments

deviceType

Valid types of device are shown in the table below.

Value	Description
0	Audio Capture devices
1	Video Capture devices (*)

(*) Parameters and values not supported for voice only telephony services

Boolean setCaptureDevice( Integer deviceType, Integer deviceID )

Description

Sets the capture device (for a specific device type) that will be used during the call. This method does not affect currently ongoing call sessions. Returns true if the method is successfully executed; false if an error occurred.

If the application does not set capture devices (i.e. it does not invoke setCaptureDevice() ) then the devices that will be used for the next call session will be the ones in the first position in the DeviceInfoCollection objects returned by the getDeviceList() method for each device type.

Arguments

deviceType

Valid types of device are shown in the table below.

Value	Description
0	Audio Capture devices
1	Video Capture devices (*)

(*) Parameters and values not supported for voice only telephony services

deviceID The specific DeviceInfo object id property (in a DeviceInfoCollection) identifying the capture device that will be used for the call

CodecInfoCollection getCodecList( Integer streamType )

Description

Returns the list of codec available on the terminal for a specific stream type. If an error occurs or no codecs are available for the specified stream type, the method returns null.

Arguments

streamType

Valid stream type values are shown in the table below.

Value	Description
0	Audio
1	Video(*)

(*) Parameters and values not supported for voice only telephony services

Boolean setPreferredCodecList( Integer streamType, CodecInfoCollection preferredCodecList )

Description

Sets a list of preferred codec to be used in the call setup for a specific stream type. Returns true if the method is successfully executed; false if an error occurred. Invocation of this method does not affect currently ongoing call sessions.

Arguments

streamType

Valid stream type values are shown in the table below.

Value	Description
0	Audio
1	Video(*)

(*) Parameters and values not supported for voice only telephony services

preferredCodecList List of codecs to be used during the call setup negotiation (ordered by preference)

String getCallParameter( Integer cid, String parameter )

Description

Returns a parameter value for the call session identified by the cid parameter. This method can be invoked before a call session creation or during an ongoing call session. If the cid parameter is null then the retrieved settings will be those that will be applied to the next call sessions that will be created (default for outgoing or incoming call). Returns the value of the parameter or null if an error occurred or the parameter is not supported.

Arguments cid Call session identifier for the application (Call ID).

parameter

Mandatory values are shown in the table below. Parameter names are not case sensitive.

Parameter name	Description
AUDIO_PAUSE	Audio transmission pause. The parameter can be `TRUE` or `FALSE`.
VIDEO_PAUSE	Video transmission pause. The parameter can be `TRUE` or `FALSE`. (*)
VIDEO_FPS	Captured video frame per second (*)
VIDEO_SIZE	Captured video frame per second (*) 176x144 352x288 640x480
MEDIA_BW	Audio and video (if available) transmission gross bandwidth (Kbps)

(*) Parameters and values not supported for voice only telephony services

Boolean setCallParameter( Integer cid, String parameter, String value )

Description

Sets parameter value for the call session identified by the cid parameter. This method can be invoked before a call session creation or during an ongoing call session. If cid parameter is defined, then the settings will be applied to the call session identified by this Call ID. If cid parameter is null then the settings will be applied at the next call sessions that will be created (default for outgoing or incoming call). Returns true if the method is successfully executed; false if an error occurred.

Arguments cid Call session identifier for the application (Call ID).

parameter

Mandatory values are shown in the table below. Parameter names are not case sensitive.

Parameter name	Description
AUDIO_PAUSE	Audio transmission pause. The parameter can be `TRUE` or `FALSE`.
VIDEO_PAUSE	Video transmission pause. The parameter can be `TRUE` or `FALSE`. (*)
VIDEO_FPS	Captured video frame per second (*)
VIDEO_SIZE	Captured video frame per second (*) 176x144 352x288 640x480
MEDIA_BW	Audio and video (if available) transmission gross bandwidth (Kbps)

(*) Parameters and values not supported for voice only telephony services

value The value for the parameter

7.8.9.3 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onCallEvent	CallEvent	Bubbles: No Cancellable: No Context Info: `eventType`, `cid`, `status`, `info`

7.8.10 Extensions to application/oipfCommunicationServices for video telephony services

If an OITF has indicated support for full-duplex Video Telephony Services functionality by a server by stating <telephony_services video="true">true</telephony_services> as defined in section 9.3.9 in its capability description, the OITF shall support communication services through the use of the following non-visual embedded object:

<object type="application/oipfCommunicationServices"/>

The extensions for telephony services provide support for:

Parameters and values related to video (identified by (*) in previous sections).
Methods to manage the rendering of local and remote video streams through CEA-2014 A/V Control or HTML5 video element.
Methods to send a session update request and to accept or refuse it. A session update is typically invoked when users want to add video to their currently ongoing voice-only call session.

When a remote or local video is activated on a target CEA-2014 A/V Control or HTML5 video element, any currently displayed video content on that object is stopped and released. The activated stream is automatically played.

The full-duplex Video Telephony Services API may be supported in the combined OITF and IG deployment cases as well as the separated OITF and IG case. It may be supported in other deployment cases. The use of the HNI-IGI interface is optional between the OITF and IG when these are co-deployed.

7.8.10.1 Methods

Boolean showRemoteVideo( Integer cid, Integer mode, String idVideoCallObject )

Description

Activates or deactivates remote peer video rendering. Returns true if the method is successfully executed; false if an error occurred. This method can be invoked as soon as a valid call id is available: after a call method invocation or when an incoming call is notified.

Arguments cid Call session identifier for the application (Call ID).

mode

Valid values are shown in the table below.

Parameter name	Description
0	Deactivates remote video
1	Activates remote video

idVideoCallObject ID attribute associated with the HTML tag of the A/V Control object as defined in section 7.14 or HTML5 video element in which the video frames will be rendered

Boolean showLocalVideoPreview( Integer cid, Integer mode, String idVideoCallObject )

Description

Activates or deactivates local video preview. This method can be invoked before a call session creation or during an ongoing call session. If cid parameter is defined, then the local video stream will be one currently used in the call session identified by this Call ID. If cid parameter is null then the local video stream will be the one that will be used in the next call session that will be created (outgoing or incoming call). Returns true if the method is successfully executed; false if an error occurred. This method can be invoked before or after the call session setup

Arguments cid Call session identifier for the application (Call ID).

mode

Valid values are shown in the table below.

Parameter name	Description
0	Deactivates local video preview
1	Activates local video preview

idVideoCallObject ID attribute associated with the HTML tag of the A/V Control object as defined in section 7.14 or HTML5 video element in which the video frames will be rendered

Boolean callUpdate( Integer cid, Integer callType )

Description

Requests an update for the call session identified by the cid parameter. Returns true if the method is successfully executed; false if an error occurred.

Arguments cid Call session identifier for the application (Call ID).

callType

Valid values are shown in the table below.

Parameter name	Description
0	AUDIO_ONLY: activate a full-duplex voice only call
1	VIDEO_ONLY: activate a video only call
2	AUDIO_VIDEO: activate a full-duplex video call (voice + video)

Boolean callAnswerUpdate( Integer cid, Integer responseUpdate )

Description

Answers an incoming call. Returns true if the method is successfully executed; false if an error occurred. Note that if an OITF supports full-duplex voice only calls, then the underlying signalling layer shall automatically refuse any update request to video. Requests an update for the call session identified by the cid parameter.

Arguments cid Call session identifier for the application (Call ID).

responseUpdate

Valid values are shown in the table below.

Parameter name	Description
0	UPDATE_ACCEPT: Accepts the update request
1	UPDATE_REFUSE: Refuses the update request
2	UPDATE_TIMEOUT: Refuses the update request due to no answer from user

7.8.11 The DeviceInfo class

Represents a device installed on or connected to the OITF. A device can be for example a capture device, a rendering device etc.

7.8.11.1 Properties

readonly Integer id

A unique, implementation dependent identifier for the capture device defined by the local system. The system shall guarantee that the id assigned to a device will not change during the life of the application

readonly Integer deviceType

The type of device, valid values are:

Value	Description
0	Audio Capture devices
1	Video Capture devices (*)

(*) Parameters and values not supported for voice only telephony services

readonly String deviceName

The friendly name for the capture device. May be used in user messages.

readonly String deviceProductName

The complete name, model number etc. for the capture device.

7.8.12 The DeviceInfoCollection class

typedef Collection<DeviceInfo> DeviceInfoCollection

The DeviceInfoCollection class represents a collection of DeviceInfo objects. See Annex K for the definition of the collection template.

7.8.13 The CodecInfo class

7.8.13.1 Properties

readonly String codecName

The codec name.

readonly String mimeType

The codec mime-type. A list of possible codec mime-types for multimedia telephony supported by the OIPF Solution are listed in Table 6 of [OIPF_MEDIA2].

readonly String profile

The codec profile. Normative definition of a subset of standard codec functionalities. The codec profiles for multimedia telephony supported by the OIPF Solution are listed in section 5.1.3 of [OIPF_MEDIA2].

7.8.14 The CodecInfoCollection class

typedef Collection<CodecInfo> CodecInfoCollection

The CodecInfoCollection class represents a collection of CodecInfo objects. See Annex K for the definition of the collection template.

In addition to the methods and properties defined for generic collections, the CodecInfoCollection class supports the additional properties and methods defined below.

7.8.14.1 Methods

Boolean moveAt( Integer targetIndex, Integer index )
Description	Moves a CodecInfo item from the specified `index` to the specified `targetIndex`. The operation is performed through an item removal and an insertion of the same item in a new position. The `targetIndex` is the position in which the element shall be inserted considering position indexes before item removal. During removal and insertion, the other items will shift accordingly. This method shall return `true` if the operation succeeded, or `false` if an invalid index was specified (e.g. index > length).
Arguments	targetIndex	The index in the list to which the item should be moved.
	index	The index in the list of the item that will be moved.

Boolean remove( Integer index )
Description	Removes the item at the specified index from the `CodecInfoCollection`. The other items shall shift accordingly. Returns `true` if the operation succeeded, or `false` if an invalid index was specified.
Arguments	index	The index of the item to be removed.

7.9 Parental rating and parental control APIs

This section defines APIs related to parental ratings and parental control.

Sections 7.9.1 through 7.9.3 define a new JavaScript embedded object “application/oipfParentalControlManager” and the related ParentalRatingScheme and ParentalRatingSchemeCollection objects, which allows applications to construct a new parental rating scheme (and a parental rating value using that scheme), and to temporarily enable or disable viewing of a content item. These APIs shall be supported if an OITF supports parental controls as indicated by value “true” for element <parentalcontrol> (as defined by section 9.3.5) in its capability profile.

Sections 7.9.4 and 7.9.5 define the ParentalRating and ParentalRatingCollection objects. These objects are used/referenced by various other objects, such as the Programme object as defined in section 7.16.2 to indicate a particular parental rating. The support for these objects depends on the support for the sections in which these are used.

7.9.1 The application/oipfParentalControlManager embedded object

If an OITF supports parental controls as indicated by value “true” for element <parentalcontrol> (as defined by section 9.3.5) in its capability profile, the OITF shall support the application/oipfParentalControlManager object with the following interface.

The following example shows a possible usage scenario for the application/oipfParentalControlManager, i.e. to add a new parental rating scheme to the parentalRatingSchemes collection:

//get a reference to the parental control manager object
var pcManager = document.getElementById("pcmanager");

// add a new rating scheme – in this case, the MPAA rating scheme
pcManager.parentalRatingSchemes.addParentalRatingScheme(
    "urn:mpeg:mpeg7:cs:MPAAParentalRatingCS:2001", "G,PG,PG-13,R,NC-17,NR" );

The following example shows a possible usage scenario for the application/oipfParentalControlManager, i.e. to temporarily unblock a blocked content item (e.g. after asking the user to enter the parental control pin):

// If a content item is blocked, the event “onParentalRatingChange” can be captured, and 
// the setParentalControlStatus() method can be used to temporarily unblock the content 
// (e.g. after asking the user to enter the parental control pin)

function askForPin() { ... }

...

//get a reference to the A/V player object 
var avPlayer = document.getElementById("avPlayer");

avPlayer.onParentalRatingChange = function() {
  var pin=askForPin();pcManager.setParentalControlStatus(pin, false)};

7.9.1.1 Properties

readonly ParentalRatingSchemeCollection parentalRatingSchemes

A reference to the collection of rating schemes known by the OITF.

readonly Boolean isPINEntryLocked

The lockout status of the parental control PIN. If the incorrect PIN has been entered too many times in the configured timeout period, parental control PIN entry shall be locked out for a period of time determined by the OITF.

7.9.1.2 Methods

Integer setParentalControlStatus( String pcPIN, Boolean enable )

Description

As defined in [OIPF_CSP2], the OITF shall prevent the consumption of a programme when its parental rating doesn't meet the parental rating criterion currently defined in the OITF. Calling this method with enable set to false will temporarily allow the consumption of any blocked programme.

Setting the parental control status using this method shall set the status until the consumption of any of all the blocked programmes terminates (e.g. until the content item being played is changed), or another call to the setParentalControlStatus() method is made.

Setting the parental control status using this method has the following effect; for the Programme and Channel objects as defined in sections 7.16.2 and 7.13.11, the blocked property of a programme or channel shall be set to true for programmes whose parental rating does not meet the applicable parental rating criterion, but the locked property shall be set to false.

This operation to temporarily disable parental rating control shall be protected by the parental control PIN (i.e. through the pcPIN argument). The return value indicates the success of the operation, and shall take one of the following values:

Value	Description
0	The PIN is correct.
1	The PIN is incorrect.
2	PIN entry is locked because an invalid PIN has been entered too many times. The number of invalid PIN attempts before PIN entry is locked is outside the scope of this specification.

Arguments pcPIN The parental control PIN.

enable Flag indicating whether parental control should be enabled.

Boolean getParentalControlStatus( )
Description	Returns a flag indicating the temporary parental control status set by setParentalControlStatus(). Note that the returned status covers parental control functionality related to all rating schemes, not only the rating scheme upon which the method is called.

Boolean getBlockUnrated( )
Description	Returns a flag indicating whether or not the OITF has been configured by the user to block content for which a parental rating is absent.

Integer setParentalControlPIN( String oldPcPIN, String newPcPIN )

Description

Set the parental control PIN.

This operation shall be protected by the parental control PIN (if PIN entry is enabled). The return value indicates the success of the operation, and shall take one of the following values:

Value	Description
0	The PIN is correct.
1	The PIN is incorrect.
2	PIN entry is locked because an invalid PIN has been entered too many times. The number of invalid PIN attempts before PIN entry is locked is outside the scope of this specification.

Arguments

oldPcPIN

The current parental control PIN.

newPcPIN

The new value for the parental control PIN.

Integer unlockWithParentalControlPIN( String pcPIN, Object target )

Description

Unlock the object specified by target for viewing if pcPIN contains the correct parental control PIN.

The object type of target can be one of the following:

video/broadcast object, in which case the content being presented through this object shall be unlocked until a new channel is selected.
A/V Control object, in which case the content being presented through this object shall be unlocked until a new item of content is played using this object

Otherwise an Invalid object error code shall be returned.

The return value indicates the success of the operation, and shall take the following values:

Value	Description
0	The PIN is correct.
1	The PIN is incorrect.
2	PIN entry is locked because an invalid PIN has been entered too many times. The number of invalid PIN attempts before PIN entry is locked is outside the scope of this specification.
3	Invalid object.

Arguments pcPIN The parental control PIN.

target The object to be unlocked.

Integer verifyParentalControlPIN( String pcPIN )

Description

Verify that the PIN specified by pcPIN is the correct parental control PIN.

This method will return one of the following values:

Value	Description
0	The PIN is correct.
1	The PIN is incorrect.
2	PIN entry is locked because an invalid PIN has been entered too many times. The number of invalid PIN attempts before PIN entry is locked is outside the scope of this specification.

Arguments pcPIN The parental control PIN to be verified.

Integer setBlockUnrated( String pcPIN, Boolean block )

Description

Set whether programmes for which no parental rating has been retrieved from the metadata client nor defined by the service provider should be blocked automatically by the terminal.

This operation shall be protected by the parental control PIN (if PIN entry is enabled). The return value indicates the success of the operation, and shall take one of the following values:

Value	Description
0	The PIN is correct.
1	The PIN is incorrect.
2	PIN entry is locked because an invalid PIN has been entered too many times. The number of invalid PIN attempts before PIN entry is locked is outside the scope of this specification.

Arguments

pcPIN

The parental control PIN.

block

Flag indicating whether programmes shall be blocked.

7.9.2 The ParentalRatingScheme class

typedef Collection<String> ParentalRatingScheme

A ParentalRatingScheme describes a single parental rating scheme that may be in use for rating content, e.g. the MPAA or BBFC rating schemes. It is a collection of strings representing rating values, which next to the properties and methods defined below shall support the array notation to access the rating values in this collection. For the natively OITF supported parental rating systems the values shall be ordered by the OITF to allow the rating values to be compared in the manner as defined for property threshold for the respective parental rating system. Using a threshold as defined in this API may not necessarily be the proper way in which parental rating filtering is applied on the OITF, e.g. the US FCC requirements take precedence for device to be imported to the US.

The parental rating schemes supported by a receiver may vary between deployments.

See Annex K for the definition of the collection template. In addition to the methods and properties defined for generic collections, the ParentalRatingScheme class supports the additional properties and methods defined below.

7.9.2.1 Properties

readonly String name

The unique name that identifies the parental rating scheme. Valid strings include:

the URI of one of the MPEG-7 classification schemes representing a parental rating scheme as defined by the “uri” attribute of one of the parental rating <ClassificationScheme> elements in [MPEG-7].
the string value “urn:oipf:GermanyFSKCS” to represent the GermanyFSK rating scheme as defined in [OIPF_META2].
This classification scheme is in all versions of the OIPF specification, but has been versioned. In R2v2.3 it is urn:oipf:cs:GermanyFSKCS:2008
the string value “dvb-si”: this means that the scheme of a minimum recommended age encoded as per ratings 0x01 to 0x0f in the parental rating descriptor from [EN300468], is used to represent the parental rating values.
NOTE: If the broadcaster defined range from 0x10 to 0xff is used then that would be a different parental rating scheme and not "dvb-si".

If the value of “name” is “dvb-si”, the ParentalRatingScheme remains empty (i.e. ParentalRatingScheme.length == 0).

readonly String threshold

The parental rating threshold that is currently in use by the OITF’s parental control system for this rating scheme, which is encoded as a ParentalRating object in the following manner:

If the value of the “name” property of the ParentalRatingScheme object is unequal to “dvb-si”, then:

the “value” property of the threshold object represents the value for which items with a ParentalRating.value greater or equal to the “value” property of the threshold object have been configured by the OITF’s parental control subsystem to be blocked.
the “labels” property of the threshold object represents the bit map of zero or more flags for which items with a ParentalRating.labels property with any of the same flags set have been configured by the OITF’s parental control subsystem to be blocked.

If the value of the “name” property of the ParentalRatingScheme object is “dvb-si”, the threshold indicates a minimum recommended age encoded as per [EN300468] at which or above which the content is being blocked by the OITF’s parental control subsystem

Note that the value property as an index into the ParentalRating object that defines the threshold can be 1 larger than the value of ParentalRatingScheme.length to convey that no content is being blocked by the parental control subsystem.

7.9.2.2 Methods

Integer indexOf( String ratingValue )
Description	Return the index of the rating represented by attribute `ratingValue` inside the parental rating scheme string collection, or `-1` if the rating value cannot be found in the collection.
Arguments	ratingValue	The string representation of a parental rating value. See property name in section 7.9.4.1 for more information about possible values. Values are not case sensitive.

String iconUri( Integer index )
Description	Return the URI of the icon representing the rating at `index` in the rating scheme, or undefined if no item is present at that position. If no icon is available, this method shall return `null`.
Arguments	index	The index of the parental rating scheme.

7.9.3 The ParentalRatingSchemeCollection class

typedef Collection<ParentalRatingScheme> ParentalRatingSchemeCollection

A ParentalRatingSchemeCollection represents a collection of parental rating schemes, e.g. as returned by property parentalRatingSchemes of the “application/oipfParentalControlManager” object as defined in section 7.9.1. Next to the properties and methods defined below a ParentalRatingSchemeCollection object shall support the array notation to access the parental rating scheme objects in this collection.

See Annex K for the definition of the collection template. In addition to the methods and properties defined for generic collections, the ParentalRatingSchemeCollection class supports the additional properties and methods defined below.

7.9.3.1 Methods

ParentalRatingScheme addParentalRatingScheme( String name, String values )
Description	Create a new ParentalRatingScheme object and adds it to the `ParentalRatingSchemeCollection`. Applications may use this method to register additional parental rating schemes with the platform. When registered, the new parental rating scheme shall (temporarily) be accessible through the parentalRatingSchemes property of the “application/oipfParentalControlmanager” object as defined in section 7.9.1. The application shall make sure that the values are ordered in such a way to allow the rating values to be compared in the manner as defined for the `threshold` property for the respective parental rating system. This method returns a reference to the ParentalRatingScheme object representing the added scheme. If the value of the `name` parameter corresponds to an already-registered rating scheme, this method returns a reference to the existing ParentalRatingScheme object. If the newly defined rating scheme was not known to the OITF, the scheme may be stored persistently, and the OITF may offer a UI to set the parental rating blocking criteria for the newly added parental rating scheme. If the OITF has successfully stored (persistently or not persistently) the additional parental rating scheme, the method shall return a non-`null` ParentalRatingScheme object.
Arguments	name	A unique string identifying the parental rating scheme to which this value refers. See property name in section 7.9.2.1 for more information about possible values.
	values	A comma-separated list of the possible values in the rating scheme, in ascending order of severity. In case the rating scheme is one of the [MPEG-7] rating classification schemes, this means that the list of parental rating values contains the values as specified by the `<Name>` elements of the `<Term>` elements in the order of appearance as they are defined for the classification scheme, with the exception of the Internet Content Rating Association (ICRA) based ratings, for which the reverse order has to be applied. The values must be ordered in such a way to allow the rating values to be compared in the manner as defined for property `threshold` for the respective parental rating system.

ParentalRatingScheme getParentalRatingScheme( String name )
Description	This method returns a reference to the ParentalRatingScheme object that is associated with the given scheme as specified through parameter “`name`”. If the value of `name` does not correspond to the `name` property of any of the ParentalRatingScheme objects in the ParentalRatingSchemeCollection, the method shall return `undefined`.
Arguments	name	The unique name identifying a parental rating scheme.

7.9.4 The ParentalRating class

A ParentalRating object describes a parental rating value for a programme or channel. The ParentalRating object identifies both the rating scheme in use, and the parental rating value within that scheme.

In case of a BCG the values of the properties in this object will be read from the ParentalGuidance element that is the child of a programme’s BCG description.

Example usage:

<!-- This example shows a possible usage scenario for the ParentalRating 
     data structure, i.e. to create a new programme to record and set 
     parental rating to MPAA parental rating to PG-13.    
-->
...
<script type="text/javascript" language="Javascript1.5">

// get a reference to the recorder object
var recorder = document.getElementById("recorder");

// create new programme to record 
var myProgramme = recorder.createProgrammeObject();

// add a new parental rating value to myProgramme, in this case the 
// programme is rated PG-13 for the US using the MPAA Parental rating scheme.
myProgramme.parentalRatings.addParentalRating(
    "urn:mpeg:mpeg7:cs:MPAAParentalRatingCS:2001", "PG-13", 2, 0, "US"
    );

</script>
...
<object id="recorder" type="application/oipfRecordingScheduler"/>

7.9.4.1 Properties

readonly String name

The string representation of the parental rating value for the respective rating scheme denoted by property scheme.

Valid strings include:

if the value of property scheme represents one of the parental rating classification scheme names identified by [MPEG-7]: the string representation of one of the parental rating values as defined by one of the <Name> elements.
if the value of property scheme is “urn:oipf:GermanyFSKCS”, the string representation of one the values for the GermanyFSK rating scheme as defined in [OIPF_META2].
This classification scheme is in all versions of the OIPF specification, but has been versioned. In R2v2.3 it is urn:oipf:cs:GermanyFSKCS:2008
if the value of property scheme is equal to “dvb-si”, this means that the scheme of a minimum recommended age encoded as per ratings 0x01 to 0x0f in the parental rating descriptor from [EN300468], which corresponds to rating_type 0 in [IEC62455].
NOTE: If the broadcaster defined range from 0x10 to 0xff is used then that would be a different parental rating scheme and not "dvb-si".

An example of a valid parental rating value is “PG-13”.

readonly String scheme

Unique name identifying the parental rating guidance scheme to which this parental rating value refers. Valid strings include:

the URI of one of the MPEG-7 classification schemes representing a parental rating scheme as defined by the “uri” attribute of one of the parental rating <ClassificationScheme> elements in [MPEG-7].
the string value “urn:oipf:GermanyFSKCS” to represent the GermanyFSK rating scheme as defined in [OIPF_META2]
This classification scheme is in all versions of the OIPF specification, but has been versioned. In R2v2.3 it is urn:oipf:cs:GermanyFSKCS:2008
.
the string value “dvb-si”: this means that the scheme of a minimum recommended age encoded as per [EN300468], is used to represent the parental rating values.

readonly String value

The parental rating value represented as an index into the set of values defined as part of the ParentalRatingScheme identified through property “scheme”.

If an associated ParentalRatingScheme object can be found by calling method getParentalRatingScheme() on property parentalRatingSchemes of the application/oipfParentalControlManager object and the value of property scheme is not equal to “dvb-si”, then the value property shall represent the index of the parental rating value inside the ParentalRatingScheme object, or -1 if the value cannot be found. If the value of property scheme is equal to “dvb-si”, then this property shall be the integer representation of the string value of ParentalRating property name.

If no associated ParentalRatingScheme object can be found by calling method getParentalRatingScheme on property parentalRatingSchemes of the application/oipfParentalControlManager object, then the value property shall have value undefined.

readonly Integer labels

The labels property represents a set of parental advisory flags that may provide additional information about the rating.

The value of this field is a 32 bit integer value that represents a binary mask corresponding to the sum of zero or more label values defined in the table below. If no labels have been explicitly set, the value for the “labels” property shall be 0.

Valid labels include:

Value	Description
1	Indicates that a content item features sexual suggestive dialog.
2	Indicates that a content item features strong language.
4	Indicates that a content item features sexual situations.
8	Indicates that a content item features violence.
16	Indicates that a content item features fantasy violence.
32	Indicates that a content item features disturbing scenes.
64	Indicates that a content item features portrayals of discrimination.
128	Indicates that a content item features scenes of illegal drug use.
256	Indicates that a content item features strobing that could impact viewers suffering from Photosensitive epilepsy.

readonly String region

The region to which the parental rating value applies as an alpha-2 region code as defined in ISO 3166-1. Returns undefined if no specific region has been defined.

7.9.5 The ParentalRatingCollection class

typedef Collection<ParentalRating> ParentalRatingCollection

A ParentalRatingCollection represents a collection of parental rating values. See Annex K for the definition of the collection template.

In addition to the methods and properties defined for generic collections, the ParentalRatingCollection class supports the additional properties and methods defined below.

7.9.5.1 Methods

void addParentalRating( String scheme, String name, Integer value, Integer labels, String region )
Description	Creates a ParentalRating object instance for a given parental rating scheme and parental rating value, and adds it to the `ParentalRatingCollection` for a programme or channel.
Arguments	scheme	A unique string identifying the parental rating scheme to which this value refers. See property scheme in section 7.9.4.1 for more information about possible values.
	name	A string representation of the parental rating value. See property name in section 7.9.4.1 for more information about possible values. Values are not case sensitive.
	value	The parental rating value represented as an Integer. See property value in section 7.9.4.1 for more information about possible values.
	labels	A set of content rating labels that may provide additional information about the rating. See property labels in section 7.9.4.1 for more information about possible values.
	region	The region to which the parental rating value applies as an alpha-2 region code as defined in ISO 3166-1. The value of this argument must be `null` or `undefined` if no specific region has been identified. Values are not case sensitive.

7.10 Scheduled Recording APIs

This section describes the APIs needed to support control by a DAE application of the recording (PVR) functionality available to an OITF, including time-shift support, scheduled recording and storage of basic metadata about recorded items. Changes made by a DAE application to properties that can also be set by the OITF may be overwritten by the OITF from metadata without warning.

This section shall apply for OITFs that have indicated <recording> with value “true” as defined in section 9.3.3 in its capability description.

7.10.1 The application/oipfRecordingScheduler embedded object

The OITF shall support the scheduling of recordings of broadcasts through the use of the following non-visual embedded object:

<object type="application/oipfRecordingScheduler"/>

Note that the functionality in this section shall adhere to the security model as specified in section 10.1.

Which channels can be recorded shall be indicated by the ipBroadcast, DASH and HAS attributes in the PVR capability indication (see section 9.3.3). Within the channels indicated by these attributes, recording of both channels stored in the channel list and locally defined channels shall be supported.

7.10.1.1 Methods

ScheduledRecording record( Programme programme )

Description

Requests the scheduler to schedule the recording of the programme identified by the programmeID property of the programme.

If the programmeIDType of the programme has the value ID_TVA_GROUP_CRID then the ScheduledRecording object returned by this method shall be a “parent” scheduled recording object that conceptually represents the recording. Each individual programme in the shall be represented by a separate ScheduledRecording object. Note that ScheduledRecording objects for individual programmes may not be created until the CRID has been partially or completely resolved. The start time, duration and other properties of the programme shall not be used for scheduling any recording.

Individual programmes shall be recorded if any entries in a programme’s associated groupCRIDs collection matches the group CRID specified in the programmeID property of any “parent” recording.

The other data contained in the programme object is used solely for annotation of the (scheduled) recording. If such programme metadata is provided, it shall be retained in the ScheduledRecording object that is returned if the recording of the programme was scheduled successfully, reflecting the possibility that not all relevant metadata might be available to the scheduler. When the programme is recorded, the metadata in the associated Recording object shall be updated with the metadata from the broadcast stream if such metadata is available. If the recording could not be scheduled due to a scheduling conflict or lack of resources the value null is returned.

Note that the actual implementation of this method should enable the scheduler to identify the domain of the service that issues the scheduling request in order to support future retrieval of the scheduled recording through the getScheduledRecordings method.

Arguments programme The programme to be recorded, as defined in section 7.16.2.

ScheduledRecording recordAt( Integer startTime, Integer duration, Integer repeatDays, String channelID )

Description

Requests the scheduler to schedule the recording of the broadcast to be received over the channel identified by channelID, starting at startTime and stopping at startTime + duration. If the recording was scheduled successfully, the resulting ScheduledRecording object is returned. If the recording could not be scheduled due to a scheduling conflict or lack of resources the value null is returned.

The OITF should associate metadata with recordings scheduled using this method. This metadata may be obtained from the broadcast being recorded (for example DVB-SI in an MPEG-2 transport stream) or from other sources of metadata. If an application anticipates that the OITF may not be able to obtain any metadata, it should instead of using this method;

create a Programme object (using the createProgrammeObject() method) containing the channelID, startTime and duration
populate that Programme object with metadata
pass that Programme object to the record(Programme) method.

Arguments startTime The start of the time period of the recording measured in seconds since midnight (GMT) on 1/1/1970. If the start time occurs in the past and the current time is within the specified duration of the recording, the OITF shall start recording immediately and may record any earlier content from the current programme that is available (e.g. stored in a time-shift buffer).

duration The duration of the recording in seconds.

repeatDays

Bitfield indicating which days of the week the recording should be repeated. Values are as follows:

Day	Bitfield Value
Sunday	0x01 (i.e. 00000001)
Monday	0x02 (i.e. 00000010)
Tuesday	0x04 (i.e. 00000100)
Wednesday	0x08 (i.e. 00001000)
Thursday	0x10 (i.e. 00010000)
Friday	0x20 (i.e. 00100000)
Saturday	0x40 (i.e. 01000000)

These bitfield values can be ‘OR’-ed together to repeat a recording on more than one day of a week (e.g. weekdays)

A value of 0x00 indicates that the recording will not be repeated.

channelID The identifier of the channel from which the broadcasted content is to be recorded. Specifies either a ccid or ipBroadcastID (as defined by the Channel object in section 7.13.11)

ScheduledRecordingCollection getScheduledRecordings( )
Description	Returns a subset of all the recordings that are scheduled but which have not yet started. The subset shall include only scheduled recordings that were scheduled using a service from the same FQDN as the domain of the service that calls the method.

ChannelConfig getChannelConfig( )
Description	Returns the channel line-up of the OITF in the form of a ChannelConfig object as defined in section 7.13.9. The ChannelConfig object returned from this function shall be identical to the ChannelConfig object returned from the getChannelConfig() method on the video/broadcast object as defined in section 7.13.1.3

void remove( ScheduledRecording recording )

Description

Remove a recording (either scheduled, in-progress or completed).

For non-privileged applications, recordings shall only be removed when they are scheduled but not yet started and the recording was scheduled by the current service.

As with the record() method, only the programmeID property of the scheduled recording shall be used to identify the scheduled recording to remove where this property is available. The other data contained in the scheduled recording shall not be used when removing a recording scheduled using methods other than recordAt(). For recordings scheduled using recordAt(), the data used to identify the recording to remove is implementation dependent.

If the programmeIDType property has the value ID_TVA_GROUP_CRID then the OITF shall cancel the recording of the specified group.

If an A/V Control object is presenting the indicated recording then the state of the A/V Control object shall be automatically changed to 6 (the error state).

Arguments

recording

The scheduled recording to be removed.

Programme createProgrammeObject( )
Description	Factory method to create an instance of Programme.

7.10.2 The ScheduledRecording class

The ScheduledRecording object represents a scheduled programme in the system, i.e. a recording that is scheduled but which has not yet started. For group recordings (e.g. recording an entire series), a ScheduledRecording object is also used to represent a “parent” recording that enables management of the group recording without representing any of the actual recordings in the group. The values of the properties of a ScheduledRecording (except for startPadding and endPadding) are provided when the object is created using one of the record() methods in section 7.10.1, for example by using a corresponding Programme object as argument for the record() method, and can not be changed for this scheduled recording object (except for startPadding and endPadding).

7.10.2.1 Constants

The following table lists the constants for recording states.

Name	Use
RECORDING_SCHEDULED	Recording has been newly scheduled.
RECORDING_REC_STARTED	Recording has started.
RECORDING_REC_COMPLETED	Recording has successfully completed.
RECORDING_REC_PARTIALLY_COMPLETED	The recording has only partially completed due to insufficient storage space, a clash or hardware failure. There are three possible conditions for this: The end of the recording is missed. The start of the recording is missed. A piece from the centre of the recording is missed (e.g. due to the receiver rebooting or a transient failure of the network connection).
RECORDING_ERROR	An error has been encountered. Refer to detailed error codes for details on the error.

This specification does not define values for these constants. Implementations may use any values as long as the value of each constant is unique.

The following table lists the constants for detailed error codes when a recording failed to complete.

Name	Use
ERROR_REC_RESOURCE_LIMITATION	The recording sub-system is unable to record due to resource limitations.
ERROR_INSUFFICIENT_STORAGE	There is insufficient storage space available. (Some of the recording may be available).
ERROR_REC_UNKNOWN	Recording has stopped before completion due to unknown (probably hardware) failure.

This specification does not define values for these constants. Implementations may use any values as long as the value of each constant is unique.

The following table lists the constants for programme ID types.

Name	Value	Use
ID_TVA_CRID	0	Used in the programmeIDType property to indicate that the programme is identified by its TV-Anytime CRID (Content Reference Identifier).
ID_DVB_EVENT	1	Used in the programmeIDType property to indicate that the programme is identified by a DVB URL referencing a DVB-SI event as enabled by section 4.1.3 of [OIPF_META2]. Support for this constant is optional.
ID_TVA_GROUP_CRID	2	Used in the programmeIDType property to indicate that the Programme object represents a group of programmes identified by a TV-Anytime group CRID.

7.10.2.2 Properties

readonly Integer state

The state of the recording. Valid values are:

RECORDING_REC_STARTED
RECORDING_REC_COMPLETED
RECORDING_REC_PARTIALLY_COMPLETED
RECORDING_SCHEDULED
RECORDING_ERROR

readonly Integer error

If the state of the recording has changed due to an error, this field contains an error code detailing the type of error. This is only valid if the value of the state argument is RECORDING_ERROR or RECORDING_REC_PARTIALLY_COMPLETED otherwise this property shall be null. Valid values are:

ERROR_REC_RESOURCE_LIMITATION
ERROR_INSUFFICIENT_STORAGE
ERROR_REC_UNKNOWN

readonly String scheduleID

An identifier for this scheduled recording. This value shall be unique to this scheduled recording. For a recording object this identifier can be used to associate which scheduled recording object this recording was created from.

readonly String customID

An identifier for this scheduled recording. This value is an identifier that the DAE application can set in order to keep track of scheduled recordings. It is not changed by the OITF.

Integer startPadding

The amount of padding to add at the start of a scheduled recording, in seconds. If the value of this property is undefined, an OITF defined start padding will be used. The default OITF defined start padding may be changed through property pvrStartPadding of the Configuration class as defined in section 7.3.2. When a recording is due to start, the OITF may use a smaller amount of padding in order to avoid conflicts with other recordings.

Positive values of this property shall cause the recording to start earlier than the specified start time (i.e. the actual duration of the recording shall be increased); negative values shall cause the recording to start later than the specified start time (i.e. the actual duration of the recording shall be decreased).

Integer endPadding

The amount of padding to add at the end of a scheduled recording, in seconds. If the value of this property is undefined, an OITF defined end padding will be used. The default OITF defined end padding may be changed through property pvrEndPadding of the Configuration class as defined in section 7.3.2. When a recording is in progress, the OITF may use a smaller amount of padding in order to avoid conflicts with other recordings.

Positive values of this property shall cause the recording to end later than the specified end time (i.e. the actual duration of the recording shall be increased); negative values shall cause the recording to end earlier than the specified end time (i.e. the actual duration of the recording shall be decreased).

readonly Integer repeatDays

Bitfield indicating which days of the week the recording should be repeated. Values are as follows:

Day	Bitfield Value
Sunday	0x01 (i.e. 00000001)
Monday	0x02 (i.e. 00000010)
Tuesday	0x04 (i.e. 00000100)
Wednesday	0x08 (i.e. 00001000)
Thursday	0x10 (i.e. 00010000)
Friday	0x20 (i.e. 00100000)
Saturday	0x40 (i.e. 01000000)

These bitfield values can be arithmetically summed to repeat a recording on more than one day of a week (e.g. weekdays)

A value of 0x00 indicates that the recording will not be repeated.

String name

The short name of the scheduled recording, e.g. 'Star Trek: DS9'.

String longName

The long name of the scheduled recording, e.g. 'Star Trek: Deep Space Nine'. If the long name is not available, this property will be undefined.

String description

The description of the scheduled recording, e.g. an episode synopsis. If no description is available, this property will be undefined.

String longDescription

The long description of the programme. If no description is available, this property will be undefined.

readonly Integer startTime

The start time of the scheduled recording, measured in seconds since midnight (GMT) on 1/1/1970. The value for the startPadding property can be used to indicate if the recording has to be started before the startTime (as defined by the Programme class).

readonly Integer duration

The duration of the scheduled recording (in seconds). The value for the endPadding property can be used to indicate how long the recording has to be continued after the specified duration of the recording.

readonly Channel channel

Reference to the broadcast channel where the scheduled programme is available.

readonly Boolean isManual

true if the recording was scheduled using oipfRecordingScheduler.recordAt() or using a terminal-specific approach that does not use guide data to determine what to record, false otherwise.

If false, then any fields whose name matches a field in the Programme object contains details from the programme guide on the programme that has been recorded. If true, only the channel, startTime and duration properties are required to be valid.

readonly String programmeID

The unique identifier of the scheduled programme or series, e.g. a TV-Anytime CRID (Content Reference Identifier). For recordings scheduled using the oipfRecordingScheduler.recordAt() method, the value of this property may be undefined.

readonly Integer programmeIDType

The type of identification used to reference the programme, as indicated by one of the ID_* constants defined in section 7.10.2.1. For recordings scheduled using the oipfRecordingScheduler.recordAt() method, the value of this property may be undefined.

readonly Integer episode

The episode number for the programme if it is part of a series. This property is undefined when the programme is not part of a series or the information is not available.

readonly Integer totalEpisodes

If the programme is part of a series, the total number of episodes in the series. This property is undefined when the programme is not part of a series or the information is not available.

readonly ParentalRatingCollection parentalRatings

A collection of parental rating values for the programme for zero or more parental rating schemes supported by the OITF. The value of this property is typically provided by a corresponding “Programme” object that is used to schedule the recording and can not be changed for this scheduled recording object. If no parental rating information is available for this scheduled recording, this property is a ParentalRatingCollection object (as defined in section 7.9.5) with length 0.

Note that if the parentalRatings property contains a certain parental rating (e.g. PG-13) and the broadcast channel associated with this scheduled recording has metadata that says that the content is rated PG-16, then the conflict resolution is implementation dependent.

Note that this property was formerly called “parentalRating” (singular not plural).

String customMetadata

Application-specific information for this recording. This value is information that the DAE application can set in order to retain additional information on this scheduled recording. It is not changed by the OITF.

The OITF shall support values up to and including 16 K Bytes in size. Strings longer than this may get truncated.

7.10.3 The ScheduledRecordingCollection class

typedef Collection<ScheduledRecording> ScheduledRecordingCollection

The ScheduledRecordingCollection class represents a collection of ScheduledRecording> objects. See Annex K for the definition of the collection template.

7.10.4 Extension to application/oipfRecordingScheduler for control of recordings

The OITF shall support the following extensions to the application/oipfRecordingScheduler object defined in section 7.10.1.

This subsection shall apply for OITFs that have indicated support for the extended PVR management functionality by adding the attribute 'manageRecordings = true' to the <recording> element in the client capability description as defined in section 9.3.3.

The functionality as described in this section is subject to the security model of section 10.

7.10.4.1 Properties

readonly ScheduledRecordingCollection recordings

Provides a list of scheduled and recorded programmes in the system. This property may only provide access to a subset of the full list of recordings, as determined by the value of the manageRecordings attribute of the <recording> element in the client capability description (see section 9.3.3).

readonly DiscInfo discInfo

Get information about the status of the local storage device. The DiscInfo class is defined in section 7.16.4.

function onPVREvent( Integer state, ScheduledRecording recording )

This function is the DOM 0 event handler for notification of changes in the state of recordings. The specified function is called with the following arguments:

Integer state – The current state of the recording. One of:

Value	Description
1	The recording has started.
2	The recording has stopped, having completed.
3	The recording sub-system is unable to record due to resource limitations.
4	There is insufficient storage space available. (Some of the recording may be available).
6	The recording has stopped before completion due to unknown (probably hardware) failure.
7	The recording has been newly scheduled.
8	The recording has been deleted (for complete or in-progress recordings) or removed from the schedule (for scheduled recordings).
9	The recording is due to start in a short time.
10	The recording has been updated. For performance reasons, OITFs should not dispatch events with the state when only the duration of an in-progress recording has changed.

ScheduledRecording recording – The recording to which this event refers.

7.10.4.2 Methods

Recording getRecording( String id )
Description	Returns the Recording object for which the value of the Recording.id property corresponds to the given `id` parameter. If such a Recording does not exist, the method returns `null`.
Arguments	id	Identifier corresponding to the id property of a Recording object.

void stop( Recording )
Description	Stop an in-progress recording. The recording shall not be deleted.
Arguments	recording	The recording to be stopped.

void refresh( )
Description	Update the recordings property to show the current status of all recordings.

Boolean update( String id, Integer startTime, Integer duration, Integer repeatDays )
Description	Requests the scheduler to update a scheduled or ongoing recording. For scheduled recordings the properties startTime, duration and repeatDays can be modified. For ongoing recordings only the duration property may be modified. This method shall return true if the operation succeeded, or false if for any reason it rescheduling is not possible (e.g. the updated recording overlaps with another scheduled recording and there are insufficient system resources to do both). If the method returns false then no changes shall be made to the recording.
Arguments	id	The id of the recording to update.
	startTime	The new start time of the recording, or `undefined` if the start time is not to be updated.
	duration	The new duration of the recording, or `undefined` if the duration is not to be updated.
	repeatDays	The new set of days on which the recording is to be repeated, or `undefined` if this is not to be updated.

7.10.4.3 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onPVREvent	PVREvent	Bubbles: No Cancellable: No Context Info: `state`, `recording`

Note: the DOM events are directly dispatched to the event target, and will not bubble nor capture. Remote UIs should not rely on receiving these events during the bubbling or the capturing phase. Remote UIs that use DOM event handlers shall call the addEventListener() method on the application/oipfRecordingScheduler object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.10.5 The Recording class

The Recording class represents an in-progress or completed recording being made available through the extended PVR management functionality as defined in section 7.10.4. Recordings for which no data has yet been recorded are represented by the ScheduledRecording class.

This class implements the ScheduledRecording interface (see section 7.10.2) to provide access to the information relating to the scheduling of the recording. The difference between scheduled recordings, in-progress recordings and completed recordings is primarily what properties are populated with values. In addition, for recorded and in-progress recordings the following is true:

The startPadding property is read only.
For in-progress recordings, changes to the value of the endPadding property shall modify the actual duration of the recording. If the value of the endPadding property is changed so that the current actual duration of the recording exceeds the new actual duration specified by the sum of the startPadding, duration and endPadding properties, the recording shall be stopped immediately. Changing the value of this property for a completed recording shall have no effect.

Recordings may be “manual” in that they simply record a channel at a certain time, for a period - analogous to a traditional VCR - or alternatively recordings can be programme based.

If an in-progress recording is interrupted and automatically resumed, e.g. due to a temporary power failure, all sections of the recording shall be represented by a single Recording object.

Values of properties in the Recording object shall be obtained from metadata about the recorded programme and are typically copied from the Programme used for scheduling a recording by the record(Programme programme) method of the application/oipfRecordingScheduler object. See section 7.10.4 for more information about the mapping between the properties of a Programme and the BCG metadata. In the event of a conflict between the metadata in the Programme and that in the broadcast channel, the conflict resolution is implementation dependent.

NOTE: The property parentalRatings formerly defined as part of this class is now redundant following the renaming of the parentalRating property in the ScheduledRecording class to parentalRatings.

7.10.5.1 Properties

NOTE: The properties state and isManual formerly defined in this class are now defined in the ScheduledRecording class, and since the Recording class inherits from the ScheduledRecording class they are still part of the Recording class.

readonly String uri

A uri identifying the content item in local storage according to [RFC3986]. The format of the URI is outside the scope of this specification except that;

the scheme shall not be one that is included in this specification
the URI shall not include a fragment

readonly String id

An identifier for this recording. This value shall be unique to this recording and so can be used to compare two recording objects to see if they refer to the same recording. The OITF shall guarantee that recording identifiers are unique in relation to download identifiers and CODAsset identifiers.

Boolean doNotDelete

If true, then this recording should not be automatically deleted by the system.

Integer saveDays

The number of days for which an individual or manual recording should be saved. Recordings older than this value may be deleted. If the value of this property is undefined, the default save duration shall be used.

Integer saveEpisodes

TThe number of episodes of a series-link that should be saved. Older episodes may be deleted. This is only valid when set on the latest scheduled recording in the series. If the value of this property is undefined, the default value shall be used.

readonly Boolean blocked

Flag indicating whether the programme is blocked due to parental control settings or conditional access restrictions.

The blocked and locked properties work together to provide a tri-state flag describing the status of a programme. This can best be described by the following table:

Description	blocked	locked
No parental control applies.	`false`	`false`
Item is above the parental rating threshold (or manually blocked); no PIN has been entered to view it and so the item cannot currently be viewed.	`true`	`true`
Item is above the parental rating threshold (or manually blocked); the PIN has been entered and so the item can be viewed.	`true`	`false`
Invalid combination – OITFs shall not support this combination	`false`	`true`

readonly Integer showType

Flag indicating the type of show. This field shall take one of the following values:

Value	Description
0	The show is live.
1	The show is a first-run show.
2	The show is a rerun.

readonly Boolean subtitles

Flag indicating whether subtitles or closed-caption information is available.

readonly StringCollection subtitleLanguages

Supported subtitle languages, indicated by their ISO 639-2 language codes as defined in [ISO639-2].

readonly Boolean isHD

Flag indicating whether the programme has high-definition video.

readonly Boolean is3D

Flag indicating whether the programme has 3D video.

readonly Integer audioType

Bitfield indicating the type of audio that is available for the programme. Since more than one type of audio may be available for a given programme, the value of this field shall consist of one or more of the following values ORed together:

Value	Desccription
1	Mono audio
2	Stereo audio
4	Multi-channel audio

readonly Boolean isMultilingual

Flag indicating whether more than one audio language is available for this recording.

readonly StringCollection audioLanguages

Supported audio languages, indicated by their ISO 639-2 language codes as defined in [ISO639-2].

readonly StringCollection genres

A collection of genres that describe this programme.

readonly Integer recordingStartTime

The actual start time of the recording, including any padding, measured in seconds since midnight (GMT) on 1/1/1970. This may not be the same as the scheduled start time of the recorded programme (e.g. due to a recording starting late, or due to start/end padding). For recordings that have not yet started, the value of this field shall be undefined.

readonly Integer recordingDuration

The actual duration of the recording, including any padding, measured in seconds. This may not be the same as the scheduled duration of the recording (e.g. due to a recording finishing early, or due to start/end padding). For recordings that have not yet started, the value of this field shall be undefined.

readonly Bookmarks bookmarks

A collection of the bookmarks set in a recording. If no bookmarks are set, the collection shall be empty.

readonly Boolean locked

Flag indicating whether the current state of the parental control system prevents the recording from being viewed (e.g. a correct parental control PIN has not been entered to allow the recording to be viewed).

7.10.6 The RecordingCollection class

This section is intentionally left empty.

7.10.7 The PVREvent class

This section is intentionally left empty.

7.10.8 The Bookmark class

The Bookmark class represents a bookmark or chapter mark in a recording or CoD asset. This is not a web bookmark – instead, it is a point from which the viewer may want to resume playback of a piece of content. These may be set implicitly without user intervention (e.g. at the point where a user stops watching a recording, in order to allow them to resume from that point later) or explicitly by the user (e.g. at the start of a favourite scene).

7.10.8.1 Properties

readonly Integer time

The time at which the bookmark is set, in seconds from the start of the content item.

readonly Name name

The name of the bookmark.

7.10.9 The BookmarkCollection class

typedef Collection<Bookmark> BookmarkCollection

A BookmarkCollection is a collection of bookmarks, ordered by time. See Annex K for the definition of the collection template. In addition to the methods and properties defined for generic collections, the BookmarkCollection class supports the additional properties and methods defined below.

NOTE: In principle bookmarks may be stored on in the network however the protocol for communicating bookmarks between the OITF and the network is not defined in the present document.

7.10.9.1 Methods

Bookmark addBookmark( Integer time, String name )
Description	Add a new bookmark to the collection. If the bookmark cannot be added (e.g. because the value given for time lies outside the length of the recording), this method shall return `null`.
Arguments	time	The time at which the bookmark is set, in seconds since the start of the recording.
	name	The name of the bookmark.

void removeBookmark( Bookmark bookmark )
Description	Remove a bookmark from the collection.
Arguments	bookmark	The bookmark to be removed.

7.11 Remote Management APIs

This section defines interfaces to perform remote diagnostics and management of the device.

Browser based remote management shall be supported by OITFs that have indicated <remote_diagnostics>true</remote_diagnostics> in their capability profile (as defined in section 9.3.12).

7.11.1 The application/oipfRemoteManagement embedded object

The application/oipfRemoteManagement embedded object has the following properties and methods.

Access to the functionality of the application/oipfRemoteManagement embedded object shall adhere to the security requirements as defined in section 10.

7.11.1.1 Properties

readonly String vendorName

The value of this property shall be the same as the value of the LocalSystem.vendorName property (see section 7.3.3.2)

readonly String modelName

The value of this property shall be the same as the value of the LocalSystem.modelName property (see section 7.3.3.2)

readonly String softwareVersion

The value of this property shall be the same as the value of the LocalSystem.softwareVersion property (see section 7.3.3.2)

readonly String hardwareVersion

The value of this property shall be the same as the value of the LocalSystem.hardwareVersion property (see section 7.3.3.2)

readonly String familyName

The value of this property shall be the same as the value of the LocalSystem.familyName property (see section 7.3.3.2)

function onSoftwareUpdate( String updateEvent, Integer seconds, String message, String version )

The function that is called when the OITF’s software update state is changed. The specified function is called with the following arguments:

String updateEvent – The event type that caused the invocation of this function. One of:

Value	Description
`SOFTWARE_AVAILABLE`	New software for the OITF has been found on a remote management server. The `message` argument may contain a user-centric message regarding this new software version and the `version` argument may contain the version number of the software update.
`SOFTWARE_DOWNLOADING`	New software for the OITF is in the process of being downloaded. The `version` argument may contain the version number of the software being downloaded. This event type may be signalled at multiple times during the download of the new software, indicating positive progress; in this case the `message` argument should contain an indication of the download progress.
`SOFTWARE_DOWNLOAD_FAILED`	The download of new software has failed. A descriptive reason for the failure may be found in the `message` argument and the `version` argument may contain the version number of the software that failed to be downloaded.
`SOFTWARE_DOWNLOADED`	A new software version of the OITF has been downloaded but has not yet been installed. Applications can now save relevant data that should survive a firmware upgrade. The actual mechanism of the download is out of scope of this specification. The `message` argument may contain a user-centric message regarding this new software version. The `seconds` argument has no significance.
`FORCED_UPDATE`	A new software version will shortly be installed. This event may occur if the users has not agreed to install the software but the system must have a new software version. The `seconds` argument gives the time until the OITF will install the new software.

Integer seconds – The time before action takes place. The meaning depends on the event type as described above.
String message – A message that may be used to inform the user about the purpose of this update to the software in order to receive the users consent to perform the actual update. undefined if not used.
String version – The new version number of the software identified for the update, or undefined if not available.

7.11.1.2 Methods

String getParameter( String parameterName )

Description Returns the requested parameter.

Arguments

parameterName

“SAMPLE_PACKET_LOSS”: This queries the RTP packet loss since the last call to this function, or the start of the current RTP content item, whichever is more recent. The returned string is of the format “<time in milliseconds since the last sample> <fraction lost> <number of packets lost>”. These fields (i.e. <xxx>) are defined as described in [RFC3550] section 6.4.2 and are decimal numbers (encoded as strings). If no content item is playing an empty string is returned.

“SAMPLE_DECODER_ERRORS”: This queries the decoder errors since the last call to this function, or the start of the current RTP content item, whichever is more recent. The returned string is of the format “<time in milliseconds since the sample> <total number of frames decoded> <total number of errors>”. These fields are decimal numbers (encoded as strings). If no content item is playing an empty string is returned.

“CUMULATIVE_PACKET_LOSS”: This queries the RTP packet loss since the start of the current RTP content item. The returned string is of the format “<time in milliseconds of this sample within the content> <fraction lost> <number of packets lost>”. These fields (i.e. <xxx>) are defined as described in [RFC3550] section 6.4.2 and are decimal numbers (encoded as strings). If no content item is playing an empty string is returned.

“CUMULATIVE_DECODER_ERRORS”: This queries the decoder errors since the start of the current RTP content item, whichever is more recent. The returned string is of the format “<time in milliseconds of this sample within the content> <total number of frames decoded> <total number of errors>”. These fields are decimal numbers (encoded as strings). If no content item is playing an empty string is returned.

Values are not case sensitive. Optionally, further vendor specific parameters may be supported.

In the case that a parameter is requested that a device does not support, it shall return an empty string.

Integer triggerSoftwareUpdate( String token )

Description

Triggers an OITF to start its software update process. The process itself and any user involvement (e.g. to confirm agreement for a software update) is not defined. The method is blocking. The process of updating the software may generate SoftwareUpdate events to indicate progress.

The returned integer is a result code that can take the following values:

Result message	Description	Semantics
0	Successful	The request is successful and the device software will be updated.
1	Unknown error	`triggerSoftwareUpdate()` failed because an unspecified error occurred.
2	Invalid token	`triggerSoftwareUpdate()` failed because the token is not valid.
3	No update available	`triggerSoftwareUpdate()` failed, because no update exists.

Arguments token An optional token string used to assist in the software update process. The token may be used to transfer credentials information to control the software update.

Integer softwareUpdateStatus( )

Description

Returns the current status of any ongoing software update activity. The value returned by this function shall be:

Result message	Description
-2	No software update is in progress.
-1	New software is available to download for the OITF.
0 .. 99	New software is being downloaded to the OITF and the value gives an approximation of the amount already downloaded.
100	Indicates that new software has been successfully downloaded to the OITF and is available for installation.
1001 .. 1999	Indicates that an error occurred during the download of new software to the OITF. This range of values can be used to provide an implementation specific error code.

7.11.1.3 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onSoftwareUpdate	SoftwareUpdate	Bubbles: No Cancellable: No Context Info: `updateEvent`, `seconds`

Note: the DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving these events during the bubbling or the capturing phase. Remote UIs that use DOM event handlers shall call the addEventListener() method on the application/oipfRemoteManagement object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.12 Metadata APIs

This section defines the JavaScript APIs used by DAE applications for reading and searching metadata about programmes. This API does not specify whether these query operations are carried out on the OITF or whether they require communication with a server.

The metadata API provides DAE applications with high-level access to metadata about programmes and channels. This document describes the mapping between this API and CoD and programme guide metadata. Mappings between this API and other metadata sources are not specified in this document.

This section shall apply for OITFs that have indicated <clientMetadata> with value “true” and a “type” attribute with value “bcg” or “dvb-si” as defined in section 9.3.7 in their capability.

Note that in order to access the metadata of programmes and channels several extensions to the Programme and Channel classes have been defined when the OITF has indicated support for <clientMetadata>. See sections 7.16.2.3 “Metadata extensions to Programme” and 7.13.11.3 “Metadata extensions to Channel” for more information).

The functionality as described in this section is subject to the security model of section 10 (in particular section 10.1.3.6).

7.12.1 The application/oipfSearchManager embedded object

OITFs shall implement the “application/oipfSearchManager” embedded object. This object provides a mechanism for applications to create and manage metadata searches.

7.12.1.1 Properties

readonly Integer guideDaysAvailable

The number of days for which guide data is available. A value of -1 means that the amount of guide data available is unknown.

function onMetadataUpdate( Integer action, Integer info, Object object )

This function is the DOM 0 event handler for events indicating changes in metadata. This shall be raised under the following circumstances:

When a new version of the metadata is discovered. Note that new versions of metadata can be made available without any of the individual items of metadata changing. It is an application's responsibility to determine what, if anything, has changed.
When the values of the blocked or locked properties on a content item change due to changes in the parental control subsystem (e.g. parental control being enabled or disabled, or a content item being unlocked with a PIN).

The specified function is called with the arguments action, info and object. These arguments are defined as follows:

Integer action – the type of update that has taken place. This field will take one of the following values:

Value	Description
1	A new version of metadata is available (see section 4.1.2.1.2 of [OIPF_META2]) and applications should discard all references to Programme objects immediately and re-acquire them.
2	A change to the parental control flags for a content item has occurred (e.g. the user has unlocked the parental control features of the receiver, allowing a blocked item to be played).
3	A flag affecting the filtering criteria of a channel has changed. Applications may listen for events with this action code to update lists of favourite channels, for instance.

Integer info – extended information about the type of update that has taken place. If the action argument is set to the value 3, the value of this field shall be one or more of the following:

Value Description

1 The list of blocked channels has changed.

2 A list of favourite channels has changed.

4 The list of hidden channels has changed.

If the action argument is set to the value 2, the value of this field shall be one or more of:

Value Description

1 The block status of a content item has changed.

2 The lock status of a content item has changed.

This field is treated as a bitfield, so values may be combined to allow multiple reasons to be passed.
Object object – the affected channel, programme, or CoD asset prior to the change. If more than one is affected, then this argument shall take the value null.

function onMetadataSearch( MetadataSearch search, Integer state )

This function is the DOM 0 event handler for events relating to metadata searches. The specified function is called with the arguments search and state. These arguments are defined as follows:

MetadataSearch search – the affected search

Integer state – the new state of the search

Value	Description
0	Search has finished. This event shall be generated when a search has completed.
1	This value is not used.
2	This value is not used.
3	The MetadataSearch object has returned to the idle state, either because of a call to SearchResults.abort() or because the parameters for the search have been modified (e.g. the query, constraints or search target).
4	The search cannot be completed due to a lack of resources or any other reason (e.g. insufficient memory is available to cache all of the requested results).

7.12.1.2 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onMetadataSearch	MetadataSearch	Bubbles: No Cancellable: No Context Info: `search`, `state`
onMetadataUpdate	MetadataUpdate	Bubbles: No Cancellable: No Context Info: `action`, `info`, `object`

Note: these DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving these events during the bubbling or the capturing phase. Applications that use DOM event handlers shall call the addEventListener() method on the application/oipfSearchManager object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.12.1.3 Methods

MetadataSearch createSearch( Integer searchTarget )

Description Create a MetadataSearch object that can be used to search the metadata.

Arguments

searchTarget

The metadata that should be searched.

Valid values of the searchTarget parameter are:

Value	Description
1	Metadata relating to scheduled content shall be searched.
2	Metadata relating to content on demand shall be searched.

These values are treated as a bitfield, allowing searches to be carried out across multiple search targets.

ChannelConfig getChannelConfig( )

Description

Returns the channel line-up of the tuner in the form of a ChannelConfig object as defined in section 7.13.9. This includes the favourite lists.

The ChannelConfig object returned from this function shall be identical to the ChannelConfig object returned from the getChannelConfig() method on the video/broadcast object as defined in section 7.13.1.3.

7.12.1.4 The MetadataSearch class

A MetadataSearch object represents a query of the metadata about available programmes. Applications can create MetadataSearch objects using the createSearch() method on the application/oipfSearchManager object. When metadata queries are performed on a remote server, the protocol used is defined in section 4.1.2.2 of [OIPF_META2].

Each search consists of three steps:

Definition of the query. The application creates a MetadataSearch object, and either creates its associated Query object, or sets a query using the findProgrammesFromStream() method, and sets any applicable constraints and result ordering.
Acquisition of results. The OITF acquires some or all of the items that match the specified query and constraints, and caches the requested subset of the results. This is typically triggered by a call to getResults().
Retrieval. The application accesses the results via the SearchResults class.

The MetadataSearch and SearchResults classes work together to manage an individual search. For every search, the MetadataSearch object and its corresponding SearchResults object shall be in one of three states as described in Table 7. Figure 13 below shows the transitions between these states:

Figure 13: State machine for a metadata search (informative)

Table 7: Metadata search states (normative)
State	Description
Idle	The search is idle; no results are available. This is the initial state of the search. In this state, the application can set or modify the query, constraints or ordering rules that are applied to the search. No search results are available in this state – any calls to SearchResults.item() shall return `undefined` and the values of the length and totalSize properties on the SearchResults object shall return zero. Any search results that have been cached by the terminal shall be discarded when the Idle state is entered. Calling the SearchResults.getResults() method shall cause a state transition to the Searching state.
Searching	Results are being retrieved and are not yet available to applications. If the terminal has not previously cached the full set of search results, the terminal performs the search to gather the requested results. If a new version of the metadata is detected (e.g. due to an EIT update) while the search is in this state, results shall be retrieved from either the new or original version of the metadata but shall not be retrieved from a combination of the two versions. Calls to SearchResults.item() shall return `undefined`. Any modification of the search parameters (e.g. changing the query or adding/removing constraints, or calling findProgrammesFromStream()) by the application shall stop the current search and cause a transition to the Idle state. The terminal shall dispatch a `MetadataSearch` event with `state`=3. When all requested results have been found, the terminal shall dispatch a `MetadataSearch` event with `state`=0 and a state transition to the Found state shall occur. If the search cannot be completed due to a lack of resources or any other reason, the terminal shall dispatch a `MetadataSearch` event with `state`=4 and a state transition to the Idle state shall occur. Calls to the SearchResults.getResults() method shall abort the retrieval of search results and attempt to retrieve the newly-requested set of results instead. NOTE: Calling getResults() when in the searching state may be used to fetch a group of items starting at a different offset or with a different count.
Found	Search results are available and can be retrieved by applications. The data exposed via the SearchResults.item() method is static and never changes as a result of any updates to the underlying metadata database until SearchResults.getResults() is next called. If a new version of the metadata is detected (e.g. due to an EIT update), a `MetadataUpdate` event is dispatched with `action`=1. Subsequent calls to SearchResult.getResults() shall return results based on the updated metadata. Calls to SearchResults.getResults() shall cause a state transition to the Searching state. Any modification of the search parameters (e.g. changing the query or adding/removing constraints, or calling findProgrammesFromStream()) by the application shall cause the current set of results to be discarded and shall cause a transition to the Idle state. The terminal shall dispatch a `MetadataSearch` event with `state`=3.

The findProgrammesFromStream() method acts as a shortcut for setting a query and a set of constraints on the MetadataSearch object. Regardless of whether the query and constraints are set explicitly by the application or via findProgrammesFromStream(), results are retrieved using the getResults() method.

Changes to the search parameters (e.g. changing the query or adding/removing constraints or modifying the search target, or calling findProgrammesFromStream()) shall be applied when the getResults() method on the corresponding SearchResults object is called. Due to the nature of metadata queries, searches are asynchronous and events are used to notify the application that results are available. MetadataSearch events shall be targeted at the application/oipfSearchManager object.

The present document is intentionally silent about the implementation of the search mechanism and the algorithm for retrieving and caching search results except where described in Table 7 above. When performing a search, the receiver may gather all search results and cache them (or cache a set of pointers into the full database), or gather only the subset of search results determined by the getResults() parameters, or take an alternative approach not described here.

7.12.1.4.1 Properties

readonly Integer searchTarget

The target(s) of the search. Valid values are:

Value	Description
1	Metadata relating to scheduled content shall be searched.
2	Metadata relating to on-demand content shall be searched.

These values shall be treated as a bitfield, allowing searches to be carried out across multiple search targets.

readonly SearchResults result

The subset of search results that has been requested by the application.

7.12.1.4.2 Methods

void setQuery( Query query )

Description

Set the query terms to be used for this search, discarding any previously-set query terms.

Setting the search parameters using this method will implicitly remove any existing constraints, ordering or queries created by prior calls to methods on this object.

Arguments

query

The query terms to be used

void addRatingConstraint( ParentalRatingScheme scheme, Integer threshold )
Description	Constrain the search to only include results whose parental rating value is below the specified threshold.
Arguments	scheme	The parental rating scheme upon which the constraint shall be based. If the value of this argument is `null`, any existing parental rating constraints shall be cleared.
	threshold	The threshold above which results shall not be returned. If the value of this argument is `null`, any existing constraint for the specified parental rating scheme shall be cleared.

void addCurrentRatingConstraint( )
Description	Constrain the search to only include results whose parental rating value is below the threshold currently set by the user.

void addChannelConstraint( ChannelList channels )

Description

Constrain the search to only include results from the specified channels. If a channel constraint has already been set, subsequent calls to addChannelConstraint() shall add the specified channels to the list of channels from which results should be returned.

For CoD searches, adding a channel constraint shall have no effect.

Arguments channels The channels from which results shall be returned. If the value of this argument is null, any existing channel constraint shall be removed.

void addChannelConstraint( Channel channel )

Description

Constrain the search to only include results from the specified channel. If a channel constraint has already been set, subsequent calls to addChannelConstraint() shall add the specified channel to the list of channels from which results should be returned.

For CoD searches, adding a channel constraint shall have no effect.

Arguments channel The channel from which results shall be returned. If the value of this argument is null, any existing channel constraint shall be removed.

void orderBy( String field, Boolean ascending )
Description	Set the order in which results should be returned in future. Any existing search results shall not be re-ordered. Subsequent calls to `orderBy()` will apply further levels of ordering within the order defined by previous calls. For example: orderBy("ServiceName", true); orderBy("PublishedStart", true); will cause results to be ordered by service name and then by start time for results with the same channel number.
Arguments	field	The name of the field by which results should be sorted. A value of `null` indicates that any currently-set order shall be cleared and the default sort order should be used.
	ascending	Flag indicating whether the results should be returned in ascending or descending order.

Query createQuery( String field, Integer comparison, String value )

Description

Create a metadata query for a specific value in a specific field within the metadata. Simple queries may be combined to create more complex queries. Applications shall follow the JavaScript type conversion rules to convert non-string values into their string representation, if necessary.

Arguments

field

The name of the field to compare. Fields are identified using the format <classname>.<propertyname> where classname shall be one of “Programme”, “CODAsset”, “CODService” or “CODFolder” and <propertyname> shall be a valid property name on the corresponding class.

comparison

The type of comparison. One of:

Value	Description
0	True if the specified value is equal to the value of the specified field.
1	True if the specified value is not equal to the value of the specified field.
2	True if the value of the specified field is greater than the specified value.
3	True if the value of the specified field is greater than or equal to the specified value.
4	True if the value of the specified field is less than the specified value.
5	True if the value of the specified field is less than or equal to the specified value.
6	True if the string value of the specified field contains the specified value. This operation shall be case insensitive, and shall match parts of a word as well as whole words (e.g. a value of “term” will match a field value of “Terminator”).

value

The value to check. Applications shall follow the JavaScript type conversion rules to convert non-string values into their string representation, if necessary.

void findProgrammesFromStream( Channel channel, Integer startTime, Integer count )
Description	Set a query and constraints for retrieving metadata for programmes from a given channel and given start time from metadata contained in the stream as defined in section 4.1.3 of [OIPF_META2]. Setting the search parameters using this method will implicitly remove any existing constraints, ordering or queries created by prior calls to methods on this object. This method does not cause the search to be performed; applications must call getResults() to retrieve the results. Applications shall be notified of the progress of the search via MetadataSearch events as described in section 7.12.1.2.
Arguments	channel	The channel for which programme information should be found.
	startTime	The start of the time period for which results should be returned measured in seconds since midnight (GMT) on 1/1/1970. The start time is inclusive; any programmes starting at the start time, or which are showing at the start time, will be included in the search results. If `null`, the search will start from the current time.
	count	Optional argument giving the maximum number of programmes for which information should be fetched. This places an upper bound on the number of results that will be present in the result set – for instance, specifying a value of 2 for this argument will result in at most two results being returned by calls to getResults() even if a call to getResults() requests more results. If this argument is not specified, no restrictions are imposed on the number of results which may be returned by calls to getResults().

7.12.1.5 The Query class

The Query class represents a metadata query that the user wants to carry out. This may be a simple search, or a complex search involving Boolean logic. Queries are immutable; an operation on a query shall return a new Query object, allowing applications to continue referring to the original query.

The examples below show how more complex queries can be constructed:

	Query qa = mySearch.createQuery("Title", 6, "Terminator");
	Query qb = mySearch.createQuery("SpokenLanguage", 0, "fr-CA");
	Query qc = qb.and(qa.not());

7.12.1.5.1 Properties

This section is intentionally left empty.

7.12.1.5.2 Methods

Query and( Query query )
Description	Create a query based on the logical AND of the predicates represented by the query currently being operated on and the argument `query`.
Arguments	query	The second predicate for the AND operation.

Query or( Query query )
Description	Create a query based on the logical OR of the predicates represented by the query currently being operated on and the argument `query`.
Arguments	query	The second predicate for the OR operation.

Query not( )
Description	Create a query that is the logical negation of the predicates represented by the query currently being operated on.

7.12.1.6 The SearchResults class

The SearchResults class represents the results of a metadata search. Since the result set may contain a large number of items, applications request a ‘window’ on to the result set, similar to the functionality provided by the OFFSET and LIMIT clauses in SQL.

Applications may request the contents of the result in groups of an arbitrary size, based on an offset from the beginning of the result set. The data shall be fetched from the appropriate source, and the application shall be notified when the data is available.

The set of results shall only be valid if a call to getResults() has been made and a MetadataSearch event notifying the application that results are available has been dispatched. If this event has not been dispatched, the set of results shall be empty (i.e. the value of the totalSize property shall be 0 and calls to item() shall return undefined).

In addition to the properties and methods defined below a SearchResults object shall support the array notation to access the results in this collection.

7.12.1.6.1 Properties

readonly Integer length

The number of items in the current window within the overall result set. The value of this property shall be zero until getResults() has been called and a MetadataSearch event notifying the application that results are available has been dispatched. If the current window onto the result set is in fact the whole result set then length will be the same as totalSize. Otherwise length will be less than totalSize.

readonly Integer offset

The current offset into the total result set.

readonly Integer totalSize

The total number of items in the result set.

The value of this property shall be zero until getResults() has been called and a MetadataSearch event notifying the application that results are available has been dispatched.

7.12.1.6.2 Methods

Object item( Integer index )
Description	Return the item at position index in the collection of currently available results, or `undefined` if no item is present at that position. This function shall only return objects that are instances of Programme, CODAsset, CODFolder, or CODService.
Arguments	index	The index into the result set.

Boolean getResults( Integer offset, Integer count )
Description	Perform the search and retrieve the specified subset of the items that match the query. Results shall be returned asynchronously. A `MetadataSearch` event with `state`=0 shall be dispatched when results are available. This method shall always return `false`.
Arguments	offset	The number of items at the start of the result set to be skipped before data is retrieved.
	count	The number of results to retrieve.

void abort( )

Description Abort any outstanding request for results and remove any query, constraints or ordering rules set on the MetadataSearch object that is associated with this SearchResults object. Regardless of whether or not there is an outstanding request for results, items currently in the collection shall be removed (i.e. the value of the length property shall be 0 and any calls to item() shall return undefined). All cached search results shall be discarded.

7.13 Scheduled Content and hybrid tuner APIs

This section shall apply to OITFs that have indicated support for tuner control (i.e. <video_broadcast>true</video_broadcast> as defined in section 9.3.1) in their capability. It describes the video/broadcast embedded object needed to support display and control by a DAE application of scheduled content received over local tuner functionality available to an OITF, including the conveyance of the channel list to the server. The term “tuner” is used here to identify a piece of functionality to enable switching between different types of scheduled content services that are identified through logical channels. This includes IP broadcast channels, as well as traditional broadcast channels received over a hybrid tuner.

7.13.1 The video/broadcast embedded object

The OITF shall support the video/broadcast embedded object with the following properties and methods, which shall adhere to the tuner related security requirements in section 10.1.3.1. The MIME type of this object shall be “video/broadcast”.

7.13.1.1 State diagram for video/broadcast objects

The state diagram below shows the states that a video/broadcast object may be in. Dashed lines indicate automatic transitions between states. The video/broadcast object shall be in the unrealized state when it is instantiated.

Figure 14: State diagram for embedded video/broadcast objects (informative).

Transient errors are defined as ones that that the OITF will automatically recover from without intervention by an application. Transient errors persist until either the condition which caused them is corrected or it is determined that it cannot be connected and the error becomes permanent. Permanent errors are defined as ones that the OITF will not automatically attempt to recover from.

Terminals shall perform the state changes in Table 8 under the conditions described and generate the listed event(s). Terminals shall not change state in circumstances other than defined in this section.

Table 8: State transitions for the video/broadcast embedded object
Old State	Trigger	New State	State Transition Events	Description
All states	setChannel(channel) where `channel != null` and the channel type is supported and the combination of channel properties is valid and a suitable tuner is available	Connecting	PlayStateChange	The terminal attempts to connect to the requested channel. The currentChannel object reflects the channel being changed to.
All states	setChannel(channel) where `channel != null` but either the channel type is not supported or the combination of channel properties is invalid or a suitable tuner is not available	No change	ChannelChangeError	The terminal remains in the same state.
Connecting or Presenting or Stopped	nextChannel(), prevChannel() where the `video/broadcast` object currentChannel is in the channel list and a suitable tuner is available	Connecting	PlayStateChange	The terminal attempts to connect to the requested channel. The currentChannel object reflects the channel being changed to.
Connecting	nextChannel(), prevChannel() where the `video/broadcast` object currentChannel is not in the channel list	Unrealized	ChannelChangeError PlayStateChange
Presenting or Stopped	nextChannel(), prevChannel() where the `video/broadcast` object currentChannel is not in the channel list	No change	ChannelChangeError	The terminal remains in the same state.
Connecting or Presenting or Stopped	nextChannel(), prevChannel() where the `video/broadcast` object currentChannel is in the channel list but no suitable tuner is available	No change	ChannelChangeError	The terminal remains in the same state.
Unrealized	bindToCurrentChannel() when at least one channel is currently being presented by the OITF and binding to the necessary resources does not fail	Presenting	PlayStateChange	The terminal binds the video/broadcast object to the current channel being natively presented. The currentChannel object reflects the channel being presented.
Unrealized	bindToCurrentChannel() when there is no channel currently being presented or binding to the necessary resources to play the channel through the video/broadcast object fails	Unrealized	PlayStateChange	The terminal continues to present the current channel, if any.
Connecting	The terminal successfully connected to the broadcast or IP multicast stream and presented its contents.	Presenting	ChannelChangeSucceeded PlayStateChange	This transition occurs automatically when media presentation starts.
Connecting	The terminal successfully connected to the broadcast or IP multicast stream but presentation of content is blocked, e.g. by a parental rating mechanism or content protection mechanism	Connecting	ChannelChangeSucceeded PlayStateChange	This is conceptually equivalent to a successful channel change where a transient error immediately pre-empts media presentation without the video/broadcast object entering the presenting state.
Connecting	Recovery from a transient error, including presentation of content no longer being blocked by a content protection mechanism (e.g. the start of a free preview period or a channel that changes from being encrypted to being in the clear during the day) the end-user entering a PIN code or other equivalent authorization to enable access to content protected by parental access control resumption of delivery of media data	Presenting	PlayStateChange	If a video/broadcast object was forced from the presenting state to the connecting state due to a transient error and that error condition clears while the video/broadcast object remains in the connecting state then the video/broadcast object shall automatically transition back to the presenting state.
Connecting or Presenting or Stopped	release() or setChannel(null)	Unrealized	PlayStateChange	The control is returned to the terminal. The currentChannel object is set to `null`. If an application has modified the set of components being presented (e.g. changing the audio or subtitle stream being presented) then the same set of components will continue to be presented.
Connecting	Permanent error including failure to change to a new channel (e.g. the channel cannot be found or none of the media components can be decoded or insufficient resources are available to present the channel) exhaustion of all possibilities for an end-user to authorize access to content protected by a parental access control mechanism (e.g. timeout on a PIN entry dialogue) delivery of media data was interrupted and has not resumed after an implementation-dependent timeout	Unrealized	ChannelChangeSucceeded PlayStateChange	The terminal encountered a permanent error
Connecting or Presenting	stop()	Stopped	PlayStateChange
Presenting	Transient error including presentation of content being blocked by a content protection mechanism, presentation of content being blocked by a parental rating mechanism, interruption of delivery of media data (either via IP or hybrid) if either; the media data is delivered over a connection and the connection remains intact or the media data is delivered via a connectionless mechanism	Connecting	PlayStateChange	The terminal encountered a transient error. During media presentation, transient errors (e.g. transient errors in the bitstream, temporary loss of signal or temporary halting of media decoding due to parental control issues) may cause the object to transition from the presenting state to the connecting state. Temporary loss of resources due to presentation being interrupted by playback of audio from memory may cause the object to transition from the presenting state to the connecting state.
Presenting or Stopped	Permanent error including; interruption of delivery of media data where the media data is delivered over a connection and the connection terminates	Unrealized	PlayStateChange	The terminal encountered a permanent error.
Stopped	bindToCurrentChannel()	Connecting	PlayStateChange	Video and audio presentation is enabled.
All states	Destroy video/broadcast	N/A		When a video/broadcast object is destroyed (e.g. by the video/broadcast object being garbage collected) control of broadcast video shall be returned to the terminal. If an application has modified the set of components being presented (e.g. changing the audio or subtitle stream being presented) then the same set of components will continue to be presented. When a video/broadcast object is destroyed due to a page transition within an application, terminals may delay this operation until the new page is fully loaded in order to avoid display glitches if a video/broadcast object is also present in the new page. Presentation of broadcast video or audio shall not be interrupted in either case.

If the channel currently being presented is requested to be changed due to an action outside the application (for example, the user pressing the CH+ key on the remote) then any video/broadcast object presenting that channel (e.g. as the result of a call to bindToCurrentChannel()) shall perform the same state transitions and dispatch the same events as if the channel change operation was initiated by the application using the setChannel() method.

If the value of the allocationMethod property is DYNAMIC_ALLOCATION, the following apply:

Scarce resources such as media decoders shall be claimed while in the connecting state.
Resources shall be released when the video/broadcast object transitions to the unrealized state.
Video and audio decoding resources shall be released when the video/broadcast object transitions to the stopped state.
Transitioning from the presenting to the connecting state should not cause scarce resources to be released.

Applications can use the playState property of the video/broadcast object to read its current state.

When a video/broadcast object stops being rendered as defined in section 10.1 of the HTML5 specification as referenced by [OIPF_WSTVP2] an OITF may release scarce resources allocated for that object. Vice versa, a video/broadcast object which is not visible but it’s still being rendered shall still be decoding video if it is in the presenting state and any audio associated with the currently presented channel will still be audible. State transitions caused by calls to methods on the video/broadcast object, or due to permanent or transient errors, will occur as shown above regardless of the visibility of the object.

NOTE: as implied by the text above, rendering state and visibility are not equivalent. This implies, just to give two examples, that display:none will affect the object state while visibility:hidden will not.

7.13.1.2 Properties

Integer width

The width of the area used for rendering the video object. This property is only writable if property fullScreen has value false. Changing the width property corresponds to changing the width property through the HTMLObjectElement interface, and must have the same effect as changing the width through the DOM Level 2 Style interfaces (i.e. CSS2Properties interface style.width), at least for values specified in pixels.

Integer height

The height of the area used for rendering the video object. This property is only writable if property fullScreen has value false. Changing the height property corresponds to changing the height property through the HTMLObjectElement interface, and must have the same effect as changing the height through the DOM Level 2 Style interfaces (i.e. CSS2Properties interface style.height), at least for values specified in pixels.

readonly Boolean fullScreen

Returns true if this video object is in full-screen mode, false otherwise. The default value is false.

readonly String data
Setting the value of the data property shall have no effect on the `video/broadcast` object. If this property is read, the value returned shall always be the empty string.

function onChannelChangeError( Channel channel, Number errorState )

The function that is called when a request to switch a tuner to another channel resulted in an error preventing the broadcasted content from being rendered. The specified function is called with the arguments channel and errorState. This function may be called either in response to a channel change initiated by the application, or a channel change initiated by the OITF (see section 7.13.1.1). These arguments are defined as follows:

Channel channel – the Channel object to which a channel switch was requested, but for which the error occurred. This object shall have the same properties as the channel that was requested, except that for channels of type ID_DVB_* the values for the onid and tsid properties shall be extracted from the transport stream when one was found (e.g. when errorState is 12).

Number errorState – error code detailing the type of error:

Value	Description
0	channel not supported by tuner.
1	cannot tune to given transport stream (e.g. no signal)
2	tuner locked by other object.
3	parental lock on channel.
4	encrypted channel, key/module missing.
5	unknown channel (e.g. can’t resolve DVB or ISDB triplet).
6	channel switch interrupted (e.g. because another channel switch was activated before the previous one completed).
7	channel cannot be changed, because it is currently being recorded.
8	cannot resolve URI of referenced IP channel.
9	insufficient bandwidth.
10	channel cannot be changed by nextChannel()/prevChannel() methods either because the OITF does not maintain a favourites or channel list or because the video/broadcast object is in the Unrealized state.
11	insufficient resources are available to present the given channel (e.g. a lack of available codec resources).
12	specified channel not found in transport stream.
100	unidentified error.

readonly Integer playState

The current play state of the video/broadcast object. Valid values are:

Value	Description
0	unrealized; the application has not made a request to start presenting a channel or has stopped presenting a channel and released any resources. The content of the video/broadcast object should be transparent but if not shall be an opaque black rectangle. Control of media presentation is under the control of the OITF, as defined in section H.2.
1	connecting; the terminal is connecting to the media source in order to begin playback. Objects in this state may be buffering data in order to start playback. Control of media presentation is under the control of the application, as defined in section H.2. The content of the video/broadcast object is implementation dependent.
2	presenting; the media is currently being presented to the user. The object is in this state regardless of whether the media is playing at normal speed, paused, or playing in a trick mode (e.g. at a speed other than normal speed). Control of media presentation is under the control of the application, as defined in section H.2. The video/broadcast object contains the video being presented.
3	stopped; the terminal is not presenting media, either inside the video/broadcast object or in the logical video plane. The logical video plane is disabled. The content of the video/broadcast object shall be an opaque black rectangle. Control of media presentation is under the control of the application, as defined in section H.2

See section 7.13.1.1 for a description of the state model for a video/broadcast object.

NOTE: Implementations where the content of the video/broadcast object is transparent in the unrealized state will give a better user experience than ones where it is black. This happens for an application with video in the background between when it includes a video/broadcast object in the page and when a call to bindToCurrentChannel() completes. Applications which do not need to call bindToCurrentChannel() should not do so. The current channel can be obtained from the currentChannel property on the ApplicationPrivateData object which is the same as that on the video/broadcast object under most normal conditions.

function onPlayStateChange( Number state, Number error )

The function that is called when the play state of the video/broadcast object changes. This function may be called either in response to an action initiated by the application, an action initiated by the OITF or an error (see section 7.13.1.1).

The specified function is called with the arguments state and error. These arguments are defined as follows:

Number state – the new state of the video/broadcast object. Valid values are given in the definition of the playState property above.
Number error – if the state has changed due to an error, this field contains an error code detailing the type of error. See the definition of onChannelChangeError above for valid values. If no error has occurred, this argument shall take the value undefined.

function onChannelChangeSucceeded( Channel channel )

The function that is called when a request to switch a tuner to another channel has successfully completed. This function may be called either in response to a channel change initiated by the application, or a channel change initiated by the OITF (see section 7.13.1.1). The specified function is called with argument channel, which is defined as follows:

Channel channel – the channel to which the tuner switched. This object shall have the same properties with the same values as the currentChannel object (see section 7.13.7).

function onFullScreenChange( )

The function that is called when the value of fullScreen changes.

function onfocus( )

The function that is called when the video object gains focus.

function onblur( )

The function that is called when the video object loses focus.

readonly StringCollection playerCapabilities

The list of media formats that are supported by the object. Each item shall contain a format label according to [OIPF_MEDIA2].

If scarce resources are not claimed by the object, the value of this property shall be null.

readonly Integer allocationMethod

Returns the resource allocation method currently in use by the object. Valid values as defined in section 7.14.13.1 are:

STATIC_ALLOCATION
DYNAMIC_ALLOCATION

7.13.1.3 Methods

ChannelConfig getChannelConfig( )
Description	Returns the channel line-up of the tuner in the form of a ChannelConfig object as defined in section 7.13.9. The method shall return the value `null` if the channel list is not (partially) managed by the OITF (i.e., if the channel list information is managed entirely in the network).

Channel bindToCurrentChannel( )

Description

If the video/broadcast object is in the unrealized state and video from exactly one channel is currently being presented by the OITF then this binds the video/broadcast object to that video.

If the video/broadcast object is in the stopped state then this restarts presentation of video and audio from the current channel under the control of the video/broadcast object. If video from more than one channel is currently being presented by the OITF then this binds the video/broadcast object to the channel whose audio is being presented.

If there is no channel currently being presented, or binding to the necessary resources to play the channel through the video/broadcast object fails for whichever reason, the OITF shall dispatch an event to the onPlayStateChange listener(s) whereby the state parameter is given value 0 (“unrealized”) and the error parameter is given the appropriate error code.

Calling this method from any other states than the unrealized or stopped states shall have no effect.

See section 7.13.1.1 for more information of its usage.

NOTE: Returning a Channel object from this method does not guarantee that video or audio from that channel is being presented. Applications should listen for the video/broadcast object entering state 2 (“presenting”) in order to determine when audio or video is being presented.

Channel createChannelObject( Integer idType, String dsd, Integer sid )
Description	Creates a Channel object of the specified `idType`. This method is typically used to create a Channel object of type `ID_DVB_SI_DIRECT`. The Channel object can subsequently be used by the setChannel() method to switch a tuner to this channel, which may or may not be part of the channel list in the OITF. The resulting Channel object represents a locally defined channel which, if not already present there, does not get added to the channel list accessed through the ChannelConfig class (see section 7.13.9). Valid value for idType include: `ID_DVB_SI_DIRECT`. For other values this behaviour is not specified. If the channel of the given type cannot be created or the delivery system descriptor is not valid, the method shall return `null`. If the channel of the given type can be created and the delivery system descriptor is valid, the method shall return a Channel object whereby at a minimum the properties with the same names (i.e. idType, dsd and sid) are given the same value as argument `idType`, `dsd` and `sid` of the `createChannelObject` method.
Arguments	idType	The type of channel, as indicated by one of the `ID_*` constants defined in section 7.13.11.1. Valid values for idType include: `ID_DVB_SI_DIRECT`. For other values this behaviour is not specified.
	dsd	The delivery system descriptor (tuning parameters) represented as a string whose characters shall be restricted to the ISO Latin-1 character set. Each character in the dsd represents a byte of a delivery system descriptor as defined by DVB-SI [EN300468] section 6.2.13, such that a byte at position "i" in the delivery system descriptor is equal the Latin-1 character code of the character at position "i" in the dsd.
	sid	The service ID, which must be within the range of 1 to 65535.

Channel createChannelObject( Integer idType, Integer onid, Integer tsid, Integer sid, Integer sourceID, String ipBroadcastID )
Description	Creates a Channel object of the specified `idType`. The Channel object can subsequently be used by the setChannel() method to switch a tuner to this channel, which may or may not be part of the channel list in the OITF. The resulting Channel object represents a locally defined channel which, if not already present there, does not get added to the channel list accessed through the ChannelConfig class (see section 7.13.9). If the channel of the given `idType` cannot be created or the given (combination of) arguments are not considered valid or complete, the method shall return `null`. If the channel of the given type can be created and arguments are considered valid and complete, then either: If the channel is in the channel list then a new object of the same type and with properties with the same values shall be returned as would be returned by calling getChannelByTriplet() with the same parameters as this method. Otherwise, the method shall return a Channel object whereby at a minimum the properties with the same names are given the same value as the given arguments of the `createChannelObject()` method. The values specified for the remaining properties of the Channel object are set to `undefined`.
Arguments	idType	The type of channel, as indicated by one of the `ID_*` constants defined in section 7.13.11.1.
	onid	The original network ID. Optional argument that shall be specified when the `idType` specifies a channel of type `ID_DVB_`, `ID_IPTV_URI`, or `ID_ISDB_` and shall otherwise be ignored by the OITF.
	tsid	The transport stream ID. Optional argument that may be specified when the `idType` specifies a channel of type `ID_DVB_`, `ID_IPTV_URI`, or `ID_ISDB_` and shall otherwise be ignored by the OITF.
	sid	The service ID. Optional argument that shall be specified when the `idType` specifies a channel of type `ID_DVB_`, `ID_IPTV_URI`, or `ID_ISDB_` and shall otherwise be ignored by the OITF.
	sourceID	The source_ID. Optional argument that shall be specified when the `idType` specifies a channel of type `ID_ATSC_T` and shall otherwise be ignored by the OITF.
	ipBroadcastID	The DVB textual service identifier of the IP broadcast service, specified in the format “`ServiceName.DomainName`” when `idType` specifies a channel of type `ID_IPTV_SDS`, or the URI of the IP broadcast service when `idType` specifies a channel of type `ID_IPTV_URI`. Optional argument that shall be specified when the `idType` specifies a channel of type `ID_IPTV_SDS` or `ID_IPTV_URI` and shall otherwise be ignored by the OITF.

void setChannel( Channel channel, Boolean trickplay, String contentAccessDescriptorURL )
Description	Requests the OITF to switch a (logical or physical) tuner to the channel specified by channel and render the received broadcast content in the area of the browser allocated for the `video/broadcast` object. If the channel specifies an idType attribute value which is not supported by the OITF or a combination of properties that does not identify a valid channel, the request to switch channel shall fail and the OITF shall trigger the function specified by the onChannelChangeError property, specifying the value 0 (“Channel not supported by tuner”) for the `errorState`, and dispatch the corresponding DOM event (see below). If the channel specifies an idType attribute value supported by the OITF, and the combination of properties defines a valid channel, the OITF shall relay the channel switch request to a local physical tuner that is currently not in use by another `video/broadcast` object and that can tune to the specified channel. If no tuner satisfying these requirements is available (i.e. all physical tuners that could receive the specified channel are in use), the request shall fail and OITF shall trigger the function specified by the onChannelChangeError property, specifying the value ‘2’ (“tuner locked by other object”) for the `errorState` and dispatch the corresponding DOM event (see below). If multiple tuners satisfying these requirements are available, the OITF selects one. If the channel specifies an IP broadcast channel, and the OITF supports idType `ID_IPTV_SDS` or `ID_IPTV_URI`, the OITF shall relay the channel switch request to a logical ‘tuner’ that can resolve the URI of the referenced IP broadcast channel. If no logical tuner can resolve the URI of the referenced IP broadcast channel, the request shall fail and the OITF should trigger the function specified by the onChannelChangeError property, specifying the value 8 (“cannot resolve URI of referenced IP channel”) for the `errorState`, and dispatch the corresponding DOM event. The optional attribute `contentAccessDescriptorURL` allows for the inclusion of a Content Access Streaming Descriptor (the format of which is defined in Annex E.2) to provide additional information for dealing with IPTV broadcasts that are (partially) DRM-protected. The descriptor may for example include Marlin action tokens or a previewLicense. The attribute shall be `undefined` or `null` if it is not applicable. If the attribute `contentAccessDescriptorURL` is present, the `trickplay` attribute shall take a value of either `true` or `false`. If the Transport Stream cannot be found, either via the DSD or the (ONID,TSID) pair, then a call to onChannelChangeError with `errorState`=5 (“unknown channel”) shall be triggered, and the corresponding DOM event dispatched. If the OITF succeeds in tuning to a valid transport stream but this transport stream does not contain the requested service in the PAT, the OITF shall remain tuned to that location and shall trigger a call to onChannelChangeError with `errorState`=12 (“specified channel not found in transport stream”), and dispatch the corresponding DOM event. If, following this procedure, the OITF selects a tuner that was not already being used to display video inside the `video/broadcast` object, the OITF shall claim the selected tuner and the associated resources (e.g., decoding and rendering resources) on behalf of the `video/broadcast` object. If all of the following are true: the `video/broadcast` object is successfully switched to the new channel the `channel` is a locally defined channel (created using the createChannelObject method) the new channel has the same tuning parameters as a channel already in the channel list in the OITF the `idType` is a value other than `ID_IPTV_URI` then the result of this operation shall be the same as calling `setChannel` with the `channel` argument being the corresponding channel object in the channel list, such that: the values of the properties of the `video/broadcast` object currentChannel shall be the same as those of the channel in the channel list any subsequent call to nextChannel or prevChannel shall switch the tuner to the next or previous channel in the favourite list or channel list as appropriate, as described in the definitions of these methods Otherwise, if any of the above conditions is not true, then: the values of the properties of the `video/broadcast` object currentChannel shall be the same as those provided in the channel argument to this method, updated as defined in section 8.4.3 the channel is not considered to be part of the channel list the resulting current channel after any subsequent call to nextChannel() or prevChannel() is implementation dependent, however all appropriate functions shall be called and DOM events dispatched. The OITF shall visualize the video content received over the tuner in the area of the browser allocated for the `video/broadcast` object. If the OITF cannot visualize the video content following a successful tuner switch (e.g., because the channel is under parental lock), the OITF shall trigger the function specified by the onChannelChangeError property with the appropriate channel and `errorState` value, and dispatch a corresponding DOM event (see below). If successful, the OITF shall trigger the function specified by the onChannelChangeSucceeded property with the given channel value, and also dispatch a corresponding DOM event.
Arguments	channel	The channel to which a switched is requested. If the `channel` object specifies a ccid, the ccid identifies the channel to be set. If the channel does not specify a ccid, the `idType` determines which properties of the channel are used to define the channel to be set, for example, if the channel is of type `ID_IPTV_SDS` or `ID_IPTV_URI`, the `ipBroadcastID` identifies the channel to be set. If `null`, the `video/broadcast` object shall transition to the unrealized state and release any resources used for decoding video and/or audio. A `ChannelChangeSucceeded` event shall be generated when the operation has completed.
	trickplay	Optional flag indicating whether resources should be allocated to support trick play. This argument provides a hint to the receiver in order that it may allocate appropriate resources. Failure to allocate appropriate resources, due to a resource conflict, a lack of trickplay support, or due to the OITF ignoring this hint, shall have no effect on the success or failure of this method. If trickplay is not supported, this shall be indicated through the failure of later calls to methods invoking trickplay functionality. The timeShiftMode property defined in section 7.13.2.2 shall provide information as to type of trickplay resources that should be allocated. If argument `contentAccessDescriptorURL` is included then the `trickplay` argument shall be included.
	contentAccessDescriptorURL	Optional argument containing a Content Access Streaming descriptor (the format of which is defined in Annex E.2) that can be included to provide additional information for dealing with IPTV broadcasts that are (partially) DRM-protected. The argument shall be `undefined` or `null` if it is not applicable.

void prevChannel( )

Description

Requests the OITF to switch the tuner that is currently in use by the video/broadcast object to the channel that precedes the current channel in the active favourite list, or, if no favourite list is currently selected, to the previous channel in the channel list. If it has reached the start of the favourite/channel list, it shall cycle to the last channel in the list.

If the previous channel is a channel that cannot be received over the tuner currently used by the video/broadcast object, the OITF shall relay the channel switch request to a local physical or logical tuner that is not in use and that can tune to the specified channel. The behaviour is defined in more detail in the description of the setChannel method.

If an error occurs during switching to the previous channel, the OITF shall trigger the function specified by the onChannelChangeError property with the appropriate channel and errorState value, and dispatch the corresponding DOM event (see below).

If the OITF does not maintain the channel list and favourite list by itself, the request shall fail and the OITF shall trigger the onChannelChangeError function with the channel property having the value null, and errorState=10 (“channel cannot be changed by nextChannel()/prevChannel() methods”).

If successful, the OITF shall trigger the function specified by the onChannelChangeSucceeded property with the appropriate channel value, and also dispatch the corresponding DOM event.

Calls to this method are valid in the Connecting, Presenting and Stopped states. They are not valid in the Unrealized state and shall fail.

void nextChannel( )

Description

Requests the OITF to switch the tuner that is currently in use by the video/broadcast object to the channel that succeeds the current channel in the active favourites list, or, if no favourite list is currently selected, to the next channel in the channel list. If it has reached the end of the favourite/channel list, it shall cycle to the first channel in the list.

If the current channel is not part of the channel list, it is implementation dependent whether the method call succeeds or fails and, if it succeeds, which channel is selected. In both cases, all appropriate functions shall be called and DOM events dispatched. If the next channel is channel that cannot be received over the tuner currently used by the video/broadcast object, the OITF shall relay the channel switch request to a local physical or logical tuner that is not in use and that can tune to the specified channel. The behaviour is defined in more detail in the description of the setChannel method.

If an error occurs during switching to the next channel, the OITF shall trigger the function specified by the onChannelChangeError property with the appropriate channel and errorState value, and dispatch the corresponding DOM event (see below).

If successful, the OITF shall trigger the function specified by the onChannelChangeSucceeded property with the appropriate channel value, and also dispatch the corresponding DOM event.

Calls to this method are valid in the Connecting, Presenting and Stopped states. They are not valid in the Unrealized state and shall fail.

void setFullScreen( Boolean fullscreen )
Description	Sets the rendering of the video content to full-screen (`fullscreen = true`) or windowed (`fullscreen = false`) mode (as per [Req. 5.7.1.c] of [CEA-2014-A]). If this indicates a change in mode, this shall result in a change of the value of property fullScreen. Changing the mode shall not affect the z-index of the video object.
Arguments	fullScreen	Boolean to indicate whether video content should be rendered full-screen or not.

Boolean setVolume( Integer volume )

Description

Adjusts the volume of the currently playing media to the volume as indicated by volume. Allowed values for the volume argument are all the integer values starting with 0 up to and including 100. A value of 0 means the sound will be muted. A value of 100 means that the volume will become equal to current “master” volume of the device, whereby the “master” volume of the device is the volume currently set for the main audio output mixer of the device. All values between 0 and 100 define a linear increase of the volume as a percentage of the current master volume, whereby the OITF shall map it to the closest volume level supported by the platform.

The method returns true if the volume has changed. Returns false if the volume has not changed. Applications may use the getVolume() method to retrieve the actual volume set.

Arguments volume Integer value between 0 up to and including 100 to indicate volume level.

Integer getVolume( )
Description	Returns the actual volume level set; for systems that do not support individual volume control of players, this method will have no effect and will always return 100.

Integer release( )

Description

Releases the decoder/tuner used for displaying the video broadcast inside the video/broadcast object, stopping any form of visualization of the video inside the video/broadcast object and releasing any other associated resources.

If the object was created with an allocationMethod of STATIC_ALLOCATION, the releasing of resources shall change this to DYNAMIC_ALLOCATION.

void stop( )

Description

Stop presenting broadcast video. If the video/broadcast object is in any state other than the unrealized state, it shall transition to the stopped state and stop video and audio presentation. This shall have no effect on access to non-media broadcast resources such as EIT information.

Calling this method from the unrealized state shall have no effect.

See section 7.13.1.1 for more information of its usage.

7.13.1.4 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onfocus	focus (as defined in section 5.2.1.2 of the DOM Level 3 Events specification as referenced in [OIPF_WSTVP2])	Bubbles: No Cancellable: No Context Info: None
onblur	blur (as defined in section 5.2.1.2 of the DOM Level 3 Events specification as referenced in [OIPF_WSTVP2])	Bubbles: No Cancellable: No Context Info: None
onFullScreenChange	FullScreenChange	Bubbles: No Cancellable: No Context Info: None
onChannelChangeError	ChannelChangeError	Bubbles: No Cancellable: No Context Info: `channel`, `errorState`
onChannelChangeSucceeded	ChannelChangeSucceeded	Bubbles: No Cancellable: No Context Info: `channel`
onPlayStateChange	PlayStateChange	Bubbles: No Cancellable: No Context Info: `state`, `error`

Note: these DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving these events during the bubbling or the capturing phase. Applications that use DOM event handlers shall call the addEventListener() method on the video/broadcast object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.13.1.5 Styling

video/broadcast objects shall support CSS-property z-index, in both full-screen and windowed mode.

7.13.2 Extensions to video/broadcast for recording and time-shift

If an OITF has indicated support for recording functionality (i.e. by giving value true to element <recording> as specified in section 9.3.3 in its capability description), the OITF shall support the following additional constants, properties and methods on the video/broadcast object, in order to start a recording and/or time-shift of a current broadcast.

Note that this functionality is subject to the security model as specified in section 10.1.

This functionality is subject to the state transitions represented in the following state diagram:

Figure 15: PVR States for recordNow and timeshifting using video/broadcast (normative)

Note that when the user switches to another channel whilst the current channel is being recorded using recordNow or the video/broadcast object gets destroyed, the conflict resolution and the release of resources is implementation dependent. The OITF may report a recording error using a RecordingEvent> with value 0 (“Unrealized”) for argument state and with value 2 (“Tuner conflict”) for argument error in that case.

7.13.2.1 Constants

Name	Value	Use
POSITION_START	0	Indicates a playback position relative to the start of the buffered content.
POSITION_CURRENT	1	Indicates a playback position relative to the current playback position.
POSITION_END	2	Indicates a playback position relative to the end of the buffered content.

7.13.2.2 Properties

function onPlaySpeedChanged( Number speed )

The function that is called when the playback speed of a channel changes.

The specified function is called with one argument, speed, which is defined as follows:

Number speed – the playback speed of the media at the time the event was dispatched.

If the playback reaches the beginning of the time-shift buffer at rewind playback speed, then the play state is changed to 2 (‘paused’) and a PlaySpeedChanged event with a speed of 0 is generated. If the playback reaches the end of the time-shift buffer at fast-forward playback speed, then the play speed is set to 1.0 and a PlaySpeedChanged event is generated.

function onPlayPositionChanged( Integer position )

The function that is called when change occurs in the play position of a channel due to the use of trick play functions.

The specified function is called with one argument, position, which is defined as follows:

Integer position – the playback position of the media at the time the event was dispatched, measured from the start of the timeshift buffer. If the value of the currentTimeShiftMode property is 1, this is measured in milliseconds from the start of the timeshift buffer. If the value of the currentTimeShiftMode property is 2, this is measured in milliseconds from the start of the media item. If the play position cannot be determined, this argument takes the value undefined.

readonly Integer playbackOffset

Returns the playback position, specified as the positive offset of the live broadcast in seconds, in the currently rendered (timeshifted) broadcast.

When the currentTimeShiftMode property has the value 1, the value of this property is undefined.

readonly Integer maxOffset

Returns the maximum playback offset, in seconds of the live broadcast, which is supported for the currently rendered (timeshifted) broadcast. If the maximum offset is unknown, the value of this property shall be undefined.

When the currentTimeShiftMode property has the value 1, the value of this property is undefined.

readonly Integer recordingState

Returns the state of the OITF’s timeshift and recordNow functionality for the channel shown in the video/broadcast object. One of:

Value	Description
0	Unrealized: user/application has not requested timeshift or recordNow functionality for the channel shown. No timeshift or recording resources are claimed in this state.
1	Recording has been newly scheduled.
2	Recording is about to start. The receiver may be monitoring EPG data in order to ensure that the programme scheduled to be recorded has not been moved, or to support "accurate recording" functionality as defined in section 11 of TS 102 323 [TS102323], where slight changes in the start time of the recording do not result in the start of the recording being missed. No recording resources have yet been acquired, although the OITF may have tuned to the channel which is to be recorded.
3	Acquiring recording resources (incl. media connection).
4	Recording has started.
5	Recording has been updated.
6	Recording has successfully completed.
10	Acquiring timeshift resources (incl. media connection).
11	Timeshift mode has started.

function onRecordingEvent( Integer state, Integer error, String recordingId )

This function is the DOM 0 event handler for notification of state changes of the recording functionality. The specified function is called with the following arguments:

Integer state - The current state of the recording. One of:

Value	Description
0	Unrealized: user/application has not requested timeshift or recordNow functionality for the channel shown. No timeshift or recording resources are claimed in this state.
1	Recording has been newly scheduled.
2	Recording is about to start. The receiver may be monitoring EPG data in order to ensure that the programme scheduled to be recorded has not been moved, or to support "accurate recording" functionality as defined in section 11 of TS 102 323 [TS102323], where slight changes in the start time of the recording do not result in the start of the recording being missed. No recording resources have yet been acquired, although the OITF may have tuned to the channel which is to be recorded.
3	Acquiring recording resources (incl. media connection).
4	Recording has started.
5	Recording has been updated.
6	Recording has successfully completed.
10	Acquiring timeshift resources (incl. media connection).
11	Timeshift mode has started.

Integer error - If the state of the recording has changed due to an error, this field contains an error code detailing the type of error. One of:

Value	Description
0	The recording sub-system is unable to record due to resource limitations.
1	There is insufficient storage space available. (Some of the recording may be available).
2	Tuner conflict (e.g. due to conflicting scheduled recording).
3	Recording not allowed due to DRM restrictions.
4	Recording has stopped before completion due to unknown (probably hardware) failure.
10	Timeshift not possible due to resource limitations.
11	Timeshift not allowed due to DRM restrictions.
12	Timeshift ended due to unknown failure.

If no error has occurred, this argument shall take the value undefined.

String recordingId - The identifier of the recording to which this event refers, This shall be equal to the value of the id property for the affected recording, if the event is associated with a specific recording.

readonly Integer playPosition

If the value of the currentTimeShiftMode property is 1, the current playback position of the media, measured in milliseconds from the start of the timeshift buffer.

If the value of the currentTimeShiftMode property is 2, the current playback position of the media, measured in milliseconds from the start of the media item.

readonly Number playSpeed

The current play speed of the media.

readonly Number playSpeeds[ ]

Returns the ordered list of playback speeds, expressed as values relative to the normal playback speed (1.0), at which the currently specified A/V content can be played (as a time-shifted broadcast in the video/broadcast object), or undefined if the supported playback speeds are not known or the video/broadcast object is not in timeshift mode.

If the video/broadcast object is in timeshift mode, the playSpeeds array shall always include at least values 1.0 and 0.0.

function onPlaySpeedsArrayChanged( )

The function that is called when the playSpeeds array values have changed. An application that makes use of the playSpeeds array needs to read the values of the playSpeeds property again.

Integer timeShiftMode

The time shift mode indicates the mode of operation for support of timeshift playback in the video/broadcast object. Valid values are:

Value	Description
0	Timeshift is turned off.
1	Timeshift shall use “local resource”.
2	Timeshift shall use “network resources”.
3	Timeshift shall first use “local resource” when available and fallback to “network resources”.

If property is not set the default value of the property is according to preferredTimeShiftMode in section 7.3.2.1.

readonly Integer currentTimeShiftMode

When timeshift is in operation the property indicates which resources are currently being used. Valid values are:

Value	Description
0	No timeshift.
1	Timeshift using “local resource”.
2	Timeshift using “network resources”.

7.13.2.3 Methods

String recordNow( Integer duration )

Description

Starts recording the broadcast currently rendered in the video/broadcast object. If the OITF has buffered the broadcasted content, the recording starts from the current playback position in the buffer, otherwise start recording the broadcast stream as soon as possible after the recording resources have been acquired. The specified duration is used by the OITF to determine the minimum duration of the recording in seconds from the current starting point.

Calling recordNow() while the broadcast that is currently rendered in the video/broadcast object is already being recorded, shall have no effect on the recording and shall return the value null.

In other cases, this method returns a String value representing a unique identifier to identify the recording. If the OITF provides recording management functionality through the APIs defined in section 7.10.4, this shall be the value of the id property of the associated Recording object defined in section 7.10.5.

The OITF shall guarantee that recording identifiers are unique in relation to download identifiers and CODAsset identifiers.

The method returns undefined if the given argument is not accepted to trigger a recording.

If the OITF supports metadata processing in the terminal, the fields of the resulting Recording object may be populated using metadata retrieved by the terminal. Otherwise, the values of these fields shall be implementation-dependent.

Arguments duration The minimum duration of the recording in seconds. A value of -1 indicates that the recording should continue until stopRecording() is called, storage space is exhausted, or an error occurs. In this case it is essential that stopRecording() is called later.

void stopRecording( )
Description	Stops the current recording started by recordNow().

Boolean pause( )

Description

Pause playback of the broadcast.

The action taken depends on the value of the timeShiftMode property.

If the value of the timeShiftMode property is 0, if trick play is not supported for the channel currently being rendered, or if the current time shift mode is not supported for the type of channel being presented (e.g. attempting to use network resource to time shift a DVB or analogue channel) this method shall return false.

If the timeshift mode is set to 1 or 3 (local resources) and if recording has not yet been started, this method will start recording the broadcast that is currently being rendered live (i.e., not time-shifted) in the video/broadcast object. If the OITF has buffered the ‘live’ broadcasted content, the recording starts with the content that is currently being rendering in the video/broadcast object. If the recording started successfully, the rendering of the broadcasted content is paused, i.e. a still-image video frame is shown.

If the timeshift mode is set to 2 (network resources) then the OITF shall follow the procedures defined in section 8.2.3.4 and returns true. Since this operation is asynchronous when the procedure are executed successful the rendering of the broadcasted content is paused, i.e. a still-image video frame is shown, and PlaySpeedChanged event is generated.

If the specified timeshift mode is not supported, this method shall return false. Otherwise, this method shall return true. Acquiring the necessary resources to enable the specified timeshift mode may be an asynchronous operation; applications may receive updates of this process by registering a listener for RecordingEvents as defined in section 7.13.2.4.

If trick play is not supported for the channel currently being rendered, this method shall return false, otherwise true is returned.

This operation may be asynchronous, and presentation of the video may not pause until after this method returns. For this reason, a PlaySpeedChanged event will be generated when the operation has completed, regardless of the success of the operation. If the operation fails, the argument of the event shall be set to the previous play speed.

Boolean resume( )

Description

Resumes playback of the time-shifted broadcast channel that is currently being rendered in the video/broadcast object at the speed specified by setSpeed(). If the desired speed was not set via setSpeed(), playback is resumed at normal speed (i.e. speed 1.0). If the video/broadcast object is currently not rendering a time-shifted channel, the OITF shall ignore the request to start playback and shall return false. If playback cannot be resumed the OITF shall also return false, otherwise true is returned.

This operation may be asynchronous, and presentation of the video may not resume until after this method returns. For this reason, a PlaySpeedChanged event will be generated when the operation has completed, regardless of the success of the operation. If the operation fails, the argument of the event shall be set to the previous play speed.

The action taken depends on the value of the timeShiftMode property.

If the value of the timeShiftMode property is 1 or 3 (local resources) then the OITF shall resume playback of the broadcast channel as specified above and return true.

If the value of the timeShiftMode property is 2 (network resources) then the OITF shall follow the procedures defined in section 7.13.2.4 and return true. Since this operation is asynchronous when the procedure is successfully executed a PlaySpeedChanged event is generated with current speed.

After initial operation of resume() several events may affect the operation.

If during fast forward the end of stream is reached the playback shall resume at normal speed and a PlaySpeedChanged event is generated. If the end of stream is reached due to end of content the playback will automatically be paused and a PlaySpeedChanged event is generated. Any resources used for time-shifting shall not be discarded.

If during rewinding the playback reaches the point that it cannot be rewound further, playback will automatically be paused (i.e. the play speed will be changed to 0) and a PlaySpeedChanged event is generated.

If for any of these events timeShiftMode is set to 3 and local resources are not available anymore then network sources shall be used according to the procedures defined in section 7.13.2.4. The OITF shall perform a smooth transition of the stream between local and network resources.

Boolean setSpeed( Number speed )

Description

Sets the playback speed of the time-shifted broadcast to the value speed, without changing the paused/resumed state of the time-shifted broadcast.

When playback is paused (i.e. by setting the play speed to 0), the last decoded frame of video is displayed.

If the time-shifted broadcast cannot be played at the desired speed, specified as a value relative to the normal playback speed, the playback speed will be set to the best approximation of speed. Applications are not required to pause playback of the broadcast or take any other action before calling setSpeed().

If the video/broadcast object is currently not rendering a time-shifted channel, the OITF shall ignore the request to change the playback speed and shall return false, otherwise true is returned.

This operation may be asynchronous, and presentation of the video may not be affected until after this method returns. For this reason, a PlaySpeedChanged event will be generated when the operation has completed, regardless of the success of the operation. If the operation fails, the argument of the event shall be set to the previous play speed.

The action taken depends on the value of the timeShiftMode property.

If the value of the timeShiftMode property is 1 or 3 (local resources) then the setSpeed() method sets the playback speed of the time-shifted broadcast to the value speed.

If the timeShiftMode is set to 2 (network resources) the OITF shall follow the procedures defined in section 7.13.2.4 and return true. Since this operation is asynchronous when the procedure is successfully executed PlaySpeedChanged event is generated with the new speed.

After initial operation of setSpeed() several events may affect the operation.

If during rewinding the playback has reaches the point that it cannot be rewound further, playback shall resume at normal speed and a PlaySpeedChanged event is generated.

If for any of these events if timeShiftMode is set to 3 and local resources are not available anymore then network sources shall be used according to the procedures defined in section 7.13.2.4. The OITF shall perform a smooth transition of the stream between local and network resources.

Arguments speed The desired relative playback speed, specified as a float value relative to the normal playback speed of 1.0. A negative value indicates reverse playback. If the time-shifted broadcast cannot be played at the desired speed, the playback speed will be set to the best approximation.

Boolean seek( Integer offset, Integer reference )
Description	Sets the playback position of the time-shifted broadcast that is being rendered in the `video/broadcast` object to the position specified by the offset and the reference point as specified by one of the constants defined in section 7.13.2.1. Returns `true` if the playback position is a valid position to seek to, `false` otherwise. If the `video/broadcast` object is currently not rendering a time-shifted channel or if the position falls outside the time-shift buffer, the OITF shall ignore the request to seek and shall return the value `false`. Applications are not required to pause playback of the broadcast or take any other action before calling `seek()`. This operation may be asynchronous, and presentation of the video may not be affected until after this method returns. For this reason, a `PlayPositionChanged` event will be generated when the operation has completed, regardless of the success of the operation. If the operation fails, the argument of the event shall be set to the previous play position. The action taken depends on the value of the timeShiftMode property. If the timeShiftMode is set to 1 (local resources) the `seek()` method sets the playback position of the time-shifted broadcast that is being rendered in the `video/broadcast` object as defined above. Playback of live content is resumed if the new position equals the end of the time-shift buffer. If the timeShiftMode is set to 2 (network resources) the OITF shall follow the procedures defined in section 7.13.2.4 and return `true`. Since this operation is asynchronous when the procedure is successfully executed `PlayPositionChanged` event is generated with the new position. Note that if timeShiftMode is set to 3 then local resources are used over network resources. After initial operation of `seek()` several events may affect the operation. If during fastforward the end of stream is reached the playback shall resume at normal speed and a `PlaySpeedChanged` event is generated. If the end of stream is reached due to end of content the playback will automatically be paused and a `PlaySpeedChanged` event is generated. Any resources used for time-shifting shall not be discarded. If for any of these events if timeShiftMode is set to 3 and local resources are not available anymore then network sources shall be used according to the procedures defined in section 7.13.2.4. The OITF shall perform a smooth transition of the stream between local and network resources.
Arguments	offset	The offset from the reference position, in seconds. This can be either a positive value to indicate a time later than the reference position or a negative value to indicate a time earlier than the reference position.
	reference	The reference point from which the offset shall be measured. The reference point can be either `POSITION_CURRENT`, `POSITION_START`, or `POSITION_END`.

Boolean stopTimeshift( )

Description

Stops rendering in time-shifted mode of the broadcast channel in the video/broadcast object and, if applicable, plays the current broadcast from the live point and stops time-shifting the broadcast. The OITF shall release all resources that were used to support time-shifted rendering of the broadcast.

Returns true if the time-shifted broadcast was successfully stopped and resources were released and false otherwise. If the video/broadcast object is currently not rendering a time-shifted channel, the OITF shall ignore the request to stop the time-shift and shall return the value false.

In addition to these methods, the OITF shall support an additional optional attribute “offSet” on the setChannel(Channel channel, Boolean trickplay, String contentAccessDescriptorURL) method of the video/broadcast object as defined in section 7.13.1.3, if the OITF has indicated support for scheduled content over IP by defining one or more ID_IPTV_* values as part of the transport attribute of the <video_broadcast> element in the capability description.

void setChannel( Channel channel, Boolean trickplay, String contentAccessDescriptorURL, Integer offset )
Description	Requests the OITF to switch a (logical or physical) tuner to the specified channel and render the received broadcast content in the area of the browser allocated for the `video/broadcast` object, as specified by the setChannel(Channel channel, Boolean trickPlay, String contentAccessDescriptorURL) method in section 7.13.1.3. The additional `offSet` attribute optionally specifies the desired offset with respect to the live broadcast in number of seconds from which the OITF should start playback immediately after the channel switch (whereby offSet is given as a positive value for seeking to a time in the past). If an OITF cannot start playback from the desired position, as indicated by the specified `offSet` (e.g. because the OITF did not, or could not, record the specified channel prior to the call to `setChannel`), if the specified `offSet` is ‘0’, or if the `offSet` is not specified, the OITF shall start playback from the live position after the specified channel switch.
Arguments	channel	As defined for method setChannel() in section 7.13.1.3.
	trickplay	Optional flag as defined for method setChannel() in section 7.13.1.3.
	contentAccessDescriptorURL	Optional flag as defined for method setChannel() in section 7.13.1.3.
	offset	The optional offset attribute may be used to specify the desired offset with respect to the live broadcast in number of seconds from which the OITF should start playback immediately after the channel switch (whereby offset is given as a negative value for seeking to a time in the past).

7.13.2.4 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated, in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onRecordingEvent	RecordingEvent	Bubbles: No Cancellable: No Context Info: `state`, `error`, `recordingId`
onPlaySpeedChanged	PlaySpeedChanged	Bubbles: No Cancellable: No Context Info: `speed`
onPlayPositionChanged	PlayPositionChanged	Bubbles: No Cancellable: No Context Info: `position`
onPlaySpeedsArrayChanged	PlaySpeedsArrayChanged	Bubbles: No Cancellable: No Context Info: None

Note: the DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving these events during the bubbling or the capturing phase. Applications that use DOM event handlers shall call the addEventListener() method on the video/broadcast object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.13.3 Extensions to video/broadcast for access to EIT p/f

The following properties and events shall be added to the video/broadcast embedded object, if the OITF has indicated support for accessing DVB-SI EIT p/f information, by giving the value “true” to element <clientMetadata> and the value “eit-pf” or “dvb-si” to the type attribute of that element as defined in section 9.3.7 in their capability profile.

Access to these properties shall adhere to the security model in section 10. The associated permission name is “permission_metadata”.

readonly ProgrammeCollection programmes

The collection of programmes available on the currently tuned channel. This list is a ProgrammeCollection as defined in section 7.16.3 and is ordered by start time, so index 0 will always refer to the present programme (if this information is available).

If the type attribute of the <clientMetadata> element in the OITF’s capability description has the value “eit-pf”, this list shall at least provide Programme objects as defined in section 7.16.2 for the present and the directly following programme on the currently tuned channel, if that information is available. In other words, the DAE application should not expect programmes.length to be larger than 2.

If the video/broadcast object is not currently tuned to a channel, or if the present/following information has not yet been retrieved (e.g. the object has just tuned to a new channel and present/following information has not yet been broadcast), or if present/following information is not available for the current channel, the length of this collection shall be 0.

If the type attribute of the <clientMetadata> element in the OITF’s capability description has a value other than “eit-pf”, an OITF may populate this field from other metadata sources described in [OIPF_META2].

The programmes.length property shall indicate the number of items that are currently known and up to date (i.e. whereby the “startTime + duration” is not smaller than the current time). This may be 0 if no programme information is currently known for the currently tuned channel.

In order to prevent misuse of this information, access to this property shall adhere to the security model in section 10. The associated permission name is “permission_metadata”.

function onProgrammesChanged( )

The function that is called when the programmes property has been updated with new programme information, e.g. when the current broadcast programme is finished and a new one has started. The specified function is called with no arguments.

7.13.3.1 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onProgrammesChanged	ProgrammesChanged	Bubbles: No Cancellable: No Context Info: None

Note: this DOM event is directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving these events during the bubbling or the capturing phase. Applications that use DOM event handlers shall call the addEventListener() method on the video/broadcast object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.13.4 Extensions to video/broadcast for playback of selected components

To support the selection of specific A/V components for playback (e.g. a specific subtitle language, audio language, or camera angle), the classes defined in sections 7.16.5.2 – 7.16.5.5 shall be supported and the constants, properties and methods defined in section 7.16.5.1 shall be supported on the video/broadcast object.

7.13.5 Extensions to video/broadcast for parental ratings errors

For parental rating related errors or changes during playback of A/V content through the video/broadcast object an OITF shall support the following intrinsic event properties and corresponding DOM events for the video/broadcast object:

function onParentalRatingChange( String contentID, ParentalRatingCollection ratings, String DRMSystemID, Boolean blocked )

The function that is called whenever the parental rating of the content being played inside the embedded object changes.

These events may occur at the start of a new content item, or during playback of a content item (e.g. during playback of linear TV content).

The specified function is called with four arguments contentID, ratings, DRMSystemID and blocked which are defined as follows:

String contentID – the content ID to which the parental rating change applies. If the event is generated by the DRM system, it shall be the unique identifier for that content in the context of the DRM system (i.e. in the case of Marlin BB it is the Marlin contentID, in the case of CSPG-CI+ the value of this field is null). Otherwise it may be null or undefined.
ParentalRatingCollection ratings – the parental ratings of the currently playing content. The ParentalRatingCollection object is defined in section 7.9.5.
String DRMSystemID – the DRM System ID of the DRM system that generated the event as defined by element DRMSystemID in section 3.3.2 of [OIPF_META2]. The value shall be null if the parental control is not enforced by a particular DRM system.
Boolean blocked – flag indicating whether consumption of the content is blocked by the parental control system as a result of the new parental rating value.

function onParentalRatingError( String contentID, ParentalRatingCollection ratings, String DRMSystemID )

The function that is called when a parental rating error occurs during playback of A/V content inside the embedded object, and is triggered whenever one or more parental ratings are discovered and none of them are valid. A valid parental rating is defined as one which uses a parental rating scheme that is supported by the OITF and which has a parental rating value that is supported by the OITF.

The specified function is called with three arguments contentID, ratings and DRMSystemID which are defined as follows:

String contentID – the content ID to which the parental rating change applies. If the event is generated by the DRM system, it shall be the unique identifier for that content in the context of the DRM system (i.e. in the case of Marlin BB it is the Marlin contentID, in the case of CSPG-CI+ the value of this field is null). Otherwise it may be null or undefined.
ParentalRatingCollection ratings – the parental ratings of the currently playing content. The ParentalRatingCollection object is defined in section 7.9.5.
String DRMSystemID – optional argument that specifies the DRM System ID of the DRM system that generated the event as defined by element DRMSystemID in section 3.3.2 of [OIPF_META2]. The value shall be null if the parental control is not enforced by a particular DRM system.

7.13.5.1 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated, in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onParentalRatingChange	ParentalRatingChange	Bubbles: No Cancellable: No Context Info: `contentID`, `ratings`, `DRMSystemID`, `blocked`
onParentalRatingError	ParentalRatingError	Bubbles: No Cancellable: No Context Info: `contentID`, `ratings`, `DRMSystemID`

Note: the above DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving a ParentalRatingError event during the bubbling or the capturing phase. The Applications that use DOM event handlers shall call the addEventListener() method on the video/broadcast object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.13.6 Extensions to video/broadcast for DRM rights errors

This section shall apply to OITF and/or server devices which have indicated support for DRM protection by providing one or more <drm> elements as specified in section 9.3.10:

For notifying JavaScript about DRM licensing errors during playback of DRM protected A/V content through the “video/broadcast” object, an OITF shall support the following intrinsic event property and corresponding DOM event for the “video/broadcast” object:

function onDRMRightsError( Integer errorState, String contentID, String DRMSystemID, String rightsIssuerURL )

The function that is called:

Whenever a rights error occurs for the A/V content (no license, license invalid), which has led to blocking consumption of the content.
Whenever a rights change occurs for the A/V content (license valid), which leads to unblocking the consumption of the content.

This may occur during playback, recording or timeshifting of DRM protected AV content.

The specified function is called with four arguments errorState, contentID, DRMSystemID and rightsIssuerURL which are defined as follows:

Integer errorState – error code detailing the type of error:
- 0: no license, consumption of the content is blocked.
- 1: invalid license, consumption of the content is blocked.
- 2: valid license, consumption of the content is unblocked.
String contentID – the unique identifier of the protected content in the scope of the DRM system that raises the error (i.e. in the case of Marlin BB it is the Marlin contentID, in the case of CSPG-CI+ the value of this field is null).
String DRMSystemID – DRMSystemID as defined by element DRMSystemID in section 3.3.2 of [OIPF_META2]. For example, for Marlin, the DRMSystemID value is “urn:dvb:casystemid:19188”.
String rightsIssuerURL – optional element indicating the value of the rightsIssuerURL that can be used to non-silently obtain the rights for the content item currently being played for which this DRM error is generated, in cases whereby the rightsIssuerURL is known. Cases whereby the rightsIssuerURL is known include cases whereby the rightsIssuerURL has been extracted from the MPEG2_TS of the protected content, retrieved from the SD&S discovery record or from the associated BCG metadata. The corresponding rightsIssuerURL fields are defined in section 4.1.3.4 of [OIPF_CSP2] and in section 3.3.2 of [OIPF_META2] respectively. If different URLs are retrieved from the stream and the metadata, then the conflict resolution is implementation-dependent.
No version of the OIPF CSP specification has contained a section 4.1.3.4 - the required information/reference may be in a different section

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated, in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onDRMRightsError	DRMRightsError	Bubbles: No Cancellable: No Context Info: `errorState`, `contentID`, `DRMSystemID`, `rightsIssuerURL`

Note: the above DOM event is directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving a DRMRightsError event during the bubbling or the capturing phase. Applications that use DOM event handlers shall call the addEventListener() method on the video/broadcast object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.13.7 Extensions to video/broadcast for current channel information

If an OITF has indicated support for extended tuner control (i.e. by giving value true to element <extendedAVControl> as specified in section 9.3.6 in its capability description), the OITF shall support the following additional properties and methods on the video/broadcast object.

The functionality as described in this section is subject to the security model of section 10.1.3.8.

Note the property onChannelScan and methods startScan and stopScan have been moved to section 7.13.9.

7.13.7.1 Properties

readonly Channel currentChannel

The channel currently being presented by this embedded object if the user has given permission to share this information, possibly through a mechanism outside the scope of this specification. If no channel is being presented, or if this information is not visible to the caller, the value of this property shall be null.

The value of this property is not affected during timeshift operations and shall reflect the value prior to the start of a timeshift operation, for both local and network timeshift resources.

7.13.8 Extensions to video/broadcast for creating channel lists from SD&S fragments

NOTE: the method createChannelList() has been moved to section 7.13.9.

7.13.9 The ChannelConfig class

The ChannelConfig class provides the entry point for applications to get information about the list of channels available. It can be obtained in two ways:

By calling the method getChannelConfig() of the video/broadcast embedded object as defined in section 7.13.1.3.
By calling the method createChannelConfig() of the object factory API as defined in section 7.1.1.

The availability of the properties and methods are dependent on the capabilities description as specified in section 9.3. The following table provides a list of the capabilities and the associated properties and methods. If the capability is false the properties and methods shall not be available to the application. Properties and methods not listed in the following table shall be available to all applications as long as the OITF has indicated support for tuner control (i.e. <video_broadcast>true</video_broadcast> as defined in section 9.3.1) in their capability.

Capability	Properties	Methods
Element `<extendedAVControl>` is set to “`true`” as defined in section 9.3.6.	onChannelScan	startScan() stopScan()
Element `<video_broadcast type="ID_IPTV_SDS">` is set as defined in section 9.3.6.		createChannelList()

The functionality as described in this section is subject to the security model of section 10.1.3.1.1 (for obtaining a ChannelConfig object) and section 10.1.3.8 (for properties and methods covered by the <extendedAVControl> capability as defined below).

7.13.9.1 Properties

readonly ChannelList channelList

The list of channels.

If an OITF includes a platform-specific application that enables the end-user to choose a channel to be presented from a list then all the channels in the list offered to the user by that application shall be included in this ChannelList.

The list of channels will be a subset of all those available to the OITF. The precise algorithm by which this subset is selected will be market and/or implementation dependent. For example;

If an OITF with a DVB-T tuner receives multiple versions of the same channel, one would be included in the list and the duplicates discarded
An OITF with a DVB tuner will often filter services based on service type to discard those which are obviously inappropriate or impossible for that device to present to the end-user, e.g. firmware download services.

The order of the channels in the list corresponds to the channel ordering as managed by the OITF. shall return the value null if the channel list is not (partially) managed by the OITF (i.e., if the channel list information is managed entirely in the network).

The properties of channels making up the channel list shall be set by the OITF to the appropriate values as determined by the tables in section 8.4.3. The OITF shall store all these values as part of the channel list.

Some values are set according to the data carried in the broadcast stream. In this case, the OITF may set these values to undefined until such time as the relevant data has been received by the OITF, for example after tuning to the channel. Once the data has been received, the OITF shall update the properties of the channel in the channel list according to the received data.

Note: There is no requirement for the OITF to pro-actively tune to every channel to gather such data.

readonly FavouriteListCollection favouriteLists

A list of favourite lists. shall return the value null if the favourite lists are not (partially) managed by the OITF (i.e., if the favourite lists information is managed entirely in the network).

readonly FavouriteList currentFavouriteList

Currently active Favourite channel list object. If currentFavouriteList is undefined, no favourite filter list is currently applied.

The OITF shall return the value null if the favourite lists are not (partially) managed by the OITF (i.e. if the favourite lists information is managed entirely in the network).

function onChannelScan( Integer scanEvent, Integer progress, Integer frequency, Integer signalStrength, Integer channelNumber, Integer channelType, Integer channelCount, Integer transponderCount, Channel newChannel )

This function is the DOM 0 event handler for events relating to channel scanning. On IP-only receivers, setting this property shall have no effect.

The specified function is called with the following arguments:

Integer scanEvent - The type of event. Valid values are:

Value	Description
0	A channel scan has started.
1	Indicates the current progress of the scan.
2	A new channel has been found.
3	A new transponder has been found.
4	A channel scan has completed.
5	A channel scan has been aborted.

Integer progress - the progress of the scan. Valid values are in the range 0 - 100, or -1 if the progress is unknown.
Integer frequency - The frequency of the transponder in kHz (for scans on RF sources only).
Integer signalStrength - The signal strength for the current channel. Valid values are in the range 0 - 100, or -1 if the signal strength is unknown.
Integer channelNumber - The logical channel number of the channel that has been found.
Integer channelType - The type of channel that has been found. Valid values are the same as for Channel.channelType.
Integer channelCount - The total number of channels found so far during the scan.
Integer transponderCount - The total number of transponders found so far during the scan (RF sources only).
Channel newChannel - When scanEvent equals 2, this argument provides a reference to the Channel object that represents the newly identified channel. For other scanEvent values this argument shall be null

function onChannelListUpdate( )

This function is the DOM 0 event handler for events relating to channel list updates. Upon receiving a ChannelListUpdate event, if an application has references to any Channel objects then it should dispose of them and rebuild its references. Where possible Channel objects are updated rather than removed, but their order in the ChannelConfig.all collection may have changed. Any lists created with ChannelConfig.createFilteredList() should be recreated in case channels have been removed.

readonly Channel currentChannel

The current channel of the OITF if the user has given permission to share this information, possibly through a mechanism outside the scope of this specification. If no channel is being presented, or if this information is not visible to the caller, the value of this property shall be null.

In an OITF where exactly one video/broadcast object is in any state other than Unrealized and the channel being presented by that video/broadcast object is the only broadcast channel being presented by the OITF then changes to the channel presented by that video/broadcast object shall result in changes to the current channel of the OITF.

In an OITF which is presenting more than one broadcast channel at the same time, the current channel of the OITF is the channel whose audio is being presented (as defined in the bindToCurrentChannel() method). If that current channel is under the control of a DAE application via a video/broadcast object then changes to the channel presented by that video/broadcast object shall result in changes to the current channel of the OITF.

7.13.9.2 Methods

ChannelList createFilteredList( Boolean blocked, Boolean favourite, Boolean hidden, String favouriteListID )

Description

Create a filtered list of channels. Returns a subset of ChannelConfig.channelList.

The blocked, favourite and hidden flags indicate whether a channel is included in the returned list. These flags correspond to the properties on Channel with the same names. Each flag may be set to one of three values:

Value	Meaning
true	The channel is added if and only if the corresponding property has the value true.
false	The channel is added if and only if the corresponding property has the value false.
undefined	The channel is added regardless of the state of the corresponding property.

A channel will only be added to the list if the values of all three flags allow it to be added.

The favouriteListID attribute is used to select a particular favouriteList that the createFilteredList method uses as a basis of the filtering process. If favouriteListID is the empty string (i.e. “”), then the filtering is performed on all available channels as defined by ChannelConfig.channelList.

Arguments blocked Flag indicating whether manually blocked channels shall be added to the list.

favourite Flag indicating whether favourite channels shall be added to the list.

hidden Flag indicating whether hidden channels shall be added to the list.

favouriteListID

If the value of the favourite flag is true, indicates which favourites list shall be filtered upon.

void startScan( ChannelScanOptions options, ChannelScanParameters scanParameters )
Description	Start a scan for new channels on all available sources. When each source finishes scanning, an `UpdateEvent` shall be raised with the type `CHANNELS_INVALIDATED` and any channel lists for that source shall have been updated. On IP-only receivers, this method shall have no effect.
Arguments	options	The options to the channel scan operation.
	scanParameters	The tuning parameters to be scanned. The value of this argument shall be one of the classes that implement the ChannelScanParameters interface and shall not be an instance of the ChannelScanParameters class.

void stopScan( )

Description

Stop a channel scan, if one is in progress. Any sources that have not finished scanning shall have their scans aborted and channel line-ups for shall not be changed.

On IP-only receivers, this method shall have no effect.

ChannelList createChannelList( String bdr )
Description	Creates a ChannelList object from the specified SD&S Broadcast Discovery Record. Channels in the returned channel list will not be included in the channel list that can be retrieved via calls to getChannelConfig().
Arguments	bdr	An XML-encoded string containing an SD&S Broadcast Discovery Record as specified in [OIPF_META2]. If the string is not a valid Broadcast Discovery Record, this method shall return `null`.

Channel createChannelObject( Integer idType, Integer onid, Integer tsid, Integer sid, Integer sourceID, String ipBroadcastID )
Description	Creates a Channel object of the specified `idType`. The Channel object can subsequently be used by the setChannel method to switch a tuner to a channel that is not part of the channel list which was conveyed by the OITF to the server. The scope of the resulting Channel object is limited to the JavaScript environment (incl. `video/broadcast` object) to which the Channel object is returned, i.e. it does not get added to the channellist available through method getChannelConfig. If the channel of the given `idType` cannot be created or the given (combination of) arguments are not considered valid or complete, the method shall return `null`. If the channel of the given type can be created and arguments are considered valid and complete, the method shall return a Channel object whereby at a minimum the properties with the same names are given the same value as the given arguments of the `createChannelObject` method. The values specified for the remaining properties of the Channel object are set to `undefined`.
Arguments	idType	The type of channel, as indicated by one of the `ID_*` constants defined in section 7.13.11.1.
	onid	The original network ID. Optional argument that shall be specified when the `idType` specifies a channel of type `ID_DVB_` or `ID_ISDB_`.
	tsid	The transport stream ID. Optional argument that may be specified when the `idType` specifies a channel of type `ID_DVB_` or `ID_ISDB_`.
	sid	The service ID. Optional argument that shall be specified when the `idType` specifies a channel of type `ID_DVB_` or `ID_ISDB_`.
	sourceID	The source_ID. Optional argument that shall be specified when the `idType` specifies a channel of type `ID_ATSC_T`.
	ipBroadcastID	The DVB textual service identifier of the IP broadcast service, specified in the format “`ServiceName.DomainName`”, or the URI of the IP broadcast service. Optional argument that shall be specified when the `idType` specifies a channel of type `ID_IPTV_SDS` or `ID_IPTV_URI`.

ChannelScanParameters createChannelScanParametersObject( Integer idType )

Description

Create an instance of one of the subclasses of the ChannelScanParameters class (or one of its subclasses). The exact subclass that will be returned shall be determined by the value of the idType parameter.

Initial values of all properties on the returned object shall be undefined.

Arguments

idType

The type of object to be created. Valid values are given by the following constants on the Channel class (see section 7.13.11.1):

ID_DVB_T or ID_DVB_T2 – returns an instance of the DVBTChannelScanParameters class.
ID_DVB_C or ID_DVB_C2 – returns an instance of the DVBCChannelScanParameters class.
ID_DVB_S or ID_DVB_S2 – returns an instance of the DVBSChannelScanParameters class.
ID_ATSC_T – returns an instance of the ATSCTChannelScanParameters class.

All other values, or channel types which are not supported by the OITF, shall cause this method to return null.

ChannelScanOptions createChannelScanOptionsObject( )
Description	Create an instance of the ChannelScanOptions class. Initial values of all properties on the returned object shall be `undefined`.

7.13.9.3 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated, in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onChannelScan	ChannelScan	Bubbles: No Cancellable: No Context Info: `scanEvent`, `progress`, `frequency`, `signalStrength`, `channelNumber`, `channelType`, `channelCount`, `transponderCount`, `newChannel`
onChannelListUpdate	ChannelListUpdate	Bubbles: No Cancellable: No Context Info: None

Note: the above DOM event is directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving these events during the bubbling or the capturing phase. Applications that use DOM event handlers shall call the addEventListener() method on the ChannelConfig object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.13.10 The ChannelList class

typedef Collection<Channel> ChannelList

A ChannelList represents a collection of Channel objects. See Annex K for the definition of the collection template.

In addition to the methods and properties defined for generic collections, the ChannelList class supports the additional properties and methods defined below

7.13.10.1 Methods

Channel getChannel( String channelID )
Description	Return the first channel in the list with the specified channel identifier. Returns `null` if no corresponding channel can be found.
Arguments	channelID	The channel identifier of the channel to be retrieved, which is a value as defined for the ccid and ipBroadcastID properties of the Channel object as defined in section 7.13.11.

Channel getChannelByTriplet( Integer onid, Integer tsid, Integer sid, Integer nid )
Description	Return the first (IPTV or non-IPTV) channel in the list that matches the specified DVB or ISDB triplet (original network ID, transport stream ID, service ID). Where no channels of type ID_ISDB_* or ID_DVB_* are available, or no channel identified by this triplet are found, this method shall return `null`.
Arguments	onid	The original network ID of the channel to be retrieved.
	tsid	The transport stream ID of the channel to be retrieved. If set to `null` the client shall retrieve the channel defined by the combination of onid and sid. This makes it possible to retrieve the correct channel also in case a remultiplexing took place which led to a changed tsid.
	sid	The service ID of the channel to be retrieved.
	nid	An optional argument, indicating the network id to be used select the channel when the channel list contains more than one entry with the same `onid`, `tsid` and `sid`.

Channel getChannelBySourceID( Integer sourceID )

Description

Return the first (IPTV or non-IPTV) channel in the list with the specified ATSC source ID.

Where no channels of type ID_ATSC_* are available, or no channel with the specified source ID is found in the channel list, this method shall return null.

Arguments sourceID The ATSC source_ID of the channel to be returned.

7.13.11 The Channel class

The Channel object represents a broadcast stream or service.

Channel objects typically represent channels stored in the channel list (see section 7.13.10). Channel objects may also represent locally defined channels created by an application using the createChannelObject() methods on the video/broadcast embedded object or the ChannelConfig class or the createChannelList() method on the ChannelConfig class. Accessing the channel property of a ScheduledRecording object or Recording object which is scheduled on a locally defined channel shall return a Channel object representing that locally defined channel.

Except for the hidden property, writing to the writable properties on a Channel object shall have no effect for Channel objects representing channels stored in the channel list. Applications should only change these writable properties of a locally defined channel before the Channel object is referenced by another object or passed to an API call as an input parameter. The effects of writing to these properties at any other time is implementation dependent.

The Channel class is defined as follows:

7.13.11.1 Constants

Name	Value	Use
TYPE_TV	0	Used in the channelType property to indicate a TV channel.
TYPE_RADIO	1	Used in the channelType property to indicate a radio channel.
TYPE_OTHER	2	Used in the channelType property to indicate that the type of the channel is unknown, or known but not of type TV or radio.
TYPE_ALL	128	Used during channel scanning to indicate that all TV, radio and other channel types should scanned.
TYPE_HBB_DATA	256	Reserved for data services defined by [TS102796].
ID_ANALOG	0	Used in the idType property to indicate an analogue channel identified by the property ‘freq’ and optionally ‘cni’ or ‘name’.
ID_DVB_C	10	Used in the idType property to indicate a DVB-C channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_DVB_S	11	Used in the idType property to indicate a DVB-S channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_DVB_T	12	Used in the idType property to indicate a DVB-T channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_DVB_SI_DIRECT	13	Used in the idType property to indicate a channel that is identified through its delivery system descriptor as defined by DVB-SI [EN300468] section 6.2.13.
ID_DVB_C2	14	Used in the idType property to indicate a DVB-C or DVB-C2 channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_DVB_S2	15	Used in the idType property to indicate a DVB-S or DVB-S2 channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_DVB_T2	16	Used in the idType property to indicate a DVB-T or DVB-T2 channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.

ID_ISDB_C	20	Used in the idType property to indicate a ISDB-C channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_ISDB_S	21	Used in the idType property to indicate a ISDB-S channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_ISDB_T	22	Used in the idType property to indicate a ISDB-T channel identified by the three properties: ‘onid’, ‘tsid’, ‘sid’.
ID_ATSC_T	30	Used in the idType property to indicate a ATSC-T channel identified by the property ‘sourceid’.
ID_IPTV_SDS	40	Used in the idType property to indicate an IP broadcast channel identified through SD&S by a DVB textual service identifier specified in the format “ServiceName.DomainName” as value for property ‘ipBroadcastID’, with `ServiceName` and `DomainName` as defined in [DVB-IPTV]. This idType shall be used to indicate Scheduled content service defined by [OIPF_PROT2].
ID_IPTV_URI	41	Used in the idType property to indicate an IP broadcast channel identified by a DVB MCAST URI (i.e. `dvb-mcast://`) or by a URI referencing a HAS or MPEG DASH MPD (i.e. `http://` or `https://`), as value for property ipBroadcastID.

7.13.11.2 Properties

This section defines the properties of the Channel object.

Properties that do not apply in a specific circumstance (e.g. onid does not apply unless the channel is of type ID_DVB_* or ID_ISDB_*) shall be undefined. The mapping to these properties is defined in section 8.4.3.

readonly Integer channelType

The type of channel. The value may be indicated by one of the TYPE_* constants defined above. If the type of the channel is unknown then the value shall be “undefined”.

NOTE: Values of this type between 256 and 511 are reserved for use by related specifications on request by liaison.

readonly Integer idType

The type of identification for the channel, as indicated by one of the ID_* constants defined in section 7.13.11.1

readonly String ccid

Unique identifier of a channel within the scope of the OITF. The ccid is defined by the OITF and shall have prefix ‘ccid’: e.g. ‘ccid:{tunerID.}majorChannel{.minorChannel}’.

Note: the format of this string is platform-dependent.

readonly String tunerid

Optional unique identifier of the tuner within the scope of the OITF that is able to receive the given channel.

readonly Integer onid

DVB or ISDB original network ID.

readonly Integer nid

The DVB or ISDB network ID.

readonly Integer tsid

DVB or ISDB transport stream ID.

readonly Integer sid

DVB or ISDB service ID.

readonly Integer sourceID

ATSC source_ID value.

readonly Integer freq

For analogue channels, the frequency of the video carrier in kHz.

readonly Integer cni

For analogue channels, the VPS/PDC confirmed network identifier.

String name

The name of the channel. Can be used for linking analog channels without CNI. Typically, it will contain the call sign of the station (e.g. 'HBO').

readonly Integer majorChannel

The major channel number, if assigned. Value undefined otherwise. Typically used for channels of type ID_ATSC_* or for channels of type ID_DVB_* or ID_IPTV_SDS in markets where logical channel numbers are used.

readonly Integer minorChannel

The minor channel number, if assigned. Value undefined otherwise. Typically used for channels of type ID_ATSC_*.

readonly String dsd

For channels of type ID_DVB_SI_DIRECT created through createChannelObject(), this property defines the delivery system descriptor (tuning parameters) as defined by DVB-SI [EN300468] section 6.2.13.

The dsd property provides a string whose characters shall be restricted to the ISO Latin-1 character set. Each character in the dsd represents a byte of a delivery system descriptor as defined by DVB-SI [EN300468] section 6.2.13, such that a byte at position "i" in the delivery system descriptor is equal the Latin-1 character code of the character at position "i" in the dsd.

Described in the syntax of JavaScript: let sdd[] be the byte array of a system delivery descriptor, in which sdd[0] is the descriptor_tag, then, dsd is its equivalent string, if:
dsd.length==sdd.length and
for each integer i : 0<=i<dsd.length holds: sdd[i] == dsd.charCodeAt(i).

readonly Boolean favourite

Flag indicating whether the channel is marked as a favourite channel or not in one of the favourite lists as defined by the property favIDs.

readonly StringCollection favIDs

The names of the favourite lists to which this channel belongs (see the favouriteLists property on the ChannelConfig class).

readonly Boolean locked

Flag indicating whether the current state of the parental control system prevents the channel from being viewed (e.g. a correct parental control pin has not been entered).

Note that this property supports the option of client-based management of parental control without excluding server-side implementation of parental control.

readonly Boolean manualBlock

Flag indicating whether the user has manually blocked viewing of this channel. Manual blocking of a channel will treat the channel as if its parental rating value always exceeded the system threshold.

Note that this property supports the option of client-based management of manual blocking without excluding server-side management of blocked channels.

readonly String ipBroadcastID

If the channel has an idType of ID_IPTV_SDS, this property denotes the DVB textual service identifier of the IP broadcast service, specified in the format “ServiceName.DomainName” with the ServiceName and DomainName as defined in [DVB-IPTV].

If the Channel has an idType of ID_IPTV_URI, this element denotes a URI of the IP broadcast service.

readonly Integer channelMaxBitRate

If the channel has an idType of ID_IPTV_SDS, this property denotes the maximum bitrate associated to the channel.

readonly Integer channelTTR

If the channel has an idType of ID_IPTV_SDS, this property denotes the TimeToRenegotiate associated to the channel.

readonly Boolean recordable

Flag indicating whether the channel is available to the recording functionality of the OITF. If the value of the pvrSupport property on the application/oipfConfiguration object as defined in section 7.3.3.2 is 0, this property shall be false for all Channel objects.

7.13.11.3 Metadata extensions to Channel

This subsection shall apply for OITFs that have indicated <clientMetadata> with value “true” and a type attribute with values “bcg”, “sd-s”, “eit-pf” or “dvb-si” as defined in section 9.3.7 in their capability profile.

The OITF shall extend the Channel class with the properties and methods described below.

The values of many of these properties may be derived from elements in the BCG metadata. For optional elements that are not present in the metadata, the default value of any property that derives its value from one of those elements shall be undefined.

7.13.11.3.1 Properties

String longName

The long name of the channel. If both short and long names are being transmitted, this property shall contain the long name of the station (e.g. 'Home Box Office'). If the long name is not available, this property shall be undefined.

The value of this property may be derived from the Name element that is a child of the BCG ServiceInformation element describing the channel, where the length attribute of the Name element has the value ‘long’.

String description

The description of the channel. If no description is available, this property shall be undefined.

The value of this field may be taken from the ServiceDescription element that is a child of the BCG ServiceInformation element describing this channel.

readonly Boolean authorised

Flag indicating whether the receiver is currently authorised to view the channel. This describes the conditional access restrictions that may be imposed on the channel, rather than parental control restrictions.

StringCollection genre

A collection of genres that describe the channel.

The value of this field may be taken from the ServiceGenre elements that are children of the BCG ServiceInformation element describing the channel.

Boolean hidden

Flag indicating whether the channel shall be included in the default channel list.

readonly Boolean is3D

Flag indicating whether the channel is a 3D channel.

readonly Boolean isHD

Flag indicating whether the channel is an HD channel.

String logoURL

The URL for the default logo image for this channel.

The value of this field may be derived from the value of the first Logo element that is a child of the BCG ServiceInformation element describing the channel. If this element specifies anything other than the URL of an image, the value of this filed shall be undefined.

7.13.11.3.2 Methods

String getField( String fieldId )
Description	Get the value of the field referred to by `fieldId` that is contained in the BCG metadata for this channel. If the field does not exist, this method shall return `undefined`.
Arguments	fieldId	The name of the field whose value shall be retrieved.

String getLogo( Integer width, Integer height )
Description	Get the URI for the logo image for this channel. The width and height parameters specify the desired width and height of the image; if an image of that size is not available, the URI of the logo with the closest available size not exceeding the specified dimensions shall be returned. If no image matches these criteria, this method shall return `null`. The URI returned shall be suitable for use as the `SRC` attribute in an HTML `IMG` element or as a background image. The URIs returned by this method will be derived from the values of the `Logo` elements that are children of the BCG `ServiceInformation` element describing the channel.
Arguments	width	The desired width of the image
	height	The desired height of the image

7.13.12 The FavouriteListCollection class

typedef Collection<FavouriteList> FavouriteListCollection

The FavouriteListCollection class represents a collection of FavouriteList objects. See Annex K for the definition of the collection template. In addition to the methods and properties defined for generic collections, the FavouriteListCollection class supports the additional methods defined below.

7.13.12.1 Methods

FavouriteList getFavouriteList( String favID )
Description	Return the first favourite list in the collection with the given `favID`.
Arguments	favID	The ID of a favourite list.

7.13.12.2 Extensions to FavouriteListCollection

If an OITF has indicated support for extended tuner control (i.e. by giving value true to element <extendedAVControl> as specified in section 9.3.6 in its capability description), the OITF shall support the following additional constants and methods on the FavouriteListCollection object.

The functionality as described in this section is subject to the security model of section 10.1.3.8.

FavouriteList createFavouriteList( String name )
Description	Create a new favourite list and add it to the collection. The new favourite list shall be returned.
Arguments	name	The name to be associated to the new favourite list.

Boolean remove( Integer index )
Description	Remove the list at the specified index from the collection. This method shall return `true` of the operation succeeded, or `false` if an invalid index was specified.
Arguments	index	The index of the list to be removed.

Boolean commit( )

Description

Commit any changes to the collection to persistent storage. This method shall return true of the operation succeeded, or false if it failed (e.g. due to insufficient space to store the collection).

If a server has indicated that it requires control of the tuner functionality of an OITF in the server capability description for a particular service, then the OITF should send an updated Client Channel Listing to the server using HTTP POST over TLS as described in section 4.8.1.1.

Boolean activateFavouriteList( String favID )
Description	Active the favourite list from the collection. This method shall return `true` if the operation succeeded, or `false` if an invalid index was specified. A newly created favourite list has to be committed before it can be activated.
Arguments	favID	The ID of a favourite list.

7.13.13 The FavouriteList class

typedef Collection<Channel> FavouriteList

The FavouriteList class represents a list of favourite channels. See Annex K for the definition of the collection template. In addition to the methods and properties defined for generic collections, the FavouriteList class supports the additional properties and methods defined below.

In order to preserve backwards compatibility with already existing DAE content the JavaScript toString() method shall return the FavouriteList.id for FavouriteList objects.

7.13.13.1 Properties

readonly String favID

A unique identifier by which the favourite list can be identified.

String name

A descriptive name given to the favourite list.

7.13.13.2 Methods

Channel getChannel( String channelID )
Description	Return the first channel in the favourite list with the specified channel identifier. Returns `null` if no corresponding channel can be found.
Arguments	channelID	The channel identifier of the channel to be retrieved, which is a value as defined for property ccid of the Channel object or a value as defined for property ipBroadcastID of the Channel object as defined in section 7.13.11.

Channel getChannelByTriplet( Integer onid, Integer tsid, Integer sid )
Description	Return the first (IPTV or non-IPTV) channel in the list that matches the specified DVB or ISDB triplet (original network ID, transport stream ID, service ID). Where no channels of type ID_ISDB_* or ID_DVB_* are available, or no channel identified by this triplet are found, this method shall return `null`.
Arguments	onid	The original network ID of the channel to be retrieved.
	tsid	The transport stream ID of the channel to be retrieved. If set to `null` the client shall retrieve the channel defined by the combination of `onid` and `sid`. This makes it possible to retrieve the correct channel also in case a remultiplexing took place which led to a changed `tsid`.
	sid	The service ID of the channel to be retrieved.

Channel getChannelBySourceID( Integer sourceID )

Description

Return the first (IPTV or non-IPTV) channel in the list with the specified ATSC source ID.

Where no channels of type ID_ATSC_* are available, or no channel with the specified source ID is found in the channel list, this method shall return null.

Arguments sourceID The ATSC source_ID of the channel to be returned.

7.13.13.3 Extensions to FavouriteList

If an OITF has indicated support for extended tuner control (i.e. by giving value true to element <extendedAVControl> as specified in section 9.3.6 in its capability description), the OITF shall support the following additional constants and methods on the FavouriteList object.

When the FavouriteList object is updated with new or removed channels it does not take effect until the object is committed. Only after commit() will the updates of a FavouriteList object become available to other DAE applications.

The name property of the FavouriteList object shall be read/write for OITFs which are controlled by a service provider. The following methods shall also be supported:

Boolean insertBefore( Integer index, String ccid )
Description	Insert a new favourite into the favourites list at the specified index. In order to add a ccid at the end of the favourite list the index shall be equal to `length`. This method shall return `true` of the operation succeeded, or `false` if an invalid index was specified (e.g. `index` > (`length`) ).
Arguments	index	The index in the list before which the favourite should be inserted.
	ccid	The ccid of the channel to be added.

Boolean remove( Integer index )
Description	Remove the item at the specified index from the favourites list. Returns `true` of the operation succeeded, or `false` if an invalid index was specified.
Arguments	index	The index of the item to be removed.

Boolean commit( )

Description

Commit any changes to the favourites list to persistent storage. This method shall return true if the operation succeeded, or false if it failed (e.g. due to insufficient space to store the list on the OITF).

7.13.14 Extensions to video/broadcast for channel scan

The section has been merged with the ChannelConfig class (see section 7.13.9 above).

7.13.15 The ChannelScanEvent class

The contents of this section have been merged with section 7.13.9.3 above.

7.13.16 The ChannelScanOptions class

The ChannelScanOptions class defines the options that should be applied during a channel scan operation. This class does not define parameters for the channel scan itself.

7.13.16.1 Properties

Integer channelType

The types of channel that should be discovered during the scan. Valid values are TYPE_RADIO, TYPE_TV, or TYPE_OTHER or TYPE_ALL as defined in section 7.13.11.1.

Boolean replaceExisting

If true, any existing channels in the channel list managed by the OITF shall be removed and the new channel list shall consist only of channels found during the channel scan operation. If false, any channels discovered during the channel scan shall be added to the existing channel list.

7.13.17 The ChannelScanParameters class

This is an empty class that acts as the base interface for channel scan parameters specific to certain types of broadcast network.

7.13.18 The DVBTChannelScanParemeters class

The DVBTChannelScanParameters class represents the parameters needed to perform a channel scan on a DVB-T or DVB-T2 network. This class implements the interface defined by ChannelScanParameters, with the following additions.

The properties that are undefined when performing startScan() are considered to be auto detected.

Integer startFrequency

The start frequency of the scan, in kHz.

Integer endFrequency

The end frequency of the scan, in kHz.

Integer raster

The raster size represented in kHz (typically 7000 or 8000).

String ofdm

The Orthogonal Frequency Division Multiplexing (OFDM) for the indicating frequency. Valid values are:

Value	Description
MODE_1K	OFDM mode 1K
MODE_2K	OFDM mode 2K
MODE_4K	OFDM mode 4K
MODE_8K	OFDM mode 8K
MODE_16K	OFDM mode 16K
MODE_32K	OFDM mode 32K

Integer modulationModes

The modulation modes to be scanned. Valid values are:

Value	Description
1	QPSK modulation
4	QAM16 modulation
8	QAM32 modulation
16	QAM64 modulation
32	QAM128 modulation
64	QAM256 modulation

More than one of these values may be ORed together in order to indicate that more than one modulation mode should be scanned.

String bandwidth

The expected bandwidth. Valid values are:

Value	Description
BAND_1.7MHZ	1.7 MHz bandwidth
BAND_5MHz	5 MHz bandwidth
BAND_6MHz	6 MHz bandwidth
BAND_7MHz	7 MHz bandwidth
BAND_8MHz	8 MHz bandwidth
BAND_10MHz	10 MHz bandwidth

7.13.19 The DVBSChannelScanParemeters class

7.13.19.1 Properties

Integer startFrequency

The start frequency of the scan, in kHz.

Integer endFrequency

The end frequency of the scan, in kHz.

Integer modulationModes

The modulation modes to be scanned. Valid values are:

Value	Description
1	QPSK modulation
2	8PSK modulation
4	QAM16 modulation

More than one of these values may be ORed together in order to indicate that more than one modulation mode should be scanned.

String symbolRate

A comma-separated list of the symbol rates to be scanned, in symbols/sec.

Integer polarisation

The polarisation to be scanned. Valid values are:

Value	Description
1	Horizontal polarisation
2	Vertical polarisation
4	Right-handed/clockwise circular polarisation
8	Left-handed/counter-clockwise circular polarization

More than one of these values may be ORed together in order to indicate that more than one polarisation should be scanned.

String codeRate

The code rate, e.g. “3/4” or “5/6”.

Number orbitalPosition

The orbitalPosition property is used to resolve DiSEqC switch/motor. The value is the orbital position of the satellite, negative value for west, positive value for east. For example, Astra 19.2 East would have orbitalPosition 19.2. Thor 0.8 West would have orbitalPosition -0.8.

Integer networkId

The network ID of the network to be scanned, or undefined if all networks should be scanned.

7.13.20 The DVBCChannelScanParemeters class

The DVBCChannelScanParameters class represents the parameters needed to perform a channel scan on a DVB-C or DVB-C2 network. This class implements the interface defined by ChannelScanParameters, with the following additions.

The properties that are undefined when performing startScan() are considered to be auto detected.

7.13.20.1 Properties

Integer startFrequency

The start frequency of the scan, in kHz.

Integer endFrequency

The end frequency of the scan, in kHz.

Integer raster

The raster size represented in kHz (typically 7000 or 8000).

Boolean startNetworkScanOnNIT

The scan mode for scanning. A false value indicates to scan complete range, a true value indicates scan terminates when a valid NIT is found. The frequency scan is replaced by a scan based on NIT. If networkId is set and the value of this property is set to true the scan continues until there is a match on both.

Integer modulationModes

The modulation modes to be scanned. Valid values are:

Value	Description
4	QAM16 modulation
8	QAM32 modulation
16	QAM64 modulation
32	QAM128 modulation
64	QAM256 modulation
128	QAM1024 modulation
256	QAM2048 modulation

More than one of these values may be ORed together in order to indicate that more than one modulation mode should be scanned.

String symbolRate

A comma-separated list of the symbol rates to be scanned, in symbols/sec.

Integer networkId

The network ID of the network to be scanned, or undefined if all networks should be scanned.

7.13.21 Extensions to video/broadcast for synchronization

The OITF shall support the following additional methods on the video/broadcast object, in order to enable synchronization to broadcast events.

void addStreamEventListener( String targetURL, String eventName, EventListener listener )
Description	Add a listener for the specified DSM-CC stream event. Event triggers are carried in the stream as MPEG private data sections. For robustness, the section describing a particular trigger may be repeated several times. Each section has a version number which is used to disambiguate a new trigger for the same event (which will have a different version number) from a repeated instance of a previous trigger (which will have the same version number). When OITF detects a trigger corresponding to an event for which a listener has been registered, a DOM `StreamEvent` shall be dispatched. An event shall also be dispatched in case of error. An OITF shall dispatch only one DOM `StreamEvent` per unique trigger detected. Repeated instances of the same trigger shall not cause a new DOM StreamEvent to be dispatched. A new trigger for the same event (i.e. an MPEG private data section for the same event but with an updated version number) shall cause a new DOM `StreamEvent` to be dispatched.
Arguments	targetURL	The URL of the DSM-CC StreamEvent object or the event description file describing the event as defined in section 8.2 of [TS102809]
	eventName	The name of the event (in the DSM-CC StreamEvent object) that should be subscribed to.
	listener	The listener for the event.

void removeStreamEventListener( String targetURL, String eventName, EventListener listener )
Description	Remove a stream event listener for the specified stream event name.
Arguments	targetURL	The URL of the DSM-CC StreamEvent object or the event description file describing the event as defined in section 8.2 of [TS102809]
	eventName	The name of the event (in the DSM-CC StreamEvent object) that should be subscribed to.
	listener	The listener for the event.

7.13.21.1 The StreamEvent class

The StreamEvent class is a subclass of the DOM Event class which notifies an application that a synchronisation trigger in a broadcast stream has been detected. This event also notifies an application when the event is no longer being monitored.

Instances of this event are directly dispatched to the event target, and will not bubble nor capture.

readonly String eventName

The name of the stream event.

readonly String data
Data of the DSM-CC StreamEvent’s event encoded in hexadecimal. For example: “0A10B81033” (for a message 5 bytes long).

readonly String text

Text data of the DSM-CC StreamEvent’s event as a string, assuming UTF-8 as the encoding for the DSM-CC StreamEvent’s event. Characters that cannot be transcoded shall be skipped.

readonly String status

The status of the event. Equal to “trigger” when the event is dispatched in response to a trigger in the stream or “error” when an error occurred (e.g. attempting to add a listener for an event that does not exist, or when a StreamEvent object with registered listeners is removed from the carousel).

An event shall be dispatched with an error status if:

the StreamEvent object pointed to by targetURL is not found in the carousel or via broadband
the StreamEvent object pointed to by targetURL does not contain the event specified by the eventName parameter
the carousel containing the event cannot be mounted
the elementary stream which contains the StreamEvent event descriptor is no longer being monitored (e.g. due to another monitoring request or because it disappears from the PMT)
the event description file pointed to by targetURL is not available or does not have the correct syntax.

Once an error is dispatched, the listener shall be automatically unregistered by the OITF.

7.13.22 The ATSCTChannelScanParemeters class

The ATSCTChannelScanParameters class represents the parameters needed to perform a channel scan on an ATSC-T network. This class implements the interface defined by ChannelScanParameters, with the following additions.

The properties that are undefined when performing startScan() are considered to be auto detected.

7.13.22.1 Properties

Integer startFrequency

The start frequency of the scan, in kHz.

Integer endFrequency

The end frequency of the scan, in kHz.

Integer raster

The raster size represented in kHz (typically 7000 or 8000).

Integer modulationModes

The modulation modes to be scanned. Valid values are:

Value	Description
2	2VSB
4	4VSB
8	8VSB
16	16VSB

More than one of these values may be arithmetically summed in order to indicate that more than one modulation mode should be scanned.

7.14 Media playback APIs

This section specifies several extensions to the audio object and the video object defined in section 5.7.1 of [CEA-2014-A]. It also contains a subsection (i.e. section 7.14.10) that defines the audio playback from memory API.

7.14.1 The A/V Control object

NOTE: Most of the text in this section was found in Annex B of previous versions of this specification. It has been moved here and re-structured for readability. No additional text has been included from CEA-2014-A.

The HTML object element (defined in section 4.8.4 of the HTML5 specification as referenced in [OIPF_WSTVP2]) shall support presentation of video and audio or just audio. This presentation shall be indicated by setting the type attribute to one of the “video/” or “audio/” MIME types that is listed in section 3 of [OIPF_MEDIA2] and corresponds to a combination of system layer format, video format and audio format that is supported by the OITF.

When an HTML object is presenting video or audio as defined in this section, the following requirements shall apply:

HTML objects presenting video and/or audio shall be accessible through the DOM and shall support the properties and methods defined by the tables below in addition to those of HTMLObjectElement as defined in the HTML5 specification as referenced in [OIPF_WSTVP2].

Table 9: Properties of the A/V Control Object when the type attribute refers to video or audio
Property type and name	Property Definition
String data	String data [RW] – media URL. If the value of data is changed while media is playing playback is stopped (resulting in a play state change). The default value is the empty string. If the value of this attribute is changed, the related data-attribute inside the DOM tree should be changed accordingly. If the value of this attribute is set to an empty string or is changed, the resources (files, server connections, etc…) currently owned by the object shall be released. The value set in this property may include a temporal fragment interval according to section 4.2.1 of [Media-Fragments-URI] in which case the derived begin time and end time shall serve as bounds for playback. The Normal Play Time format shall be used. The begin time shall behave as start-of-media and the end time shall behave as end-of-media. If the value of temporal fragment interval is changed then there will be no change in the play state unless the interval is changed to period outside of the current play position.
readonly Number playPosition	The play position in number of milliseconds since the beginning as denoted by the server (i.e. in relation to NPT 0.0 as described in section 3.6 of [RTSP]) of the media referenced by attribute data when data refers to a single media item. If the play position cannot be determined, the playPosition shall be undefined.
readonly Number playTime	The estimated total duration in milliseconds of the media referenced by data when data refers to a single media item. If the duration of the media cannot be determined, the playTime shall be undefined.
readonly Number playState	Indication of the current play state as follows: 0 - stopped; user (or script) has stopped playback of the current media, or playback has not yet started. 1 - playing; the current media pointed to by data is currently playing. 2 - paused; the current media pointed to by data has been paused. 3 - connecting; connect to media server, i.e. waiting for connection to media server to be established, upon first connection or after the connection was lost. In addition, DRM rights necessary for playback of protected content are also retrieved during this state. 4 - buffering; the buffer is being filled in order to have sufficient data available to initiate or continue playback. In this state, playback is stalled due to insufficient data in the buffer to continue playback. The player waits until sufficient data has been buffered to continue playback. For video objects, whilst being in this state, the player should show the last completed video frame that was shown before entering this state. This playstate is an intermediate state to reach playState 1 (‘playing’). The OITF should buffer the content in the background whilst in playState 2 (‘paused’). However, this background buffering does not result into a state change to state 4. 5 - finished; the playback of the current media has reached the end of the media. 6 - error; an error occurred during media playback, preventing the current media to start/continue playing.
readonly Number error	Error details; only significant if the value of playState equals 6: 0 - A/V format not supported. 1 - cannot connect to server or connection lost. 2 - unidentified error. 3 – insufficient resources. 4 – content corrupt or invalid. 5 – content not available. 6 – content not available at given position.
readonly Number speed	Play speed relative to real-time as defined by 5.7.1.f.6 of [CEA-2014-A].
Object onPlayStateChange	DOM-0 event handler called when the value of the playState property changes as defined by 5.7.1.f.9 of [CEA-2014-A].

Table 10: Additional Properties of the A/V Control Object when the type attribute refers to video
Property type and name	Property Definition
String width	The width of the area used for rendering the video object. This property is only writable if property `fullScreen` has value `false`. The effect of changes to `width` shall be in accordance with requirement 5.7.1.c of [CEA-2014-A].
String height	The height of the area used for rendering the video object. This property is only writable if property `fullScreen` has value `false`. The effect of changes to `width` shall be in accordance with requirement 5.7.1.c of [CEA-2014-A].
readonly Boolean fullScreen	Indicates whether an object presenting video is in full screen mode or not - as defined in by 5.7.1.g.3 of [CEA-2014-A].
Object onFullScreenChange	DOM-0 event handler called when the value of fullScreen changes as defined in by 5.7.1.g.4 of [CEA-2014-A].
Object onfocus	DOM-0 event handler called when the object gains focus as defined by 5.7.1.g.7 of [CEA-2014-A].
Object onblur	DOM-0 event handler called when the object loses focus as defined by 5.7.1.g.8 of [CEA-2014-A].

Table 11: Methods of the A/V Control Object when the type attribute refers to video or audio
Method signature	Method Definition
Boolean play(Number speed)	Plays the media referenced by data, starting at the current play position denoted by `playPosition`, at the supported speed closest to the value of attribute speed. Negative speeds reverse playback. If no speed is specified, it defaults to 1. A speed of 0 will pause playback. This method shall always return `true`. If the playback reached the beginning of the media at rewind playback speed, then the play state shall be changed to 2 (‘paused’). A play speed event (see section 7.14.3.2 of this specification) shall be generated when the operation has completed, regardless of the new play speed. If the play speed is not changed, the argument of the event shall be set to the previous play speed.
Boolean stop()	Stops playback and resets the `playPosition` to 0 as defined by 5.7.1.f.12 of [CEA-2014-A].
Boolean seek(Number pos)	If `seek()` is called while the player is in state 1 (“playing”), then it sets the current play position (in milliseconds) to the value of pos and may change play state to 4 (‘buffering’). If the player is in state 2 (‘paused’), then the `seek()` method seeks to the new position, but the play state and the rendered image is not changed. If the player is in states 0 (“stopped”), 5 (“finished”) or 6 (“error”), then the new play position shall be retained and shall be used (if possible) as the starting position for playing back the content item indicated by the data property when the `play()` method is called. NOTE: changing the content item resets the play position to the beginning of the new content item. If the player is in states 3 (“connecting”) or 4 (“buffering”) then the `seek()` method seeks to the new play position and may change play state to 3 (“connecting”). If the new playback position is valid, the value of the `playPosition` attribute shall be set to the new value before this method returns. Returns `true` if the method succeeded, and `false` otherwise. A play position event (see section 7.14.3.2 of this specification) will be generated when the operation has completed, regardless of the success of the operation. If the operation fails, the argument of the event shall be set to the previous play position.
Boolean setVolume(Number volume)	Sets the audio volume as defined by 5.7.1.f.14 of [CEA-2014-A]

Table 12: Additional Methods of the A/V Control Object when the type attribute refers to video
Method signature	Method Definition
setFullScreen(Boolean fullscreen)	Sets the object to full screen mode or windowed mode as defined by 5.7.1.g.5 of [CEA-2014-A].
focus()	Sets the input focus to this object as defined by 5.7.1.g.6 of [CEA-2014-A].

In addition to the properties and methods listed above, the following table lists other requirements from CEA-2014-A that shall also apply for the A/V Control object as defined in this section.

Table 13: Additional applicable requirements from CEA-2014
CEA-2014 Requirement	Summary
5.7.1.a.3	Indication of the initial aspect ratio of the video content.
5.7.1.b.3	Access to both video and audio objects by name/id through the `HTMLDocument` interface.
5.7.1.c	Full-screen or windowed mode for video objects.
5.7.1.d	CSS properties that apply to video objects.
5.7.1.e	CSS z-index, opacity and RGBA colour values. NOTE: In this specification, the value of the “`<overlay>`” element is never “none” and hence `z-index` and `opacity` are required to be supported.

7.14.1.1 State diagram for A/V Control objects

The following state transition diagram should be used for an A/V Control object:

Figure 16: State diagram for embedded A/V Control objects (normative)

The following clarifications apply:

A detailed description for all the states in this state diagram is given above in the definition of the playState property.
If the value of the allocationMethod property is DYNAMIC_ALLOCATION the following shall apply:
1. Scarce resources for playback using the A/V Control object, such as the MPEG decoder, are claimed during state 3 (‘connecting’), state 4 (‘buffering’) or during state transitions from state 3 (‘connecting’) to state 4 (‘buffering’), from state 4 (‘buffering’) to state 1 (‘playing’) or from state 0 (‘stopped’) or from state 3 (‘connecting’) to state 2 (‘paused’).
2. If at any point in time during playback the scarce resources are not available anymore, due to a resource conflict, then the play state of the A/V Control object shall be set to 6 (‘error’) with a detailed error code of 3 (‘insufficient resources’).
3. Scarce resources for playback using the A/V Control object shall be released when state 6 (‘error’) or 0 (‘stopped’) or 5 (‘finished’) are reached.
In addition, if the A/V Control object gets destroyed, e.g. because another URL is loaded into the containing window, scarce resources claimed for playback using the A/V Control object shall be released, except in cases described for the optional persist property of A/V Control objects.
When the data attribute and/or the type attribute of the HTMLObjectElement representing the A/V Control object is given a different value, the object shall go to state 0 (‘stopped’).
For playback of DRM protected content, the rights for playback are retrieved during state 3 (‘connecting’).
If the play position reaches the end of the available content the A/V Control object shall be set to state 5 (‘finished’) in addition to generating a playback speed change of zero.
If there is an attempt to play() with a speed in the positive direction (forward or > 0) and there is no content available then the request fails.
If the play position reaches the beginning of the available content the A/V Control object shall be set to state 2 (‘paused’) in addition to generating a playback speed change of zero.
If there is an attempt to play() with a speed in the negative direction (rewind or < 0) and there is no content available then the request fails.
If seek() is performed beyond the available content the request is rejected and the current playout is maintained.
When a A/V Control object stops being rendered as defined in section 10.1 of the HTML5 specification as referenced by [OIPF_WSTVP2] an OITF may release scarce resources allocated for that object. Vice versa, an A/V Control object which is not visible but is still being rendered shall still be decoding video if it is in the playing state and any audio associated with the currently playing media will still be audible. State transitions caused by calls to methods on the A/V Control object, or due to permanent or transient errors, will occur as shown above regardless of the visibility of the object. Section 4.4.4 describes the effect on scarce resources when an A/V Control object is removed from the DOM tree.
NOTE: as implied by the text above, rendering state and visibility are not equivalent. This implies, just to give two examples, that display:none will affect the object state while visibility:hidden will not. When an A/V Control object is destroyed (e.g. by the A/V Control object being garbage collected, or because of a page transition within the application), presentation of streamed audio or video shall be terminated.
When not presenting video, the A/V Control object shall be rendered as an opaque black rectangle.

7.14.1.2 Using an A/V Control object to play streaming content

If an A/V Control object is used to play streamed content using either RTSP or HTTP the OITF then the following holds:

If play(0) is called in state 0 (‘stopped’), the A/V Control object shall automatically go to play state 2 (‘paused’). The necessary resources are secured and no external signalling is performed.
If play(0) is called in the connecting or buffering state, the A/V Control object shall automatically go to play state 2 (‘paused’)
If play() is called in the paused state with an argument other than 0, the A/V Control object shall transition to one of the following states as follows:
1. If there is no connection to the server, the A/V Control object shall transition to the connecting state.
2. If there is a connection to the server but insufficient content is buffered to resume playback immediately, the A/V Control object shall transition to the buffering state.
3. If there is a connection to the server and sufficient content is buffered to resume playback immediately, the A/V Control object shall transition to the playing state.

7.14.1.3 Using an A/V Control object to play downloaded content

If an A/V Control object is used to play content that has been downloaded and stored on the OITF (by using method setSource() as defined in section 7.14.7) then the following holds:

if the download was triggered using registerDownloadURL or the download was triggered using a Content Access Download Descriptor with <TransferType> value “playable_download” as defined in Annex E.1, then:
1. if the play() method is called before sufficient data has been download to initiate playback, then the play state of the A/V Control object shall be set to 6 (‘error’) with a detailed error code of 5 (“content not available”).
if the downloaded content was triggered using a Content Access Download Descriptor with <TransferType> value “full_download” as defined in Annex E.1, then:
1. if the play() method is called whilst the content is still downloading and has not yet successfully completed, then the play state of the A/V Control object shall be set to 6 (‘error’) with a detailed error code of 5 (“content not available”).

7.14.1.4 Using an A/V Control object to play recorded content

If an A/V Control object is used to play content that has been recorded or is being recorded on the OITF (by using method setSource() as defined in section 7.14.7) then the following holds:

if the play() method is called before sufficient data has been recorded to initiate playback, then the play state of the A/V Control object shall be set to 6 (‘error’) with a detailed error code of 5 (“content not available”).

7.14.1.5 Using the A/V Control object to play content fragments

If the OITF indicates support through the <temporalClipping> capability indicator (see section 9.3.22) for playing content fragments then it shall support the Media Fragment URI [Media-Fragments-URI] according to section 8.3.1.

7.14.1.6 User Input and the A/V Control object

If an A/V Control object has input focus:

The OITF shall not block execution of scripts of the document from which the focus was moved to the video object, even when the video is playing full-screen and has input focus.
The OITF shall not handle the VK_OK, VK_PLAY, VK_PAUSE, VK_PLAY_PAUSE, VK_STOP, VK_FAST_FWD, VK_REWIND, VK_NEXT or VK_PREV keys.

7.14.2 Extensions to A/V Control object for playback through Content-Access Streaming Descriptor

As specified in section 4.7.1, an OITF shall support setting up the A/V stream using the information provided by a valid Content Access Streaming Descriptor referred to by the ‘data’ attribute. To this end, the OITF shall fetch the Content Access Streaming Descriptor from the URL provided by the data attribute, after which the descriptor shall be interpreted, resulting in an appropriate <ContentURL> to be selected (e.g. based on which DRM system the OITF supports). The OITF shall then initiate a streaming CoD session to the selected <ContentURL>, after which playback can be started when the play() method is invoked.

The OITF shall pass included DRM-information of the selected content and DRM system ID as part of the <DRMControlInformation> elements of a Content Access Streaming Descriptor to the DRM agent, if it supports a DRM agent with a matching DRMSystemID as per section 9.3.10.

If the Content Access Streaming Descriptor is not valid according to the XML Schema and semantics as defined in Annex E.2, the A/V Control object shall go to playState 6 (i.e. error), with error value 4, which is defined as follows in addition to the error states identified by bullet 5 of [Req. 5.7.1.f] of CEA-2014-A:

4: content corrupt or invalid.

For more information about setting up the A/V stream based on a Content Access Streaming descriptor, see section 4.7.1, section 8 and Annex D.

7.14.3 Extensions to A/V Control object for trickmodes

The following additional properties shall be supported on the audio object and video object defined in section 5.7.1 of [CEA-2014-A].

7.14.3.1 Properties

function onPlaySpeedChanged( Number speed )

The function that is called when the playback speed of the media changes.

The specified function is called with one argument, speed, which is defined as follows:

Number speed – the playback speed of the media at the time the event was dispatched.

The behaviour of the A/V Control object when the end of media (or the end of the currently-available media) is reached is defined in section 7.14.1.

function onPlayPositionChanged( Integer position )

The function that is called when change occurs in the play position of the media due to the use of trick play functions.

The specified function is called with one argument, position, which is defined as follows:

Integer position – the playback position of the media at the time the event was dispatched, measured in milliseconds since the beginning of the referenced media as denoted by the server.

The behaviour of the A/V Control object when the end of media (or the end of the currently-available media) is reached is defined in section 7.14.1.

readonly Number playSpeeds[ ]

Returns an ordered list of playback speeds, expressed as values relative to the normal playback speed (1.0), at which the currently specified A/V content can be played (either through an CEA-2014 audio or video object), or undefined if the supported playback speeds are not (yet) known.

function onPlaySpeedsArrayChanged( )

The function that is called when the playSpeeds array values have changed. An application that makes use of the playSpeeds array needs to read the values of the playSpeeds property again.

readonly String oitfSourceIPAddress

The OITF source IP address for RTSP or HTTP signalling, as well as, the address where the RTSP stream is expected to arrive. The information shall be available in “buffering”, “paused” or “playing” states.

readonly String oitfSourcePortAddress

The OITF Port Address where the RTSP stream is expected to arrive. The information shall be available in “buffering”, “paused” or “playing” states.

Boolean oitfNoRTSPSessionControl

When the oitfNoRTSPSessionControl is set to true then the OITF shall not signal the RTSP messages DESCRIBE, SETUP or TEARDOWN.

String oitfRTSPSessionId

The sessionId to be used by the A/V Control object when signalling RTSP. This property is only applicable when property oitfNoRTSPSessionControl is set to true.

7.14.3.2 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onPlaySpeedChanged	PlaySpeedChanged	Bubbles: No Cancellable: No Context Info: `speed`
onPlayPositionChanged	PlayPositionChanged	Bubbles: No Cancellable: No Context Info: `position`
onPlaySpeedsArrayChanged	PlaySpeedsArrayChanged	Bubbles: No Cancellable: No Context Info: None

Note: the DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving these events during the bubbling or the capturing phase. Applications that use DOM event handlers shall call the addEventListener() method on the A/V Control object itself. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.14.4 Extensions to A/V Control object for playback of selected components

7.14.5 Extensions to A/V Control object for parental rating errors

For parental rating errors during playback of A/V content through the CEA-2014 A/V Control object (as defined in section 5.7.1 of [CEA-2014-A]) an OITF shall support the following intrinsic event properties and corresponding DOM events for the CEA-2014 A/V Control object.

function onParentalRatingChange( String contentID, ParentalRatingCollection ratings, String DRMSystemID, Boolean blocked )

The function that is called whenever the parental rating of the content being played inside the A/V Control object changes.

These events may occur at the start of a new content item, or during playback of a content item (e.g. during playback of A/V streaming content).

The specified function is called with four arguments contentID, ratings, DRMSystemID, and blocked which are defined as follows:

String contentID – the content ID to which the parental rating change applies. If the event is generated by the DRM system, it shall be the unique identifier for that content in the context of the DRM system (i.e. in the case of Marlin BB it is the Marlin contentID, in the case of CSPG-CI+ the value of this field is null). Otherwise, it may be null or undefined.
ParentalRatingCollection ratings – the parental ratings of the currently playing content. The ParentalRatingCollection object is defined in section 7.9.5.
String DRMSystemID – the DRM System ID of the DRM system that generated the event as defined by element DRMSystemID in section 3.3.2 of [OIPF_META2]. The value shall be null if the parental control is not enforced by a particular DRM system.
Boolean blocked – flag indicating whether consumption of the content is blocked by the parental control system as a result of the new parental rating value.

function onParentalRatingError( String contentID, ParentalRatingCollection ratings, String DRMSystemID )

The function that is called when a parental rating error occurs during playback of A/V content inside the A/V Control object, and is triggered whenever one or more parental ratings are discovered and none of them are valid. A valid parental rating is defined as one which uses a parental rating scheme that is supported by the OITF and which has a parental rating value that is supported by the OITF.

The specified function is called with three arguments contentID, ratings, amd DRMSystemID which are defined as follows:

String contentID – the content ID to which the parental rating error applies. If the event is generated by the DRM system, it shall be the unique identifier for that content in the context of the DRM system (i.e. in the case of Marlin BB it is the Marlin contentID, in the case of CSPG-CI+ the value of this field is null). Otherwise, it may be null or undefined.
ParentalRatingCollection ratings – the parental ratings of the currently playing content. The ParentalRatingCollection object is defined in section 7.9.5.
String DRMSystemID – optional argument that specifies the DRM System ID of the DRM system that generated the event as defined by element DRMSystemID in section 3.3.2 of [OIPF_META2]. The value shall be null if the parental control is not enforced by a particular DRM system.

7.14.5.1 Events

For the intrinsic events listed in the table below, a corresponding DOM event shall be generated in the following manner:

Intrinsic event	Corresponding DOM event	DOM Event properties
onParentalRatingChange	ParentalRatingChange	Bubbles: No Cancellable: No Context Info: `contentID`, `ratings`, `DRMSystemID`, `blocked`
onParentalRatingError	ParentalRatingError	Bubbles: No Cancellable: No Context Info: `contentID`, `ratings`, `DRMSystemID`

Note: the above DOM events are directly dispatched to the event target, and will not bubble nor capture. Applications should not rely on receiving these events during the bubbling or the capturing phase. The applications that use DOM event handlers shall call the addEventListener() method on the CEA-2014 A/V embedded object. The third parameter of addEventListener, i.e. “useCapture”, will be ignored.

7.14.6 Extensions to A/V Control object for DRM rights errors

This section shall apply to OITF and/or server devices which have indicated support for DRM protection by providing one or more <drm> elements as specified in section 9.3.10:

For notifying JavaScript about DRM licensing errors during playback of DRM protected A/V content through the CEA-2014 A/V Control object (as defined by as defined in section 5.7.1 of CEA-2014-A) an OITF shall support the following intrinsic event property and corresponding DOM event, for the CEA-2014 A/V Control object.

function onDRMRightsError( Integer errorState, String contentID, String DRMSystemID, String rightsIssuerURL )

The function that is called:

Whenever a rights error occurs for the A/V content (no license, license invalid), which has led to blocking consumption of the content.
Whenever a rights change occurs for the A/V content (license valid), which leads to unblocking the consumption of the content.

This may occur during playback, recording or timeshifting of DRM protected AV content.

The specified function is called with four arguments errorState, contentID, DRMSystemID and rightsIssuerURL which are defined as follows:

Integer errorState – error code detailing the type of error:
- 0: no license, consumption of the content is blocked
- 1: invalid license, consumption of the content is blocked
- 2: valid license, consumption of the content is unblocked
String contentID – the unique identifier of the protected content in the scope of the DRM system that raises the error (i.e. in the case of Marlin BB it is the Marlin contentID, in the case of CSPG-CI+ the value of this field is null).
String DRMSystemID – DRMSystemID as defined by element DRMSystemID in table 9 of section 3.3.2 of [OIPF_META2]. For example, for Marlin, the DRMSystemID value is “urn:dvb:casystemid:19188”.
String rightsIssuerURL – optional element indicating the value of the rightsIssuerURL that can be used to non-silently obtain the rights for the content item currently being played for which this DRM error is generated, in cases whereby the rightsIssuerURL is known. Cases whereby the rightsIssuerURL is known include cases whereby the rightsIssuerURL has been extracted from the MPEG2_TS of the protected content, retrieved from the SD&S discovery record or from the

[3GPPTS24.229]	3GPP, TS 24.229, "IP Multimedia Call Control Protocol based on Session Initiation Protocol (SIP) and Session Description Protocol (SDP) Stage 3 (Release 8)"
[CEA-2014-A]	CEA, CEA-2014-A, "Web-based Protocol Framework for Remote User Interface on UPnP Networks and the Internet (Web4CE)", (including the August 2008 Errata)
[DASH]	ISO/IEC 23009-1, Information technology — Dynamic adaptive streaming over HTTP (DASH) — Part 1: Media presentation description and segment formats
[DLNA]	DLNA Networked Device Interoperability Guidelines, August 2009
[DVB-IPTV]	ETSI TS 102 034 V1.4.1, "DVB-IPTV 1.4: Transport of MPEG-2 TS Based DVB Services over IP Based Networks (and associated XML)"
[EN300468]	ETSI EN 300 468 V1.9.1 (2008-11), "Digital Video Broadcasting (DVB); Specification for Service Information (SI) in DVB systems". Also available as DVB Bluebook A38 (09/2012)
[GIF]	Graphics Interchange Format version 89a, © 1987, 1988, 1989, 1990, CompuServe Incorporated, Columbus, Ohio.
[HTTP]	IETF, RFC 2616, "Hypertext Transfer Protocol -- HTTP/1.1" URL: http://tools.ietf.org/html/rfc2616
[IEC62455]	IEC, IEC 62455, "Internet protocol (IP) and transport stream (TS) based service access"
[IM]	OMA, OMA-TS-SIMPLE_IM-V1_0-20080820-D, "Instant Messaging using SIMPLE"
[ISO639-2]	ISO 639-2:1998 Codes for the representation of names of languages – Part 2: Alpha-3 code
[JFIF]	Hamilton, Eric. JPEG File Interchange Format. Sep 1992. URL: http://www.w3.org/Graphics/JPEG/jfif3.pdf C-Cube Microsystems. Milpitas, CA, USA.
[MEDIA_FRAGMENTS_HTTP]	W3C, "Protocol for Media Fragments 1.0 Resolution in HTTP", W3C Working Draft 1 December 2011
[MPEG-7]	ISO/IEC 15938-5, "Multimedia Content Description Interface - Part 5:Multimedia description schemes", May 2003
[Media-Fragments-URI]	W3C, "Media Fragments URI 1.0", Recommendation 25 September 2012
[PNG]	ISO/IEC, 15948:2004, "Information technology - Computer graphics and image processing - Portable Network Graphics (PNG): Functional specification".
[PRES]	OMA, OMA-TS-Presence_SIMPLE_XDM-V1_1-20080627-A, "Presence XDM Specification"
[RFC1321]	IETF, RFC 1321, "The MD5 Message-Digest Algorithm" URL: http://tools.ietf.org/html/rfc1321
[RFC1918]	IETF, RFC 1918, "Address Allocation for Private Internets" URL: http://tools.ietf.org/html/rfc1918
[RFC2246]	IETF, RFC 2246 "The Transport Layer Security (TLS) Protocol Version 1.0" URL: http://tools.ietf.org/html/rfc2246
[RFC2818]	IETF, RFC 2818, "HTTP over TLS" URL: http://tools.ietf.org/html/rfc2818
[RFC3550]	IETF, RFC 3550, "RTP: A Transport Protocol for Real-Time Applications" URL: http://tools.ietf.org/html/rfc3550
[RFC3840]	IETF, RFC 3840, "Indicating User Agent Capabilities in the Session Initiation Protocol (SIP)" URL: http://tools.ietf.org/html/rfc3841
[RFC3841]	IETF, RFC 3841, "Caller Preferences for the Session Initiation Protocol (SIP)" URL: http://tools.ietf.org/html/rfc3841
[RFC3986]	IETF, RFC 3986, "Uniform Resource Identifier (URI): Generic Syntax" URL: http://tools.ietf.org/html/rfc3986
[RFC4122]	IETF, RFC 4122, "A Universally Unique Identifier (UUID) Namespace" URL: http://tools.ietf.org/html/rfc4122
[RFC4346]	IETF, RFC 4346, "The Transport Layer Security (TLS) Protocol Version 1.1" URL: http://tools.ietf.org/html/rfc4346
[RFC5019]	IETF, RFC 5019, "The Lightweight Online Certificate Status Protocol (OCSP) Profile for High-Volume Environments" URL: http://tools.ietf.org/html/rfc5019
[RFC5246]	IETF, RFC 5246, "The Transport Layer Security (TLS) Protocol Version 1.2" URL: http://tools.ietf.org/html/rfc5246
[RFC5280]	IETF, RFC 5280, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile" URL: http://tools.ietf.org/html/rfc5280
[RFC5746]	IETF, RFC 5746, "Transport Layer Security (TLS) Renegotiation Indication Extension" URL: http://tools.ietf.org/html/rfc5746
[RFC6265]	IETF, RFC 6265, "HTTP State Management Mechanism" URL: http://tools.ietf.org/html/rfc6265
[RFC6454]	IETF, RFC 6454, "The Web Origin Concept" URL: http://tools.ietf.org/html/rfc6454
[RTSP]	IETF, RFC 2326, "Real Time Streaming Protocol (RTSP)" URL: http://tools.ietf.org/html/rfc2326
[TISPAN]	ETSI TS 183 063, "Telecommunications and Internet converged Services and Protocols for Advanced Networking (TISPAN);IMS-based IPTV stage 3 specification"
[TS101154]	ETSI TS 101 154, "Digital Video Broadcasting (DVB);Specification for the use of Video and Audio Coding in Broadcasting Applications based on the MPEG-2 Transport Stream"
[TS102539]	ETSI TS 102 539, "Digital Video Broadcasting (DVB); Carriage of Broadband Content Guide (BCG) information over Internet Protocol (IP)"
[TS102809]	ETSI, TS 102 809 V1.1.1 (2010-01), "Digital Video Broadcasting (DVB); Signalling and carriage of interactive applications and services in hybrid broadcast / broadband environments".
[TS102822-3-1]	ETSI TS 102 822-3-1, "Broadcast and On-line Services: Search, select and rightful use of content on personal storage systems ("TV-Anytime"); Part 3: Metadata; Sub-part 1: Phase 1 - Metadata schemas"
[TS102851]	ETSI TS 102 851, "Digital Video Broadcasting (DVB); Uniform Resource Identifiers (URI) for DVB Systems"
[TS26234]	3GPP, TS 26.234 V9.3.0 (2010-06), Transparent end-to-end Packet-switched Streaming Service (PSS) Protocols and codecs (Release 9)
[Web-Storage]	W3C, "Web Storage", W3C Candidate Recommendation 08 December 2011
[Widgets-APIs]	W3C, "Widget Interface", W3C Candidate Recommendation 13 December 2011
[Widgets-Access]	W3C, "Widget Access Request Policy", W3C Recommendation 7 February 2012.
[Widgets-DigSig]	W3C, "XML Digital Signatures for Widgets", W3C Proposed Recommendation 11 August 2011
[Widgets-Packaging]	W3C, "Widget Packaging and XML Configuration", W3C Recommendation 27 September 2011

[OIPF_ARCH2]	Open IPTV Forum, "Functional Architecture - V2.3", January 2014.
[OIPF_CSP2]	Open IPTV Forum, "Release 2 Specification, Volume 7 - Authentication, Content Protection and Service Protection", V2.3, January 2014.
[OIPF_HAS2]	Open IPTV Forum, "Release 2 Specification, Volume 2a - HTTP Adaptive Streaming", V2.3, January 2014.
[OIPF_MEDIA2]	Open IPTV Forum, "Release 2 Specification, Volume 2 - Media Formats", V2.3, January 2014.
[OIPF_META2]	Open IPTV Forum, "Release 2 Specification, Volume 3 - Content Metadata", V2.3, January 2014.
[OIPF_OVIEW2]	Open IPTV Forum, "Release 2 Specification, Volume 1 - Overview", V2.3, January 2014.
[OIPF_PAE2]	Open IPTV Forum, "Release 2 Specification, Volume 6 - Procedural Application Environment", V2.3, January 2014.
[OIPF_PROT2]	Open IPTV Forum, "Release 2 Specification, Volume 4 - Protocols", V2.3, January 2014.
[OIPF_PROT_EX2]	Open IPTV Forum, "Release 2 Specification, Volume 4a - Examples of IPTV Protocol Sequences", V2.3, January 2014.
[OIPF_REQS2]	Open IPTV Forum, "Service and Platform Requirements", V2.0, December 2008.
[OIPF_WSTVP2]	Open IPTV Forum, "Release 2 Specification, Volume 5a - Web Standards TV Profile", V2.3, January 2014.

[RFC2119]	S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
[TIMING-CONTROL]	W3C, Timing control for script-based animations, W3C Working Draft 21 February 2012
[TS102323]	ETSI TS 102 323, "Digital Video Broadcasting (DVB);Carriage and signalling of TV-Anytime information in DVB transport streams"
[TS102796]	ETSI TS 102 796, "Hybrid Broadcast-Broadband TV"

Descriptor or Element	Summary	Status in this specification
5.4.4.1 ApplicationList	List of applications	Required
5.4.4.2 Application	Name, identifier, type specific descriptor	Required
5.4.4.3 ApplicationIdentifier	2 numbers	Required
5.4.4.4 ApplicationDescriptor	Numerous application attributes	Required The serviceBound element is only applicable to broadcast related applications and shall be ignored for other applications.
5.4.4.5 VisibilityDescriptor	Attribute – indicate if application can be visible to users and/or other applications	Optional. If this element is not present, OITFs shall use a default value of `VISIBLE_ALL`.
5.4.4.6 IconDescriptor	Icon for application	The filename in the IconDescriptor shall be an HTTP URL. Use of the icon signalled here by the OITF is optional.
5.4.4.7 AspectRatio	Preferred aspect ratio for icons	Only relevant if the OITF uses the IconDescriptor.
5.4.4.8 MhpVersion	Specification version	As defined in section section 3.2.3.3.2 of [OIPF_META2].
5.4.4.9 StorageCapabilities	Can the application be stored or cached	Ignored
5.4.4.10 StorageType	Enumeration used in section 5.4.4.9 of [TS102809]	Ignored
5.4.4.11 ApplicationType	Application type	For DAE and PAE applications, the appropriate value from the ApplicationTypeCS scheme from [OIPF_META2] shall be used. This classification scheme is only present in the following versions of the OIPF specifications (2.0, 2.1-void), its removal may have been in error
5.4.4.12 DvbApplicationType	Enumeration for section 5.4.4.11 of [TS102809]	Ignored
5.4.4.13 ApplicationControlCode	Enumeration for 5.4.4.4 of [TS102809]	See below
5.4.4.14 ApplicationSpecificDescriptor	Container	Ignored
5.4.4.15 AbstractIPService	Supports grouping of unbound applications	Only one group shall be signalled
5.4.4.16 ApplicationOfferingType	Used as part of application discovery record	Required
5.4.4.17 ServiceDiscovery	Used as part of application discovery record	Required
5.4.4.18 ApplicationUsageDescriptor	Indicates that an application provides a specific service	Required
5.4.4.19 TransportProtocolDescriptorType	Abstract base type	Required
5.4.4.20 HTTPTransportType	Type for applications accessed by HTTP	Required
5.4.4.21 OCTransportType	Type for applications accessed by DSM-CC object carousel	Required
5.4.4.22 ComponentTagType	Encodes a DVB component tag	Ignored
5.4.4.23 SimpleApplicationLocationDescriptorType	Encodes the location of the start page of an application relative to one of the transport types	Required
5.4.4.24 SimpleApplicationBoundaryDescriptorType	Encodes an application boundary	Required
FLUTESessionDescriptor as defined by Annex B.6 of [OIPF_META2]	Support for distributing applications through multicast	shall be supported if OITFs support FLUTE.

Abstract

Contents

Figures

Tables

Introduction

1. Scope

2. References

2.1 Normative references

2.2 OIPF references

2.3 Informative references

3. Conventions and Terminology

3.1 Conventions

3.2 Terminology

3.2.1 Definitions

3.2.2 Abbreviations

4. DAE Overview

4.1 Architecture of DAE

4.2 Gateway Discovery and Control

4.3 Application Definition

4.3.1 Similarities between applications and traditional web pages

4.3.2 Differences between applications and traditional web pages

4.3.3 The application tree

4.3.4 The application display model

4.3.4.1 Manipulating an application’s DOM Window object

4.3.5 The security model

4.3.6 Inheritance of permissions

4.3.7 Privileged application APIs

4.3.7.1 Compromising the security

4.3.8 Active applications list

4.3.9 Widgets

4.3.10 Origin for Broadcast-delivered Documents

4.4 Resource Management

4.4.1 Application lifecycle issues

4.4.2 Caching of application files

4.4.3 Memory usage

4.4.4 Instantiating embedded objects and claiming scarce system resources

4.4.5 Media control

4.4.6 Use of the display

4.4.7 Cross-application event handling

4.4.7.1 Behaviour of the BACK key

4.4.8 Tuner resources

4.5 Parental access control

4.6 Content Download

4.6.1 Download manager

4.6.2 Content Access Download Descriptor

4.6.3 Triggering a download

4.6.3.1 Using the registerDownload() method

4.6.3.2 Using the registerDownloadURL() method

4.6.3.3 Using the optional registerDownloadFromCRID() method

4.6.3.4 General behaviour regarding triggering a download

4.6.4 Download protocol(s)

4.7 Streaming CoD

4.7.1 Unicast streaming

4.7.1.1 HTTP Adaptive Streaming

4.7.1.2 Multicast streaming

4.8 Scheduled Content

4.8.1 Conveyance of channel list

4.8.1.1 Method 1: JavaScript method “getChannelConfig()”

4.8.1.2 Method 2: HTTP POST message

4.8.2 Conveyance of channel list and list of scheduled recordings

4.9 DLNA RUI Remote Control Function

4.9.1 Interfaces used by the DLNA RUI Remote Control Function

4.10 Power Consumption

4.10.1 DAE application wake-up support

4.10.1.1 Single DAE application wakeup

4.10.1.2 OITF wakeup

4.10.2 OITF hibernate support

4.10.3 State diagram for the power state

4.11 Display Model

5. DAE Application Model

5.1 Application Lifecycle

5.1.1 Creating a new application

5.1.1.1 General

5.1.1.2 Broadcast-independent applications

5.1.1.3 Applications started through an OITF-specific user interface

5.1.1.4 Using the Application.createApplication() method

5.1.1.5 CE-HTML third party notifications

5.1.1.6 Starting applications from SD&S Signalling

5.1.1.7 Applications started by the DRM agent

5.1.1.8 Applications provided by the AG through the remote UI