MediaDrm

EVENT_KEY_EXPIRED

int EVENT_KEY_EXPIRED

This event type indicates that the licensed usage duration for keys in a session has expired. The keys are no longer valid.

Constant Value: 3 (0x00000003)

EVENT_KEY_REQUIRED

int EVENT_KEY_REQUIRED

This event type indicates that the app needs to request keys from a license server. The request message data is obtained using getKeyRequest(byte[], byte[], String, int, HashMap).

Constant Value: 2 (0x00000002)

EVENT_PROVISION_REQUIRED

int EVENT_PROVISION_REQUIRED

This constant was deprecated in API level 23.
Handle provisioning via NotProvisionedException instead.

This event type indicates that the app needs to request a certificate from the provisioning server. The request message data is obtained using getProvisionRequest()

Constant Value: 1 (0x00000001)

EVENT_SESSION_RECLAIMED

int EVENT_SESSION_RECLAIMED

This event indicates that a session opened by the app has been reclaimed by the resource manager.

Constant Value: 5 (0x00000005)

EVENT_VENDOR_DEFINED

int EVENT_VENDOR_DEFINED

This event may indicate some specific vendor-defined condition, see your DRM provider documentation for details

Constant Value: 4 (0x00000004)

KEY_TYPE_OFFLINE

int KEY_TYPE_OFFLINE

This key request type specifies that the keys will be for offline use, they will be saved to the device for use when the device is not connected to a network.

Constant Value: 2 (0x00000002)

KEY_TYPE_RELEASE

int KEY_TYPE_RELEASE

This key request type specifies that previously saved offline keys should be released.

Constant Value: 3 (0x00000003)

KEY_TYPE_STREAMING

int KEY_TYPE_STREAMING

This key request type species that the keys will be for online use, they will not be saved to the device for subsequent use when the device is not connected to a network.

Constant Value: 1 (0x00000001)

PROPERTY_ALGORITHMS

String PROPERTY_ALGORITHMS

String property name: a comma-separated list of cipher and mac algorithms supported by CryptoSession. The list may be empty if the DRM engine plugin does not support CryptoSession operations.

Constant Value: "algorithms"

PROPERTY_DESCRIPTION

String PROPERTY_DESCRIPTION

String property name: describes the DRM engine plugin

Constant Value: "description"

PROPERTY_DEVICE_UNIQUE_ID

String PROPERTY_DEVICE_UNIQUE_ID

Byte array property name: the device unique identifier is established during device provisioning and provides a means of uniquely identifying each device.

Constant Value: "deviceUniqueId"

PROPERTY_VENDOR

String PROPERTY_VENDOR

String property name: identifies the maker of the DRM engine plugin

Constant Value: "vendor"

PROPERTY_VERSION

String PROPERTY_VERSION

String property name: identifies the version of the DRM engine plugin

Constant Value: "version"

MediaDrm

MediaDrm (UUID uuid)

Instantiate a MediaDrm object

closeSession

void closeSession (byte[] sessionId)

Close a session on the MediaDrm object that was previously opened with openSession().

getCryptoSession

MediaDrm.CryptoSession getCryptoSession (byte[] sessionId, 
                String cipherAlgorithm, 
                String macAlgorithm)

Obtain a CryptoSession object which can be used to encrypt, decrypt, sign and verify messages or data using the session keys established for the session using methods getKeyRequest(byte[], byte[], String, int, HashMap) and provideKeyResponse(byte[], byte[]) using a session key server.

getKeyRequest

MediaDrm.KeyRequest getKeyRequest (byte[] scope, 
                byte[] init, 
                String mimeType, 
                int keyType, 
                HashMap<String, String> optionalParameters)

A key request/response exchange occurs between the app and a license server to obtain or release keys used to decrypt encrypted content.

getKeyRequest() is used to obtain an opaque key request byte array that is delivered to the license server. The opaque key request byte array is returned in KeyRequest.data. The recommended URL to deliver the key request to is returned in KeyRequest.defaultUrl.

After the app has received the key request response from the server, it should deliver to the response to the DRM engine plugin using the method provideKeyResponse(byte[], byte[]).

getPropertyByteArray

byte[] getPropertyByteArray (String propertyName)

Read a DRM engine plugin byte array property value, given the property name string.

Standard fields names are PROPERTY_DEVICE_UNIQUE_ID

getPropertyString

String getPropertyString (String propertyName)

Read a DRM engine plugin String property value, given the property name string.

Standard fields names are: PROPERTY_VENDOR, PROPERTY_VERSION, PROPERTY_DESCRIPTION, PROPERTY_ALGORITHMS

getProvisionRequest

MediaDrm.ProvisionRequest getProvisionRequest ()

A provision request/response exchange occurs between the app and a provisioning server to retrieve a device certificate. If provisionining is required, the EVENT_PROVISION_REQUIRED event will be sent to the event handler. getProvisionRequest is used to obtain the opaque provision request byte array that should be delivered to the provisioning server. The provision request byte array is returned in ProvisionRequest.data. The recommended URL to deliver the provision request to is returned in ProvisionRequest.defaultUrl.

