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"
  • Verimatrix: "viewright_web"
appId Optional String Unique ID of 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 key file in 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 valid format.
507 It cannot get the valid time information.
599 It's 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 key file in 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 valid format.
507 It cannot get the valid time information.
599 It's 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 key file in 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 valid format.
507 It cannot get the valid time information.
599 It's 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 message 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 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"
  • Verimatrix: "json"
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"
  • Verimatrix: "0x5601"

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.
Unique ID of 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 key file in 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 valid format.
507 It cannot get the valid time information.
599 It's 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 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);
        });
}

Example - Verimatrix

var msgId;
 
// Message format for Verimatrix
var msg = '{"company_name":"Verimatrix", "vcas_boot_address":"public-ott.verimatrix.com"}';
  
// Message type for Verimatrix
var msgType = "json";
  
// Unique ID of DRM system
var drmSystemId = "0x5601";
  
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 Verimatrix type.
            console.log("sendDrmMessage succeeded");
        },
        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 rights or operates an appropriate action such as displaying error to 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)

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 key file in 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 valid format.
507 It cannot get the valid time information.
599 It's 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