DRM

Service URI - luna://com.webos.service.drm

Provides methods for managing DRM clients which handle DRM right information, sending DRM message, and subscribing to DRM rights error information.

Methods

Method

Description

Supported in Emulator

load

Creates a DRM client instance for given type.

No

unload

Removes a DRM client instance and deallocates the resource. 

No

isLoaded

Checks if a DRM client mapping to given application ID exists or not.

No

sendDrmMessage

Sends a DRM message to DRM service, using a message type as defined by the DRM system.

No

getRightsError

Returns DRM rights error information when a DRM licensing error occurs during content playback.

No

For more details on DRM playback, see the Playing DRM Content.

 

Open All


load

Description

Creates a DRM client instance for given type. 

After a DRM client instance is created using this method, other methods provided by the DRM service can be used. 

If different plugins in an application need to access the same DRM client instance, use isLoaded method to check the client ID.
The client ID is randomly generated with mixed characters and numbers in 11 bytes. The last 1 byte is reserved for '0'. (e.g. ISQTUFTWV40, 5DaOSFv82A0)

Post-condition: A unique DRM client instance is created.  

Syntax

load(String drmType[, String appId])

Parameters

Name

Required

Type

Description

drmType

Required

 String

DRM type

  • PlayReady: "playready"

  • Widevine: "widevine"

appId

Optional

String

Unique ID of the application using DRM client

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

 Flag that indicates success/failure of the request.

  • true: Success

  • false: Failure

clientId

Optional

String

Unique ID of DRM client instance

errorCode

Optional

Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText

Optional

String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error Reference

Error Code

Error Message

500

Vendor managed error

501

This API is not supported in the activated DRM.

502

There is no process matching to input clientId.

503

It cannot find a key file in the DRM store.

504

A part of whole parameters is not valid data or format.

505

It's not supporting drmType.

506

The key file is not a valid format.

507

It cannot get the valid time information.

599

It's an unknown error.

Example

var appId = "com.yourdomain.yourapp";
var drmType = "playready";
var clientId;
var isDrmClientLoaded;

var request = webOS.service.request("luna://com.webos.service.drm",
    method: "load",
    parameters: {
        "drmType": drmType,
        "appId": appId
    },
    onSuccess: function (inResponse) {
		clientId = result.clientId;
		isDrmClientLoaded= true;
		console.log("DRM Client is loaded successfully.");
		// To-Do something
		return;
    },
	onFailure: function (inError) {
		console.log("Result: " + JSON.stringify(inResponse));
		console.log("[" + inError.errorCode + "]: " + inError.errorText);
		// To-Do something
		return;
	}
});

Return Example

// Success return
{
    "returnValue":true,
    "clientId":"LE3bZyIZzY"
}

// Failure return - Use wrong DRM type
{
    "returnValue":false,
    "errorCode":505,
    "errorText":"It's not supporting drmType"
}

See Also


unload

Description

Removes a DRM client instance and deallocates the resource. 
After calling this method, the removed DRM client instance cannot be used by any other method.

Syntax

unload(String clientId)

Parameters

Name

Required

Type

Description

clientId

Required

String

Unique ID of DRM client instance

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

 Flag that indicates success/failure of the request.

  • true: Success

  • false: Failure

errorCode

Optional

Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText

Optional

String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error Reference

Error Code

Error Message

500

Vendor managed error

501

This API is not supported in the activated DRM.

502

There is no process matching to input clientId.

503

It cannot find a key file in the DRM store.

504

A part of whole parameters is not valid data or format.

505

It's not supporting drmType.

506

The key file is not a valid format.

507

It cannot get the valid time information.

599

It's an unknown error.

Example

<body onunload="unloadDrmClient()">
...
 
