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. For more details on DRM playback, see the DRM Content Playback.

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

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.

Parameters

Name	Required	Type	Description
drmType	Required	String	DRM type PlayReady: "playready"
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
isLoaded

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.

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

load
isLoaded

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.

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 also

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.

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 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 in DRM message.
drmSystemId	Required	String	Unique ID of DRM system PlayReady: "urn:dvb:casystemid:19219"

Call returns

Name Required Type Description

returnValue

Required

Boolean

Flag that indicates success/failure of the request.

true: Success
false: Failure

msgId

Optional

String

Note

This parameter is used for PlayReady only.

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

resultCode

Optional

Number

Note

This parameter 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

Note

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

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

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) Note 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

sendDrmMessage

No Headings

webOS News

LG Electronics Announces Call for Participants for the LG webOS Hackathon 2024

LG Smart TVs Unlock Limitless Entertainment and Personal Growth With New Apps

DRM

load

unload

isLoaded

sendDrmMessage

getRightsError