The application/oipfDrmAgent embedded object
Support in HbbTV
Available since: HbbTV 1.0 (ETSI TS 102 796 V1.1.1, OIPF DAE V1.1)
If the DRM feature is supported or if the terminal supports CI Plus then this is mandatory except as follows:
– The canRecordContent() method is mandatory only if either or both of the preceding conditions apply and also the PVR feature is supported.
– The onDRMSystemStatusChange property and the DRMSystemStatus method are not included.
The DRMSystemID argument for the sendDRMMessage() method shall be specified and shall not be null.
If the DRM feature is supported (even if with only one DRM system) or if the terminal supports CI Plus then the extensions defined in clause A.2.27 shall be supported.
Comment
Security: Trusted
This object shall be extended with the following additional method.
| Boolean setActiveDRM( String DRMSystemID ) | ||
| Description | Sets the DRM system, specified by DRMSystemID, that the terminal shall use with any new requests for playing protected broadband content. Any other DRM systems present in the terminal shall not be used with new requests until this method is called again or the application stops for any reason, even if this means playback of content fails.
If the method is called with the DRMSystemID set to null, the algorithm used by the terminal to determine which DRM to use is outside the scope of the present document. The value true shall always be returned in this case. This shall be the default state if no calls to this method have been made.
A call to this method with DRMSystemID set to “urn:hbbtv:oipfdrm:inactive” shall disable the use of all DRM systems in response to requests to play protected broadband content with the exception that the operation of the EME API is not affected (see clause B.3). Methods on the oipfDrmAgent object may still be called in this state, though depending on the DRM system, some uses of sendDRMMessage may fail. Protected broadband content may still play if suitable keys or licences are provided using the EME API.
If for any reason the terminal is unable to set the specified DRM system as requested, the method shall return false, otherwise it shall return true. | |
| Arguments | DRMSystemID | The DRM system as defined in clause 9.3.10 of the OIPF DAE specification [1] and in Table 9 (“DRMControlInformation Type Semantics”) of the OIPF Metadata specification [18]. |
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
Properties
| 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 and msg 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]. |
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:
| ||||||||||||||||
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 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 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”. | |
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.