// JavaScript Code
...
function unloadDrmClient() {
    if (isDrmClientLoaded) {
        var request = webOS.service.request("luna://com.webos.service.drm", { 
            method:"unload", 
            parameters: { "clientId": clientId },
            onSuccess: function (result) {
                isDrmClientLoaded = false;
                console.log("DRM Client is unloaded successfully.");
            },
            onFailure: function (result) {
                console.log("[" + result.errorCode + "] " + result.errorText);
                // Do something for error handling
            });
    }
}

Return Example

// Success return
{
    "returnValue":true
}

// Failure return
{
    "returnValue":false,
    "errorCode":502,
    "errorText":"There is no process matching to input clientId"
}

See Also


isLoaded

Description

Checks if a DRM client mapping to given application ID exists or not.
If exists, the client ID is returned. Otherwise, a new DRM client instance for the application ID can be created using the load method.
Since only one DRM client ID can be created per an application ID, this method is used when different plugins with same application ID try to access a DRM client that already exists. 

Syntax

isLoaded([String appId])

Parameters

Name

Required

Type

Description

appId

Optional

String

Unique ID of application

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

 Flag that indicates success/failure of the request.

  • true: Success

  • false: Failure

loadStatus

Optional

Boolean

Flag that indicates whether DRM client instance is loaded or not.

  • true : Loaded

  • false: Not loaded

clientId

Optional

String

Unique ID of loaded DRM client

errorCode

Optional

Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText

Optional

String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error Reference

Error Code

Error Message

500

Vendor managed error

501

This API is not supported in the activated DRM.

502

There is no process matching to input clientId.

503

It cannot find a key file in the DRM store.

504

A part of whole parameters is not valid data or format.

505

It's not supporting drmType.

506

The key file is not a valid format.

507

It cannot get the valid time information.

599

It's an unknown error.

Example

var appId = "com.yourdomain.yourapp";

var request = webOS.service.request("luna://com.webos.service.drm",
    method: "isLoaded",
    parameters: {
        "appId": appId
    },
    onSuccess: function (inResponse) {
        clientId = result.clientId;
        isDrmClientLoaded = result.loadStatus;
		drmType = result.drmType
		console.log("Result: " + JSON.stringify(inResponse));

		if (isDrmCliendLoaded) {
            console.log("DRM Client is already loaded");
			// To-Do something
		} else {
			console.log("DRM Client is not loaded");
			// To-Do something
		}
    },
	onFailure: function (inError) {
		console.log("Failed to get DRM client loading state");
		console.log("[" + inError.errorCode + "]: " + inError.errorText);
		// To-Do something
		return;
	}
});

Return Example

// Success return - already loaded
{
    "returnValue":true, 
    "loadStatus":true, 
    "clientId":"i5wAE5ws1i", 
    "drmType":"playready"
}

// Success return - not loaded
{
    "returnValue": true,
    "loadStatus": false
}

See Als


sendDrmMessage

Description

Sends a DRM message to DRM service, using a message type as defined by the DRM system. DRM service parses the received message and performs the DRM operation. Setting, initialization command, and authentication information are passed within this message.

The format of the message is determined according to the DRM type. The message must comply with the predefined schema. See the samples of messages in msg parameter description.

Pre-condition: For PlayReady, a callback function must be registered using getRightsError to receive an error occurred while the message is being processed by DRM service.
Post-condition: A unique ID for the message is returned.

Syntax

sendDrmMessage(String clientId, String msgType, String msg, String drmSystemId)

Parameters

Name

Required

Type

Description

clientId

Required

String

Unique ID of DRM client instance

msgType

Required

String

A globally unique message type as defined by the DRM system

  • Widevine: "application/widevine+xml"

  • PlayReady: "application/vnd.ms-playready.initiator+xml"

msg

Required

String

The message to be provided to the underlying DRM server formatted according to the message type as indicated by msgType. Valid formats for msg parameter are described here. 

drmSystemId

Required

String

 Unique ID of DRM system

  • PlayReady: "urn:dvb:casystemid:19219"

  • Widevine: "urn:dvb:casystemid:19156"

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

 Flag that indicates success/failure of the request.

  • true: Success

  • false: Failure

msgId

Optional

String

This is used for PlayReady only.

The unique ID of the message which has led to this resulting message

resultCode

Optional

Number

This is used for PlayReady only.

Result Code

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 necessary computations in the time allotted.

3

Unknown MIME Type

