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 |
Supported in Simulator |
---|---|---|---|
Creates a DRM client instance for given type. |
No |
No |
|
Removes a DRM client instance and deallocates the resource. |
No |
No |
|
Checks if a DRM client mapping to given application ID exists or not. |
No |
No |
|
Sends a DRM message to DRM service, using a message type as defined by the DRM system. |
No |
No |
|
Returns DRM rights error information when a DRM licensing error occurs during content playback. |
No |
No |
-
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