ExoMediaDrm

Artifact: androidx.media3:media3-exoplayer

Kotlin |Java

@UnstableApi
interface ExoMediaDrm

Known direct subclasses

DummyExoMediaDrm, FakeExoMediaDrm, FrameworkMediaDrm

`DummyExoMediaDrm`	An `ExoMediaDrm` that does not support any protection schemes.
`FakeExoMediaDrm`	A fake implementation of `ExoMediaDrm` for use in tests.
`FrameworkMediaDrm`	An `ExoMediaDrm` implementation that wraps the framework `MediaDrm`.

Used to obtain keys for decrypting protected media streams.

Reference counting

Access to an instance is managed by reference counting, where acquire increments the reference count and release decrements it. When the reference count drops to 0 underlying resources are released, and the instance cannot be re-used.

Each new instance has an initial reference count of 1. Hence application code that creates a new instance does not normally need to call acquire, and must call release when the instance is no longer required.

See also
`MediaDrm`

Summary

Nested types
`class ExoMediaDrm.AppManagedProvider : ExoMediaDrm.Provider` Provides an `ExoMediaDrm` instance owned by the app.
`class ExoMediaDrm.KeyRequest` Contains data used to request keys from a license server.
`@Documented @Retention(value = RetentionPolicy.SOURCE) @Target(value = ElementType.TYPE_USE) @IntDef(value = ) annotation ExoMediaDrm.KeyRequest.RequestType` Key request types.
`class ExoMediaDrm.KeyStatus` Defines the status of a key.
`interface ExoMediaDrm.OnEventListener` Called when a DRM event occurs.
`interface ExoMediaDrm.OnExpirationUpdateListener` Called when a session expiration update occurs.
`interface ExoMediaDrm.OnKeyStatusChangeListener` Called when the keys in a DRM session change state.
`interface ExoMediaDrm.Provider` Provider for `ExoMediaDrm` instances.
`class ExoMediaDrm.ProvisionRequest` Contains data to request a certificate from a provisioning server.

Constants
`const Int`	`@UnstableApi EVENT_KEY_EXPIRED = 3` Event indicating that keys have expired, and are no longer usable.
`const Int`	`@UnstableApi EVENT_KEY_REQUIRED = 2` Event indicating that keys need to be requested from the license server.
`const Int`	`@UnstableApi EVENT_PROVISION_REQUIRED = 1` Event indicating that a certificate needs to be requested from the provisioning server.
`const Int`	`@UnstableApi KEY_TYPE_OFFLINE = 2` Key request type for keys that will be used for offline use.
`const Int`	`@UnstableApi KEY_TYPE_RELEASE = 3` Key request type indicating that saved offline keys should be released.
`const Int`	`@UnstableApi KEY_TYPE_STREAMING = 1` Key request type for keys that will be used for online use.

Public functions
`Unit`	`acquire()` Increments the reference count.
`Unit`	`closeSession(sessionId: ByteArray!)` Closes a DRM session.
`CryptoConfig!`	`createCryptoConfig(sessionId: ByteArray!)` Creates a `CryptoConfig` that can be passed to a compatible decoder to allow decryption of protected content using the specified session.
`Int`	`@C.CryptoType getCryptoType()` Returns the `type` of `CryptoConfig` instances returned by `createCryptoConfig`.
`ExoMediaDrm.KeyRequest!`	`getKeyRequest( scope: ByteArray!, schemeDatas: (Mutable)List<DrmInitData.SchemeData!>?, keyType: Int, optionalParameters: HashMap<String!, String!>? )` Generates a key request.
`PersistableBundle?`	`getMetrics()` Returns metrics data for this ExoMediaDrm instance, or `null` if metrics are unavailable.
`(Mutable)List<ByteArray<Byte>!>!`	`getOfflineLicenseKeySetIds()` Returns a list of the `keySetIds` for all offline licenses.
`ByteArray<Byte>!`	`getPropertyByteArray(propertyName: String!)` Returns the value of a byte array property.
`String!`	`getPropertyString(propertyName: String!)` Returns the value of a string property.
`ExoMediaDrm.ProvisionRequest!`	`getProvisionRequest()` Generates a provisioning request.
`ByteArray<Byte>!`	`openSession()` Opens a new DRM session.
`ByteArray<Byte>?`	`provideKeyResponse(scope: ByteArray!, response: ByteArray!)` Provides a key response for the last request to be generated using `getKeyRequest`.
`Unit`	`provideProvisionResponse(response: ByteArray!)` Provides a provisioning response for the last request to be generated using `getProvisionRequest`.
`(Mutable)Map<String!, String!>!`	`queryKeyStatus(sessionId: ByteArray!)` Returns the key status for a given session, as {name, value} pairs.
`Unit`	`release()` Decrements the reference count.
`Unit`	`removeOfflineLicense(keySetId: ByteArray!)` Removes an offline license.
`Boolean`	`requiresSecureDecoder(sessionId: ByteArray!, mimeType: String!)` Returns whether the given session requires use of a secure decoder for the given MIME type.
`Unit`	`restoreKeys(sessionId: ByteArray!, keySetId: ByteArray!)` Restores persisted offline keys into a session.
`Unit`	`setOnEventListener(listener: ExoMediaDrm.OnEventListener?)` Sets the listener for DRM events.
`Unit`	`setOnExpirationUpdateListener( listener: ExoMediaDrm.OnExpirationUpdateListener? )` Sets the listener for session expiration events.
`Unit`	`setOnKeyStatusChangeListener( listener: ExoMediaDrm.OnKeyStatusChangeListener? )` Sets the listener for key status change events.
`Unit`	`setPlayerIdForSession(sessionId: ByteArray!, playerId: PlayerId!)` Sets the `PlayerId` of the player using a session.
`Unit`	`setPropertyByteArray(propertyName: String!, value: ByteArray!)` Sets the value of a byte array property.
`Unit`	`setPropertyString(propertyName: String!, value: String!)` Sets the value of a string property.