sendDrmMessage() failed, because the specified MIME type is unknown for the specified DRM system indicated in the MIME type

4

User Consent Needed

sendDrmMessage() failed because user consent is needed for that action

 resultMsg

Optional

String

This is used for PlayReady only.

DRM system specific result message

For example, the result message is gotten as below.

<?xml version="1.0" encoding="utf-8"?>
<PlayReadyResponse xmlns=
"http://schemas.microsoft.com/
DRM/2007/03/protocols/">

<DRM_RESULT>0</DRM_RESULT> 
<CustomData>CID=abc</CustomData>

</PlayReadyResponse>

errorCode

Optional

Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText

Optional

String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error Reference

Error Code

Error Message

500

Vendor managed error

501

This API is not supported in the activated DRM.

502

There is no process matching to input clientId.

503

It cannot find a key file in the DRM store.

504

A part of whole parameters is not valid data or format.

505

It's not supporting drmType.

506

The key file is not a valid format.

507

It cannot get the valid time information.

599

It's an unknown error.

Example - Widevine

var msgId;
 
// Message format for widevine
// You should keep the order of XML elements in Widevine message as below.
var msg = '<?xml version="1.0" encoding="utf-8"?>
<WidevineCredentialsInfo xmlns="http://www.smarttv-alliance.org/DRM/widevine/2012/protocols/">
    <ContentURL>http://example.org/examplePath/example.vob</ContentURL>
    <DeviceID>ab-cd-ef-01-02-03</DeviceID>
    <StreamID>123abc-ab12-1234-abcd-abc123</StreamID>
    <ClientIP>Sample</ClientIP>
    <DRMServerURL>https://drmserver.example.org/drmserver.cgi</DRMServerURL>
    <DRMAckServerURL>https://ackserver.example.org/ack.cgi</DRMAckServerURL>
    <DRMHeartBeatURL>https://heartbeat.example.org/heartbeat.cgi</DRMHeartBeatURL>
    <DRMHeartBeatPeriod>120</DRMHeartBeatPeriod>
    <UserData>SampleUserData</UserData>
    <Portal>Sample (e.g. company name)</Portal>
    <StoreFront>Sample (e.g. company name)</StoreFront>
    <BandwidthCheckURL>none</BandwidthCheckURL>
    <BandwidthCheckInterval>none</BandwidthCheckInterval>
</WidevineCredentialsInfo >'
 
// Message type for widevine
var msgType = "application/widevine+xml";
 
// Unique ID of DRM system
var drmSystemId = "urn:dvb:casystemid:19156";
 