getSecureStop

byte[] getSecureStop (byte[] ssid)

Access secure stop by secure stop ID.

getSecureStops

List<byte[]> getSecureStops ()

A means of enforcing limits on the number of concurrent streams per subscriber across devices is provided via SecureStop. This is achieved by securely monitoring the lifetime of sessions.

Information from the server related to the current playback session is written to persistent storage on the device when each MediaCrypto object is created.

In the normal case, playback will be completed, the session destroyed and the Secure Stops will be queried. The app queries secure stops and forwards the secure stop message to the server which verifies the signature and notifies the server side database that the session destruction has been confirmed. The persisted record on the client is only removed after positive confirmation that the server received the message using releaseSecureStops().

isCryptoSchemeSupported

boolean isCryptoSchemeSupported (UUID uuid, 
                String mimeType)

Query if the given scheme identified by its UUID is supported on this device, and whether the drm plugin is able to handle the media container format specified by mimeType.

isCryptoSchemeSupported

boolean isCryptoSchemeSupported (UUID uuid)

Query if the given scheme identified by its UUID is supported on this device.

openSession

byte[] openSession ()

Open a new session with the MediaDrm object. A session ID is returned.

provideKeyResponse

byte[] provideKeyResponse (byte[] scope, 
                byte[] response)

A key response is received from the license server by the app, then it is provided to the DRM engine plugin using provideKeyResponse. When the response is for an offline key request, a keySetId is returned that can be used to later restore the keys to a new session with the method restoreKeys(byte[], byte[]). When the response is for a streaming or release request, null is returned.

provideProvisionResponse

void provideProvisionResponse (byte[] response)

After a provision response is received by the app, it is provided to the DRM engine plugin using this method.

queryKeyStatus

HashMap<String, String> queryKeyStatus (byte[] sessionId)

Request an informative description of the key status for the session. The status is in the form of {name, value} pairs. Since DRM license policies vary by vendor, the specific status field names are determined by each DRM vendor. Refer to your DRM provider documentation for definitions of the field names for a particular DRM engine plugin.

release

void release ()

releaseAllSecureStops

void releaseAllSecureStops ()

Remove all secure stops without requiring interaction with the server.

releaseSecureStops

void releaseSecureStops (byte[] ssRelease)

Process the SecureStop server response message ssRelease. After authenticating the message, remove the SecureStops identified in the response.

removeKeys

void removeKeys (byte[] sessionId)

Remove the current keys from a session.

restoreKeys

void restoreKeys (byte[] sessionId, 
                byte[] keySetId)

Restore persisted offline keys into a new session. keySetId identifies the keys to load, obtained from a prior call to provideKeyResponse(byte[], byte[]).

setOnEventListener

void setOnEventListener (MediaDrm.OnEventListener listener)

Register a callback to be invoked when an event occurs

setOnExpirationUpdateListener

void setOnExpirationUpdateListener (MediaDrm.OnExpirationUpdateListener listener, 
                Handler handler)

Register a callback to be invoked when a session expiration update occurs. The app's OnExpirationUpdateListener will be notified when the expiration time of the keys in the session have changed.

setOnKeyStatusChangeListener

void setOnKeyStatusChangeListener (MediaDrm.OnKeyStatusChangeListener listener, 
                Handler handler)

Register a callback to be invoked when the state of keys in a session change, e.g. when a license update occurs or when a license expires.

setPropertyByteArray

void setPropertyByteArray (String propertyName, 
                byte[] value)

Set a DRM engine plugin byte array property value.

setPropertyString

void setPropertyString (String propertyName, 
                String value)

Set a DRM engine plugin String property value.

finalize

void finalize ()

Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. A subclass overrides the finalize method to dispose of system resources or to perform other cleanup.

The general contract of finalize is that it is invoked if and when the Java^TM virtual machine has determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, except as a result of an action taken by the finalization of some other object or class which is ready to be finalized. The finalize method may take any action, including making this object available again to other threads; the usual purpose of finalize, however, is to perform cleanup actions before the object is irrevocably discarded. For example, the finalize method for an object that represents an input/output connection might perform explicit I/O transactions to break the connection before the object is permanently discarded.

The finalize method of class Object performs no special action; it simply returns normally. Subclasses of Object may override this definition.

The Java programming language does not guarantee which thread will invoke the finalize method for any given object. It is guaranteed, however, that the thread that invokes finalize will not be holding any user-visible synchronization locks when finalize is invoked. If an uncaught exception is thrown by the finalize method, the exception is ignored and finalization of that object terminates.

After the finalize method has been invoked for an object, no further action is taken until the Java virtual machine has again determined that there is no longer any means by which this object can be accessed by any thread that has not yet died, including possible actions by other objects or classes which are ready to be finalized, at which point the object may be discarded.

The finalize method is never invoked more than once by a Java virtual machine for any given object.

Any exception thrown by the finalize method causes the finalization of this object to be halted, but is otherwise ignored.