Constants

EVENT_KEY_EXPIRED

@UnstableApi
const val EVENT_KEY_EXPIRED = 3: Int

Event indicating that keys have expired, and are no longer usable.

EVENT_KEY_REQUIRED

@UnstableApi
const val EVENT_KEY_REQUIRED = 2: Int

Event indicating that keys need to be requested from the license server.

EVENT_PROVISION_REQUIRED

@UnstableApi
const val EVENT_PROVISION_REQUIRED = 1: Int

Event indicating that a certificate needs to be requested from the provisioning server.

KEY_TYPE_OFFLINE

@UnstableApi
const val KEY_TYPE_OFFLINE = 2: Int

Key request type for keys that will be used for offline use. They will be saved to the device for subsequent use when the device is not connected to a network.

KEY_TYPE_RELEASE

@UnstableApi
const val KEY_TYPE_RELEASE = 3: Int

Key request type indicating that saved offline keys should be released.

KEY_TYPE_STREAMING

@UnstableApi
const val KEY_TYPE_STREAMING = 1: Int

Key request type for keys that will be used for online use. Streaming keys will not be saved to the device for subsequent use when the device is not connected to a network.

Public functions

acquire

fun acquire(): Unit

Increments the reference count. When the caller no longer needs to use the instance, it must call release to decrement the reference count.

A new instance will have an initial reference count of 1, and therefore it is not normally necessary for application code to call this method.

closeSession

fun closeSession(sessionId: ByteArray!): Unit

Closes a DRM session.

Parameters
`sessionId: ByteArray!`	The ID of the session to close.

createCryptoConfig

fun createCryptoConfig(sessionId: ByteArray!): CryptoConfig!

Creates a CryptoConfig that can be passed to a compatible decoder to allow decryption of protected content using the specified session.

Parameters
`sessionId: ByteArray!`	The ID of the session.

Returns
`CryptoConfig!`	A `CryptoConfig` for the given session.

Throws
`android.media.MediaCryptoException`	If a `CryptoConfig` could not be created.

getCryptoType

@C.CryptoType
fun getCryptoType(): Int

Returns the type of CryptoConfig instances returned by createCryptoConfig.

getKeyRequest

fun getKeyRequest(
    scope: ByteArray!,
    schemeDatas: (Mutable)List<DrmInitData.SchemeData!>?,
    keyType: Int,
    optionalParameters: HashMap<String!, String!>?
): ExoMediaDrm.KeyRequest!

Generates a key request.

Parameters
`scope: ByteArray!`	If `keyType` is `KEY_TYPE_STREAMING` or `KEY_TYPE_OFFLINE`, the ID of the session that the keys will be provided to. If `keyType` is `KEY_TYPE_RELEASE`, the `keySetId` of the keys to release.
`schemeDatas: (Mutable)List<DrmInitData.SchemeData!>?`	If key type is `KEY_TYPE_STREAMING` or `KEY_TYPE_OFFLINE`, a list of `SchemeData` instances extracted from the media. Null otherwise.
`keyType: Int`	The type of the request. Either `KEY_TYPE_STREAMING` to acquire keys for streaming, `KEY_TYPE_OFFLINE` to acquire keys for offline usage, or `KEY_TYPE_RELEASE` to release acquired keys. Releasing keys invalidates them for all sessions.
`optionalParameters: HashMap<String!, String!>?`	Are included in the key request message to allow a client application to provide additional message parameters to the server. This may be `null` if no additional parameters are to be sent.