function sendRightInformation() {
    var request = webOS.service.request("luna://com.webos.service.drm", { 
        method:"sendDrmMessage", 
        parameters: {
            "clientId": clientId,
            "msgType": msgType,
            "msg": msg,
            "drmSystemId": drmSystemId
        }, 
        onSuccess: function (result) {
            // DRM API does not return the msgId, resultCode, resultMsg for Widevine type.
            console.log("sendDrmMessage succeeded");
        },
        onFailure: function (result) {
            console.log("[" + result.errorCode + "] " + result.errorText);
        });
}
You should keep the order of XML elements in the Widevine message as above example.

Example - PlayReady

// Message example for playready
var msg = '<?xml version="1.0" encoding="utf-8"?>
<PlayReadyInitiator xmlns= "http://schemas.microsoft.com/DRM/2007/03/protocols/">
  <LicenseAcquisition>
    <Header>
      <WRMHEADER xmlns= "http://schemas.microsoft.com/DRM/2007/03/PlayReadyHeader" version="4.0.0.0">
        <DATA>
          <PROTECTINFO>
            <KEYLEN>16</KEYLEN>
            <ALGID>AESCTR</ALGID>
          </PROTECTINFO>
          <LA_URL>http://rm.contoso.com/rightsmanager.asmx</LA_URL>
          <KID>lFmb2gxg0Cr5bfEnJXgJeA==</KID>
          <CHECKSUM>P7ORpD2IpA==</CHECKSUM>
        </DATA>
      </WRMHEADER>
    </Header>
    <CustomData>AuthZToken XYZ</CustomData>
  </LicenseAcquisition>
</PlayReadyInitiator>'
 
var msgId;
 
// Message type for PlayReady
var msgType = "application/vnd.ms-playready.initiator+xml"; 
 
// Unique ID of DRM system
var drmSystemId = "urn:dvb:casystemid:19219";
 
function sendRightInformation() {
    request = webOS.service.request("luna://com.webos.service.drm", { 
        method:"sendDrmMessage", 
        parameters: {
            "clientId": clientId,
            "msgType": msgType,
            "msg": msg,
            "drmSystemId": drmSystemId
        }, 
        onSuccess: function (result) {
            msgId = result.msgId;
            var resultCode = result.resultCode;
            var resultMsg = result.resultMgs;
            console.log("Message ID: " + msgId);
            console.log("[" + resultCode + "] " + resultMsg);
             
            if (resultCode != 0){
                // Do Handling DRM message error
            }
        },
        onFailure: function (result) {
            console.log("[" + result.errorCode + "] " + result.errorText);
        });
}

See Also


getRightsError

Description

Returns DRM rights error information when a DRM licensing error occurs during content playback. The DRM rights error information is returned if parameter subscribe is set to 'true'. If an error information is received, the application retries to acquire a DRM right or operates an appropriate action such as displaying an error to the user.

This method is supported in the following DRM type only:

  • PlayReady

Syntax

getRightsError(String clientId, Boolean subscribe)

Parameters

Name

Required

Type

Description

clientId

Required

String

Unique ID of DRM client instance

subscribe

Required

Boolean

Flag that decides whether to subscribe or not.

  • true: Subscribe

  • false: Do not subscribe. Indicates that this method should be called only once. (Default)

When you set this parameter to false, an error (error code: 504) returns currently. To avoid the error, set this parameter to true.

Call Returns

Name

Required

Type

Description

returnValue

Required

Boolean

 Flag that indicates success/failure of the request.

  • true: Success

  • false: Failure

subscribed

Required

Boolean

Flag that indicates whether the subscription is enabled or not.

  • true: Enabled

  • false: Not enabled

errorCode

Optional

Number

errorCode contains the error code if the method fails. The method will return errorCode only if it fails.

See the Error Codes Reference of this method for more details.

errorText

Optional

String

errorText contains the error text if the method fails. The method will return errorText only if it fails.

See the Error Codes Reference of this method for more details.

Error Reference

Error Code

Error Message

500

Vendor managed error

501

This API is not supported in the activated DRM.

502

There is no process matching to input clientId.

503

It cannot find a key file in the DRM store.

504

A part of whole parameters is not valid data or format.

505

It's not supporting drmType.

506

The key file is not a valid format.

507

It cannot get the valid time information.

599

It's an unknown error.

Subscription Returns

Name

Required

Type

Description

errorState

Optional

String

Error code describing the type of error

  • 0: No license

  • 1: Invalid license

contentId

Optional

String

Unique ID of the protected content in the scope of DRM system that raises the error.

drmSystemId

Optional

String

DRM system ID

  • PlayReady: "urn:dvb:casystemid:19219"

rightsIssuerUrl

Optional

String

License server URL

Example

var subscriptionHandler;
...
function subscribeLicensingError() {
    var request = webOS.service.request("luna://com.webos.service.drm", { 
        method:"getRightsError", 
        parameters: {
            "clientId": clientId,
            "subscribe": true
        }, 
        onSuccess: function (result) { // Subscription Callback
            contentId = result.contentId;
            if (contentId == msgId) {
                if ( 0 == result.errorState) {
                    console.log("No license");
                    // Do something for error handling
                }
                else if ( 1 == result.errorState) {
                    console.log("Invalid license");
                    // Do something for error handling
                }
                console.log("DRM System ID: " + result.drmSystemId);
                console.log("License Server URL: " + result.rightIssueUrl);
            }
        },
        onFailure: function (result) {
            console.log("[" + result.errorCode + "] " + result.errorText);
        });
    //Register subscription handler
    subscriptionHandler = request;
}
...

See Also



Navigation