Android Guides | Samples

Android.Media.MediaDrm Class

MediaDrm can be used to obtain keys for decrypting protected media streams, in conjunction with MediaCrypto.

See Also: MediaDrm

Syntax

[Android.Runtime.Register("android/media/MediaDrm", DoNotGenerateAcw=true)]
public sealed class MediaDrm : Object

Remarks

MediaDrm can be used to obtain keys for decrypting protected media streams, in conjunction with MediaCrypto. The MediaDrm APIs are designed to support the ISO/IEC 23001-7: Common Encryption standard, but may also be used to implement other encryption schemes.

Encrypted content is prepared using an encryption server and stored in a content library. The encrypted content is streamed or downloaded from the content library to client devices via content servers. Licenses to view the content are obtained from a License Server.

Keys are requested from the license server using a key request. The key response is delivered to the client app, which provides the response to the MediaDrm API.

A Provisioning server may be required to distribute device-unique credentials to the devices.

Enforcing requirements related to the number of devices that may play content simultaneously can be performed either through key renewal or using the secure stop methods.

The following sequence diagram shows the interactions between the objects involved while playing back encrypted content:

The app first constructs MediaExtractor and MediaCodec objects. It accesses the DRM-scheme-identifying UUID, typically from metadata in the content, and uses this UUID to construct an instance of a MediaDrm object that is able to support the DRM scheme required by the content. Crypto schemes are assigned 16 byte UUIDs. The method MediaDrm.IsCryptoSchemeSupported(UUID) can be used to query if a given scheme is supported on the device.

The app calls MediaDrm.OpenSession to generate a sessionId that will uniquely identify the session in subsequent interactions. The app next uses the MediaDrm object to obtain a key request message and send it to the license server, then provide the server's response to the MediaDrm object.

Once the app has a sessionId, it can construct a MediaCrypto object from the UUID and sessionId. The MediaCrypto object is registered with the MediaCodec in the MediaCodec.Configure(MediaFormat,Surface,Surface,Surface) method to enable the codec to decrypt content.

When the app has constructed MediaExtractor, MediaCodec and MediaCrypto objects, it proceeds to pull samples from the extractor and queue them into the decoder. For encrypted content, the samples returned from the extractor remain encrypted, they are only decrypted when the samples are delivered to the decoder.

MediaDrm methods throw NoType:android/media/MediaDrm$MediaDrmStateException;Href=../../../reference/android/media/MediaDrm.MediaDrmStateException.html when a method is called on a MediaDrm object that has had an unrecoverable failure in the DRM plugin or security hardware. NoType:android/media/MediaDrm$MediaDrmStateException;Href=../../../reference/android/media/MediaDrm.MediaDrmStateException.html extends IllegalStateException with the addition of a developer-readable diagnostic information string associated with the exception.

In the event of a mediaserver process crash or restart while a MediaDrm object is active, MediaDrm methods may throw MediaDrmResetException. To recover, the app must release the MediaDrm object, then create and initialize a new one.

As MediaDrmResetException and NoType:android/media/MediaDrm$MediaDrmStateException;Href=../../../reference/android/media/MediaDrm.MediaDrmStateException.html both extend IllegalStateException, they should be in an earlier catch() block than IllegalStateException if handled separately.

Callbacks

Applications should register for informational events in order to be informed of key state updates during playback or streaming. Registration for these events is done via a call to MediaDrm.SetOnEventListener(.IOnEventListener). In order to receive the respective callback associated with this listener, applications are required to create MediaDrm objects on a thread with its own Looper running (main UI thread by default has a Looper running).

[Android Documentation]

Requirements

Namespace: Android.Media
Assembly: Mono.Android (in Mono.Android.dll)
Assembly Versions: 0.0.0.0
Since: Added in API level 18

The members of Android.Media.MediaDrm are listed below.

See Also: Object

Public Constructors

Instantiate a MediaDrm object

Public Fields

