See Also: MediaDrm
public sealed class MediaDrm : Object
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.
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).
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
|EventKeyExpired||MediaDrmEventType (3). This event type indicates that the licensed usage duration for keys in a session has expired.|
|EventKeyRequired||MediaDrmEventType (2). This event type indicates that the app needs to request keys from a license server.|
|EventProvisionRequired||MediaDrmEventType (1). This event type indicates that the app needs to request a certificate from the provisioning server.|
|EventVendorDefined||MediaDrmEventType (4). This event may indicate some specific vendor-defined condition, see your DRM provider documentation for details|
|KeyTypeOffline||MediaDrmKeyType (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.|
|KeyTypeRelease||MediaDrmKeyType (3). This key request type specifies that previously saved offline keys should be released.|
|KeyTypeStreaming||MediaDrmKeyType (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.|
|PropertyAlgorithms||String. String property name: a comma-separated list of cipher and mac algorithms supported by CryptoSession.|
|PropertyDescription||String. String property name: describes the DRM engine plugin|
|PropertyDeviceUniqueId||String. Byte array property name: the device unique identifier is established during device provisioning and provides a means of uniquely identifying each device.|
|PropertyVendor||String. String property name: identifies the maker of the DRM engine plugin|
|PropertyVersion||String. String property name: identifies the version of the DRM engine plugin|
Close a session on the MediaDrm object that was previously opened with MediaDrm.OpenSession.
|GetCryptoSession(Byte, String, String)|
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>)|
Read a DRM engine plugin byte array property value, given the property name string.
Read a DRM engine plugin String property value, given the property name string.
A provision request/response exchange occurs between the app and a provisioning server to retrieve a device certificate.
Query if the given scheme identified by its UUID is supported on this device.
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.
Open a new session with the MediaDrm object.
A key response is received from the license server by the app, then it is provided to the DRM engine plugin using provideKeyResponse.
After a provision response is received by the app, it is provided to the DRM engine plugin using this method.
Request an informative description of the key status for the session.
Process the SecureStop server response message ssRelease.
Remove the current keys from a session.
Restore persisted offline keys into a new session. keySetId identifies the keys to load, obtained from a prior call to MediaDrm.ProvideKeyResponse(Byte,Byte).
Register a callback to be invoked when an event occurs
Set a DRM engine plugin byte array property value.
Set a DRM engine plugin String property value.