MediaDrm Class
Definition
Important
Some information relates to prerelease product that may be substantially modified before it’s released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
MediaDrm can be used to obtain keys for decrypting protected media streams, in
conjunction with android.media.MediaCrypto.
[Android.Runtime.Register("android/media/MediaDrm", DoNotGenerateAcw=true)]
public sealed class MediaDrm : Java.Lang.Object, IDisposable, Java.Interop.IJavaPeerable, Java.Lang.IAutoCloseable[<Android.Runtime.Register("android/media/MediaDrm", DoNotGenerateAcw=true)>]
type MediaDrm = class
inherit Object
interface IAutoCloseable
interface IJavaObject
interface IDisposable
interface IJavaPeerable- Inheritance
- Attributes
- Implements
Remarks
MediaDrm can be used to obtain keys for decrypting protected media streams, in conjunction with android.media.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.
<img src="../../../images/mediadrm_overview.png" alt="MediaDrm Overview diagram" border="0" />
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:
<img src="../../../images/mediadrm_decryption_sequence.png" alt="MediaDrm Overview diagram" border="0" />
The app first constructs android.media.MediaExtractor and android.media.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 #isCryptoSchemeSupported can be used to query if a given scheme is supported on the device.
The app calls #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 method to enable the codec to decrypt content.
When the app has constructed android.media.MediaExtractor, android.media.MediaCodec and android.media.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 android.media.MediaDrm.MediaDrmStateException when a method is called on a MediaDrm object that has had an unrecoverable failure in the DRM plugin or security hardware. android.media.MediaDrm.MediaDrmStateException extends java.lang.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 android.media.MediaDrmResetException. To recover, the app must release the MediaDrm object, then create and initialize a new one.
As android.media.MediaDrmResetException and android.media.MediaDrm.MediaDrmStateException both extend java.lang.IllegalStateException, they should be in an earlier catch() block than java.lang.IllegalStateException if handled separately.
"Callbacks"><h3>Callbacks</h3>
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 #setOnEventListener. 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).
Java documentation for android.media.MediaDrm.
Portions of this page are modifications based on work created and shared by the Android Open Source Project and used according to terms described in the Creative Commons 2.5 Attribution License.
Constructors
| MediaDrm(UUID) |
Instantiate a MediaDrm object |
Fields
| EventKeyExpired |
This event type indicates that the licensed usage duration for keys in a session has expired. |
| EventKeyRequired |
Obsolete.
This event type indicates that the app needs to request keys from a license server. |
| EventProvisionRequired |
This event type indicates that the app needs to request a certificate from the provisioning server. |
| EventSessionReclaimed |
Obsolete.
This event indicates that a session opened by the app has been reclaimed by the resource manager. |
| EventVendorDefined |
Obsolete.
This event may indicate some specific vendor-defined condition, see your DRM provider documentation for details |
| HdcpLevelUnknown |
Obsolete.
The DRM plugin did not report an HDCP level, or an error occurred accessing it |
| HdcpNoDigitalOutput |
Obsolete.
No digital output, implicitly secure |
| HdcpNone |
Obsolete.
HDCP is not supported on this device, content is unprotected |
| HdcpV1 |
Obsolete.
HDCP version 1. |
| HdcpV2 |
Obsolete.
HDCP version 2. |
| HdcpV21 |
Obsolete.
HDCP version 2. |
| HdcpV22 |
Obsolete.
HDCP version 2. |
| HdcpV23 |
Obsolete.
HDCP version 2. |
| KeyTypeOffline |
Obsolete.
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 |
Obsolete.
This key request type specifies that previously saved offline keys should be released. |
| KeyTypeStreaming |
Obsolete.
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. |
| OfflineLicenseStateReleased |
Obsolete.
Offline license is released, the keys have been marked for
release using |
| OfflineLicenseStateUnknown |
Obsolete.
Offline license state is unknown, an error occurred while trying to access it. |
| OfflineLicenseStateUsable |
Obsolete.
Offline license is usable, the keys may be used for decryption. |
| PropertyAlgorithms |
String property name: a comma-separated list of cipher and mac algorithms supported by CryptoSession. |
| PropertyDescription |
String property name: describes the DRM plugin |
| PropertyDeviceUniqueId |
Byte array property name: the device unique identifier is established during device provisioning and provides a means of uniquely identifying each device. |
| PropertyVendor |
String property name: identifies the maker of the DRM plugin |
| PropertyVersion |
String property name: identifies the version of the DRM plugin |
| SecurityLevelHwSecureAll |
Obsolete.
DRM key management, crypto operations, decoding of content and all handling of the media (compressed and uncompressed) is handled within a hardware backed trusted execution environment. |
| SecurityLevelHwSecureCrypto |
Obsolete.
DRM key management and crypto operations are performed within a hardware backed trusted execution environment. |
| SecurityLevelHwSecureDecode |
Obsolete.
DRM key management, crypto operations and decoding of content are performed within a hardware backed trusted execution environment. |
| SecurityLevelSwSecureCrypto |
Obsolete.
DRM key management uses software-based whitebox crypto. |
| SecurityLevelSwSecureDecode |
Obsolete.
DRM key management and decoding use software-based whitebox crypto. |
| SecurityLevelUnknown |
Obsolete.
The DRM plugin did not report a security level, or an error occurred accessing it |
Properties
| Class |
Returns the runtime class of this |
| ConnectedHdcpLevel |
Return the HDCP level negotiated with downstream receivers the device is connected to. |
| Handle |
The handle to the underlying Android instance. (Inherited from Object) |
| JniIdentityHashCode | (Inherited from Object) |
| JniPeerMembers | |
| LogMessages |
Returns recent |
| MaxHdcpLevel |
Return the maximum supported HDCP level. |
| MaxSecurityLevel |
Returns a value that may be passed as a parameter to |
| MaxSessionCount |
Return the maximum number of MediaDrm sessions that may be opened simultaneosly among all MediaDrm instances for the active DRM scheme. |
| Metrics |
Return Metrics data about the current MediaDrm instance. |
| OfflineLicenseKeySetIds |
The keys in an offline license allow protected content to be played even if the device is not connected to a network. |
| OpenSessionCount |
Return the number of MediaDrm sessions that are currently opened simultaneously among all MediaDrm instances for the active DRM scheme. |
| PeerReference | (Inherited from Object) |
| SecureStopIds |
Return a list of all secure stop IDs currently in persistent memory. |
| SecureStops |
Secure stops are a way to enforce limits on the number of concurrent streams per subscriber across devices. |
| SupportedCryptoSchemes | |
| ThresholdClass |
This API supports the Mono for Android infrastructure and is not intended to be used directly from your code. (Inherited from Object) |
| ThresholdType |
This API supports the Mono for Android infrastructure and is not intended to be used directly from your code. (Inherited from Object) |
Methods
| ClearOnEventListener() |
Clear the |
| ClearOnExpirationUpdateListener() |
Clear the |
| ClearOnKeyStatusChangeListener() |
Clear the |
| ClearOnSessionLostStateListener() |
Clear the |
| Clone() |
Creates and returns a copy of this object. (Inherited from Object) |
| Close() |
Releases resources associated with the current session of MediaDrm. |
| CloseSession(Byte[]) |
Close a session on the MediaDrm object that was previously opened
with |
| Dispose() | (Inherited from Object) |
| Dispose(Boolean) | (Inherited from Object) |
| Equals(Object) |
Indicates whether some other object is "equal to" this one. (Inherited from Object) |
| 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 |
| GetHashCode() |
Returns a hash code value for the object. (Inherited from Object) |
| GetKeyRequest(Byte[], Byte[], String, Int32, IDictionary<String,String>) |
A key request/response exchange occurs between the app and a license server to obtain or release keys used to decrypt encrypted content. |
| GetOfflineLicenseState(Byte[]) |
Request the state of an offline license. |
| GetPlaybackComponent(Byte[]) |
Obtain a |
| GetPropertyByteArray(String) |
Read a MediaDrm byte array property value, given the property name string. |
| GetPropertyString(String) |
Read a MediaDrm String property value, given the property name string. |
| GetProvisionRequest() |
A provision request/response exchange occurs between the app and a provisioning server to retrieve a device certificate. |
| GetSecureStop(Byte[]) |
Access a specific secure stop given its secure stop ID. |
| GetSecurityLevel(Byte[]) |
Return the current security level of a session. |
| IsCryptoSchemeSupported(UUID) |
Query if the given scheme identified by its UUID is supported on this device. |
| IsCryptoSchemeSupported(UUID, String) |
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(UUID, String, SecurityLevel) |
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 at the requested security level. |
| JavaFinalize() |
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. (Inherited from Object) |
| Notify() |
Wakes up a single thread that is waiting on this object's monitor. (Inherited from Object) |
| NotifyAll() |
Wakes up all threads that are waiting on this object's monitor. (Inherited from Object) |
| OpenSession() |
Open a new session with the MediaDrm object. |
| OpenSession(Int32) |
Open a new session at a requested security level. |
| ProvideKeyResponse(Byte[], Byte[]) |
A key response is received from the license server by the app, then it is provided to the MediaDrm instance using provideKeyResponse. |
| ProvideProvisionResponse(Byte[]) |
After a provision response is received by the app, it is provided to the MediaDrm instance using this method. |
| QueryKeyStatus(Byte[]) |
Request an informative description of the key status for the session. |
| Release() |
This member is deprecated. |
| ReleaseAllSecureStops() |
Remove all secure stops without requiring a secure stop release message from the license server. |
| ReleaseSecureStops(Byte[]) |
Process the secure stop server response message ssRelease. |
| RemoveAllSecureStops() |
Remove all secure stops without requiring a secure stop release message from the license server. |
| RemoveKeys(Byte[]) |
Remove the current keys from a session. |
| RemoveOfflineLicense(Byte[]) |
Normally offline licenses are released using a key request/response
exchange using |
| RemoveSecureStop(Byte[]) |
Remove a specific secure stop without requiring a secure stop release message from the license server. |
| RequiresSecureDecoder(String) |
Query if the crypto scheme requires the use of a secure decoder to decode data of the given mime type at the default security level. |
| RequiresSecureDecoder(String, Int32) |
Query if the crypto scheme requires the use of a secure decoder to decode data of the given mime type at the given security level. |
| RestoreKeys(Byte[], Byte[]) |
Restore persisted offline keys into a new session. |
| SetHandle(IntPtr, JniHandleOwnership) |
Sets the Handle property. (Inherited from Object) |
| SetOnEventListener(IExecutor, MediaDrm+IOnEventListener) |
Register a callback to be invoked when an event occurs |
| SetOnEventListener(MediaDrm+IOnEventListener) |
Register a callback to be invoked when an event occurs |
| SetOnEventListener(MediaDrm+IOnEventListener, Handler) |
Register a callback to be invoked when an event occurs |
| SetOnExpirationUpdateListener(IExecutor, MediaDrm+IOnExpirationUpdateListener) |
Register a callback to be invoked when a session expiration update occurs. |
| SetOnExpirationUpdateListener(MediaDrm+IOnExpirationUpdateListener, Handler) |
Register a callback to be invoked when a session expiration update occurs. |
| SetOnKeyStatusChangeListener(IExecutor, MediaDrm+IOnKeyStatusChangeListener) |
Register a callback to be invoked when the state of keys in a session change, e. |
| SetOnKeyStatusChangeListener(MediaDrm+IOnKeyStatusChangeListener, Handler) |
Register a callback to be invoked when the state of keys in a session change, e. |
| SetOnSessionLostStateListener(IExecutor, MediaDrm+IOnSessionLostStateListener) |
Register a callback to be invoked when session state has been lost. |
| SetOnSessionLostStateListener(MediaDrm+IOnSessionLostStateListener, Handler) |
Register a callback to be invoked when session state has been lost. |
| SetPropertyByteArray(String, Byte[]) |
Set a MediaDrm byte array property value, given the property name string and new value for the property. |
| SetPropertyString(String, String) |
Set a MediaDrm String property value, given the property name string and new value for the property. |
| ToArray<T>() | (Inherited from Object) |
| ToString() |
Returns a string representation of the object. (Inherited from Object) |
| UnregisterFromRuntime() | (Inherited from Object) |
| Wait() |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>. (Inherited from Object) |
| Wait(Int64) |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>, or until a certain amount of real time has elapsed. (Inherited from Object) |
| Wait(Int64, Int32) |
Causes the current thread to wait until it is awakened, typically by being <em>notified</em> or <em>interrupted</em>, or until a certain amount of real time has elapsed. (Inherited from Object) |
Events
| MediaDrmEvent |
Explicit Interface Implementations
| IJavaPeerable.Disposed() | (Inherited from Object) |
| IJavaPeerable.DisposeUnlessReferenced() | (Inherited from Object) |
| IJavaPeerable.Finalized() | (Inherited from Object) |
| IJavaPeerable.JniManagedPeerState | (Inherited from Object) |
| IJavaPeerable.SetJniIdentityHashCode(Int32) | (Inherited from Object) |
| IJavaPeerable.SetJniManagedPeerState(JniManagedPeerStates) | (Inherited from Object) |
| IJavaPeerable.SetPeerReference(JniObjectReference) | (Inherited from Object) |
Extension Methods
| JavaCast<TResult>(IJavaObject) |
Performs an Android runtime-checked type conversion. |
| JavaCast<TResult>(IJavaObject) | |
| GetJniTypeName(IJavaPeerable) | |