ExoMediaDrm

Artifact: androidx.media3:media3-exoplayer

View Source

---

Kotlin |Java

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

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

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

Constants

EVENT_KEY_EXPIRED

@UnstableApi
default static final int EVENT_KEY_EXPIRED = 3

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

EVENT_KEY_REQUIRED

@UnstableApi
default static final int EVENT_KEY_REQUIRED = 2

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

EVENT_PROVISION_REQUIRED

@UnstableApi
default static final int EVENT_PROVISION_REQUIRED = 1

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

KEY_TYPE_OFFLINE

@UnstableApi
default static final int KEY_TYPE_OFFLINE = 2

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
default static final int KEY_TYPE_RELEASE = 3

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

KEY_TYPE_STREAMING

@UnstableApi
default static final int KEY_TYPE_STREAMING = 1

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 methods

acquire

abstract void acquire()

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

abstract void closeSession(byte[] sessionId)

Closes a DRM session.

Parameters
byte[] sessionId	The ID of the session to close.

createCryptoConfig

abstract CryptoConfig createCryptoConfig(byte[] sessionId)

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

Parameters
byte[] sessionId	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
abstract int getCryptoType()

Returns the type of CryptoConfig instances returned by createCryptoConfig.

getKeyRequest

abstract ExoMediaDrm.KeyRequest getKeyRequest(
    byte[] scope,
    @Nullable List<DrmInitData.SchemeData> schemeDatas,
    int keyType,
    @Nullable HashMap<String, String> optionalParameters
)

Generates a key request.

Parameters
byte[] scope	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.
@Nullable List<DrmInitData.SchemeData> schemeDatas	If key type is KEY_TYPE_STREAMING or KEY_TYPE_OFFLINE, a list of SchemeData instances extracted from the media. Null otherwise.
int keyType	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.
@Nullable HashMap<String, String> optionalParameters	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

abstract @Nullable PersistableBundle getMetrics()

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

getOfflineLicenseKeySetIds

default List<byte[]> getOfflineLicenseKeySetIds()

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
List<byte[]>	The list of keySetIds for all offline licenses.

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

getPropertyByteArray

abstract byte[] getPropertyByteArray(String propertyName)

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

Parameters
String propertyName	The property name.

Returns
byte[]	The property value.

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

getPropertyString

abstract String getPropertyString(String propertyName)

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

Parameters
String propertyName	The property name.

Returns
String	The property value.

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

getProvisionRequest

abstract ExoMediaDrm.ProvisionRequest getProvisionRequest()

Generates a provisioning request.

Returns
ExoMediaDrm.ProvisionRequest	The generated provisioning request.

openSession

abstract byte[] openSession()

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

Returns
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

abstract @Nullable byte[] provideKeyResponse(byte[] scope, byte[] response)

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

Parameters
byte[] scope	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.
byte[] response	The response data from the server.

Returns
@Nullable 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

abstract void provideProvisionResponse(byte[] response)

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

Parameters
byte[] response	The response data from the server.

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

queryKeyStatus

abstract Map<String, String> queryKeyStatus(byte[] sessionId)

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
byte[] sessionId	The ID of the session being queried.

Returns
Map<String, String>	The key status for the session.

release

abstract void release()

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

removeOfflineLicense

default void removeOfflineLicense(byte[] keySetId)

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
byte[] keySetId	The keySetId of the license to remove.

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

requiresSecureDecoder

abstract boolean requiresSecureDecoder(byte[] sessionId, String mimeType)

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
byte[] sessionId	The ID of the session.
String mimeType	The content MIME type to query.

restoreKeys

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

Restores persisted offline keys into a session.

Parameters
byte[] sessionId	The ID of the session into which the keys will be restored.
byte[] keySetId	The keySetId of the keys to restore, as provided by the call to provideKeyResponse that persisted them.

setOnEventListener

abstract void setOnEventListener(@Nullable ExoMediaDrm.OnEventListener listener)

Sets the listener for DRM events.

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

Parameters
@Nullable ExoMediaDrm.OnEventListener listener	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

abstract void setOnExpirationUpdateListener(
    @Nullable ExoMediaDrm.OnExpirationUpdateListener listener
)

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
@Nullable ExoMediaDrm.OnExpirationUpdateListener listener	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

abstract void setOnKeyStatusChangeListener(
    @Nullable ExoMediaDrm.OnKeyStatusChangeListener listener
)

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
@Nullable ExoMediaDrm.OnKeyStatusChangeListener listener	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

default void setPlayerIdForSession(byte[] sessionId, PlayerId playerId)

Sets the PlayerId of the player using a session.

Parameters
byte[] sessionId	The ID of the session.
PlayerId playerId	The PlayerId of the player using the session.

setPropertyByteArray

abstract void setPropertyByteArray(String propertyName, byte[] value)

Sets the value of a byte array property.

Parameters
String propertyName	The property name.
byte[] value	The value.

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

setPropertyString

abstract void setPropertyString(String propertyName, String value)

Sets the value of a string property.

Parameters
String propertyName	The property name.
String value	The value.

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