Returns
`ExoMediaDrm.KeyRequest!`	The generated key request.

Throws
`android.media.NotProvisionedException`

See also
`getKeyRequest`

getMetrics

fun getMetrics(): PersistableBundle?

Returns metrics data for this ExoMediaDrm instance, or null if metrics are unavailable.

getOfflineLicenseKeySetIds

fun getOfflineLicenseKeySetIds(): (Mutable)List<ByteArray<Byte>!>!

Returns a list of the keySetIds for all offline licenses.

This is an optional method, and some implementations may only support it on certain Android API levels.

See getOfflineLicenseKeySetIds for more details.

Returns
`(Mutable)List<ByteArray<Byte>!>!`	The list of `keySetIds` for all offline licenses.

Throws
`java.lang.UnsupportedOperationException`	if the implementation doesn't support this method.

getPropertyByteArray

fun getPropertyByteArray(propertyName: String!): ByteArray<Byte>!

Returns the value of a byte array property. For standard property names, see getPropertyByteArray.

Parameters
`propertyName: String!`	The property name.

Returns
`ByteArray<Byte>!`	The property value.

Throws
`java.lang.IllegalArgumentException`	If the underlying DRM plugin does not support the property.

getPropertyString

fun getPropertyString(propertyName: String!): String!

Returns the value of a string property. For standard property names, see getPropertyString.

Parameters
`propertyName: String!`	The property name.

Returns
`String!`	The property value.

Throws
`java.lang.IllegalArgumentException`	If the underlying DRM plugin does not support the property.

getProvisionRequest

fun getProvisionRequest(): ExoMediaDrm.ProvisionRequest!

Generates a provisioning request.

Returns
`ExoMediaDrm.ProvisionRequest!`	The generated provisioning request.

openSession

fun openSession(): ByteArray<Byte>!

Opens a new DRM session. A session ID is returned.

Returns
`ByteArray<Byte>!`	The session ID.

Throws
`android.media.NotProvisionedException`	If provisioning is needed.
`android.media.ResourceBusyException`	If required resources are in use.
`android.media.MediaDrmException`	If the session could not be opened.

provideKeyResponse

fun provideKeyResponse(scope: ByteArray!, response: ByteArray!): ByteArray<Byte>?

Provides a key response for the last request to be generated using getKeyRequest.

Parameters
`scope: ByteArray!`	If the request had type `KEY_TYPE_STREAMING` or `KEY_TYPE_OFFLINE`, the ID of the session to provide the keys to. If `keyType` is `KEY_TYPE_RELEASE`, the `keySetId` of the keys being released.
`response: ByteArray!`	The response data from the server.

Returns
`ByteArray<Byte>?`	If the request had type `KEY_TYPE_OFFLINE`, the `keySetId` for the offline keys. An empty byte array or `null` may be returned for other cases.

Throws
`android.media.NotProvisionedException`	If the response indicates that provisioning is needed.
`android.media.DeniedByServerException`	If the response indicates that the server rejected the request.

provideProvisionResponse

fun provideProvisionResponse(response: ByteArray!): Unit

Provides a provisioning response for the last request to be generated using getProvisionRequest.

Parameters
`response: ByteArray!`	The response data from the server.

Throws
`android.media.DeniedByServerException`	If the response indicates that the server rejected the request.

queryKeyStatus

fun queryKeyStatus(sessionId: ByteArray!): (Mutable)Map<String!, String!>!

Returns the key status for a given session, as {name, value} pairs. Since DRM license policies vary by vendor, the returned entries depend on the DRM plugin being used. Refer to your DRM provider's documentation for more information.

Parameters
`sessionId: ByteArray!`	The ID of the session being queried.

Returns
`(Mutable)Map<String!, String!>!`	The key status for the session.

release

fun release(): Unit

Decrements the reference count. If the reference count drops to 0 underlying resources are released, and the instance cannot be re-used.

removeOfflineLicense

fun removeOfflineLicense(keySetId: ByteArray!): Unit

Removes an offline license.

