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 )
DescriptionSets 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.

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

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 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 eventCorresponding DOM eventDOM Event properties
onDRMMessageResultDRMMessageResultBubbles: No Cancellable: No Context Info: msgID, resultMsg, resultCode
onDRMSystemStatusChangeDRMSystemStatusChangeBubbles: No Cancellable: No Context Info: DRMSystemID
onDRMSystemMessageDRMSystemMessageBubbles: 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.