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

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"
}

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"
}

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

load

unload

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);
        });
}

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

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;
}
...

[Action Required: Windows XP OS users] End of Support for 3DES Cipher

DRM

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

Methods

Description

Syntax

Parameters

Call Returns

Error Reference

Example

Return Example

See Also

Description

Syntax

Parameters

Call Returns

Error Reference

Example

Return Example

See Also

Description

Syntax

Parameters

Call Returns

Error Reference

Example

Return Example

See Als

Description

Syntax

Parameters

Call Returns

Error Reference

Example - Widevine

Example - PlayReady

See Also

Description

Syntax

Parameters

Call Returns

Error Reference

Subscription Returns

Example

See Also