This method is generally not needed, and should only be used if the preferred approach of generating a license release request by passing KEY_TYPE_RELEASE to getKeyRequest is not possible.

This is an optional method, and some implementations may only support it on certain Android API levels.

See removeOfflineLicense for more details.

Parameters
`keySetId: ByteArray!`	The `keySetId` of the license to remove.

Throws
`java.lang.UnsupportedOperationException`	if the implementation doesn't support this method.

requiresSecureDecoder

fun requiresSecureDecoder(sessionId: ByteArray!, mimeType: String!): Boolean

Returns whether the given session requires use of a secure decoder for the given MIME type. Assumes a license policy that requires the highest level of security supported by the session.

Parameters
`sessionId: ByteArray!`	The ID of the session.
`mimeType: String!`	The content MIME type to query.

restoreKeys

fun restoreKeys(sessionId: ByteArray!, keySetId: ByteArray!): Unit

Restores persisted offline keys into a session.

Parameters
`sessionId: ByteArray!`	The ID of the session into which the keys will be restored.
`keySetId: ByteArray!`	The `keySetId` of the keys to restore, as provided by the call to `provideKeyResponse` that persisted them.

setOnEventListener

fun setOnEventListener(listener: ExoMediaDrm.OnEventListener?): Unit

Sets the listener for DRM events.

This is an optional method, and some implementations may only support it on certain Android API levels.

Parameters
`listener: ExoMediaDrm.OnEventListener?`	The listener to receive events, or `null` to stop receiving events.

Throws
`java.lang.UnsupportedOperationException`	if the implementation doesn't support this method.

See also
`setOnEventListener`

setOnExpirationUpdateListener

fun setOnExpirationUpdateListener(
    listener: ExoMediaDrm.OnExpirationUpdateListener?
): Unit

Sets the listener for session expiration events.

This is an optional method, and some implementations may only support it on certain Android API levels.

Parameters
`listener: ExoMediaDrm.OnExpirationUpdateListener?`	The listener to receive events, or `null` to stop receiving events.

Throws
`java.lang.UnsupportedOperationException`	if the implementation doesn't support this method.

See also
`setOnExpirationUpdateListener`

setOnKeyStatusChangeListener

fun setOnKeyStatusChangeListener(
    listener: ExoMediaDrm.OnKeyStatusChangeListener?
): Unit

Sets the listener for key status change events.

This is an optional method, and some implementations may only support it on certain Android API levels.

Parameters
`listener: ExoMediaDrm.OnKeyStatusChangeListener?`	The listener to receive events, or `null` to stop receiving events.

Throws
`java.lang.UnsupportedOperationException`	if the implementation doesn't support this method.

See also
`setOnKeyStatusChangeListener`

setPlayerIdForSession

fun setPlayerIdForSession(sessionId: ByteArray!, playerId: PlayerId!): Unit

Sets the PlayerId of the player using a session.

Parameters
`sessionId: ByteArray!`	The ID of the session.
`playerId: PlayerId!`	The `PlayerId` of the player using the session.

setPropertyByteArray

fun setPropertyByteArray(propertyName: String!, value: ByteArray!): Unit

Sets the value of a byte array property.

Parameters
`propertyName: String!`	The property name.
`value: ByteArray!`	The value.

Throws
`java.lang.IllegalArgumentException`	If the underlying DRM plugin does not support the property.

setPropertyString

fun setPropertyString(propertyName: String!, value: String!): Unit

Sets the value of a string property.

Parameters
`propertyName: String!`	The property name.
`value: String!`	The value.

Throws
`java.lang.IllegalArgumentException`	If the underlying DRM plugin does not support the property.

ExoMediaDrm

Reference counting

Summary

Nested types

Constants

Public functions

Constants

EVENT_KEY_EXPIRED

EVENT_KEY_REQUIRED

EVENT_PROVISION_REQUIRED

KEY_TYPE_OFFLINE

KEY_TYPE_RELEASE

KEY_TYPE_STREAMING

Public functions

acquire

closeSession

createCryptoConfig

getCryptoType

getKeyRequest

getMetrics

getOfflineLicenseKeySetIds

getPropertyByteArray

getPropertyString

getProvisionRequest

openSession

provideKeyResponse

provideProvisionResponse

queryKeyStatus

release

removeOfflineLicense

requiresSecureDecoder

restoreKeys

setOnEventListener

setOnExpirationUpdateListener

setOnKeyStatusChangeListener

setPlayerIdForSession

setPropertyByteArray

setPropertyString