const
EventKeyExpiredMediaDrmEventType (3). This event type indicates that the licensed usage duration for keys in a session has expired.
const
EventKeyRequiredMediaDrmEventType (2). This event type indicates that the app needs to request keys from a license server.
const
EventProvisionRequiredMediaDrmEventType (1). This event type indicates that the app needs to request a certificate from the provisioning server.
const
EventVendorDefinedMediaDrmEventType (4). This event may indicate some specific vendor-defined condition, see your DRM provider documentation for details
const
KeyTypeOfflineMediaDrmKeyType (2). 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.
const
KeyTypeReleaseMediaDrmKeyType (3). This key request type specifies that previously saved offline keys should be released.
const
KeyTypeStreamingMediaDrmKeyType (1). 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.
const
PropertyAlgorithmsString. String property name: a comma-separated list of cipher and mac algorithms supported by CryptoSession.
const
PropertyDescriptionString. String property name: describes the DRM engine plugin
const
PropertyDeviceUniqueIdString. Byte array property name: the device unique identifier is established during device provisioning and provides a means of uniquely identifying each device.
const
PropertyVendorString. String property name: identifies the maker of the DRM engine plugin
const
PropertyVersionString. String property name: identifies the version of the DRM engine plugin

Public Properties

[read-only]
SecureStopsIList<Byte[]>. A means of enforcing limits on the number of concurrent streams per subscriber across devices is provided via SecureStop.

Protected Properties

[read-only]
override
ThresholdClassIntPtr. This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.
[read-only]
override
ThresholdTypeType. This API supports the Mono for Android infrastructure and is not intended to be used directly from your code.

Public Methods

CloseSession(Byte[])
Close a session on the MediaDrm object that was previously opened with MediaDrm.OpenSession.
GetCryptoSession(Byte[], String, String) : MediaDrm+CryptoSession
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 MediaDrm.getKeyRequest(byte[], byte[], java.lang.String, int, java.util.HashMap<java.lang.String, java.lang.String>) and MediaDrm.ProvideKeyResponse(Byte[],Byte[]) using a session key server.
GetKeyRequest(Byte[], Byte[], String, Int32, IDictionary<string, string>) : MediaDrm+KeyRequest
GetPropertyByteArray(String) : Byte[]
Read a DRM engine plugin byte array property value, given the property name string.
GetPropertyString(String) : String
Read a DRM engine plugin String property value, given the property name string.
GetProvisionRequest() : MediaDrm+ProvisionRequest
A provision request/response exchange occurs between the app and a provisioning server to retrieve a device certificate.
static
IsCryptoSchemeSupported(UUID) : Boolean
Query if the given scheme identified by its UUID is supported on this device.
static
IsCryptoSchemeSupported(UUID, String) : Boolean
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.
OpenSession() : Byte[]
Open a new session with the MediaDrm object.
ProvideKeyResponse(Byte[], Byte[]) : Byte[]
A key response is received from the license server by the app, then it is provided to the DRM engine plugin using provideKeyResponse.
ProvideProvisionResponse(Byte[])
After a provision response is received by the app, it is provided to the DRM engine plugin using this method.
QueryKeyStatus(Byte[]) : IDictionary<string, string>
Request an informative description of the key status for the session.
Release()
ReleaseSecureStops(Byte[])
Process the SecureStop server response message ssRelease.
RemoveKeys(Byte[])
Remove the current keys from a session.
RestoreKeys(Byte[], Byte[])
Restore persisted offline keys into a new session. keySetId identifies the keys to load, obtained from a prior call to MediaDrm.ProvideKeyResponse(Byte[],Byte[]).
SetOnEventListener(MediaDrm+IOnEventListener)
Register a callback to be invoked when an event occurs
SetPropertyByteArray(String, Byte[])
Set a DRM engine plugin byte array property value.
SetPropertyString(String, String)
Set a DRM engine plugin String property value.

Public Events