MediaDrm
public
final
class
MediaDrm
extends Object
implements
AutoCloseable
java.lang.Object | |
↳ | android.media.MediaDrm |
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 isCryptoSchemeSupported(UUID)
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 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 MediaDrm.MediaDrmStateException
when a method is called on a MediaDrm object that has had an unrecoverable failure
in the DRM plugin or security hardware.
MediaDrm.MediaDrmStateException
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
MediaDrm.MediaDrmStateException
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
setOnEventListener(OnEventListener)
. 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).
Summary
Nested classes | |
---|---|
class |
MediaDrm.CryptoSession
In addition to supporting decryption of DASH Common Encrypted Media, the MediaDrm APIs provide the ability to securely deliver session keys from an operator's session key server to a client device, based on the factory-installed root of trust, and then perform encrypt, decrypt, sign and verify operations with the session key on arbitrary user data. |
class |
MediaDrm.ErrorCodes
Error codes that may be returned from The description of each error code includes steps that may be taken to resolve the error condition. |
class |
MediaDrm.KeyRequest
Contains the opaque data an app uses to request keys from a license server. |
class |
MediaDrm.KeyStatus
Defines the status of a key. |
class |
MediaDrm.LogMessage
A |
class |
MediaDrm.MediaDrmStateException
Thrown when a general failure occurs during a MediaDrm operation. |
class |
MediaDrm.MetricsConstants
Definitions for the metrics that are reported via the
|
interface |
MediaDrm.OnEventListener
Interface definition for a callback to be invoked when a drm event occurs |
interface |
MediaDrm.OnExpirationUpdateListener
Interface definition for a callback to be invoked when a drm session expiration update occurs |
interface |
MediaDrm.OnKeyStatusChangeListener
Interface definition for a callback to be invoked when the keys in a drm session change states. |
interface |
MediaDrm.OnSessionLostStateListener
Interface definition for a callback to be invoked when the session state has been lost and is now invalid |
class |
MediaDrm.PlaybackComponent
This class contains the Drm session ID and log session ID |
class |
MediaDrm.ProvisionRequest
Contains the opaque data an app uses to request a certificate from a provisioning server |
class |
MediaDrm.SessionException
|
Constants | |
---|---|
int |
EVENT_KEY_EXPIRED
This constant was deprecated
in API level 26.
Use |
int |
EVENT_KEY_REQUIRED
This event type indicates that the app needs to request keys from a license server. |
int |
EVENT_PROVISION_REQUIRED
This constant was deprecated
in API level 23.
Handle provisioning via |
int |
EVENT_SESSION_RECLAIMED
This event indicates that a session opened by the app has been reclaimed by the resource manager. |
int |
EVENT_VENDOR_DEFINED
This event may indicate some specific vendor-defined condition, see your DRM provider documentation for details |
int |
HDCP_LEVEL_UNKNOWN
The DRM plugin did not report an HDCP level, or an error occurred accessing it |
int |
HDCP_NONE
HDCP is not supported on this device, content is unprotected |
int |
HDCP_NO_DIGITAL_OUTPUT
No digital output, implicitly secure |
int |
HDCP_V1
HDCP version 1.0 |
int |
HDCP_V2
HDCP version 2.0 Type 1. |
int |
HDCP_V2_1
HDCP version 2.1 Type 1. |
int |
HDCP_V2_2
HDCP version 2.2 Type 1. |
int |
HDCP_V2_3
HDCP version 2.3 Type 1. |
int |
KEY_TYPE_OFFLINE
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. |
int |
KEY_TYPE_RELEASE
This key request type specifies that previously saved offline keys should be released. |
int |
KEY_TYPE_STREAMING
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. |
int |
OFFLINE_LICENSE_STATE_RELEASED
Offline license is released, the keys have been marked for
release using |
int |
OFFLINE_LICENSE_STATE_UNKNOWN
Offline license state is unknown, an error occurred while trying to access it. |
int |
OFFLINE_LICENSE_STATE_USABLE
Offline license is usable, the keys may be used for decryption. |
String |
PROPERTY_ALGORITHMS
String property name: a comma-separated list of cipher and mac algorithms supported by CryptoSession. |
String |
PROPERTY_DESCRIPTION
String property name: describes the DRM plugin |
String |
PROPERTY_DEVICE_UNIQUE_ID
Byte array property name: the device unique identifier is established during device provisioning and provides a means of uniquely identifying each device. |
String |
PROPERTY_VENDOR
String property name: identifies the maker of the DRM plugin |
String |
PROPERTY_VERSION
String property name: identifies the version of the DRM plugin |
int |
SECURITY_LEVEL_HW_SECURE_ALL
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. |
int |
SECURITY_LEVEL_HW_SECURE_CRYPTO
DRM key management and crypto operations are performed within a hardware backed trusted execution environment. |
int |
SECURITY_LEVEL_HW_SECURE_DECODE
DRM key management, crypto operations and decoding of content are performed within a hardware backed trusted execution environment. |
int |
SECURITY_LEVEL_SW_SECURE_CRYPTO
DRM key management uses software-based whitebox crypto. |
int |
SECURITY_LEVEL_SW_SECURE_DECODE
DRM key management and decoding use software-based whitebox crypto. |
int |
SECURITY_LEVEL_UNKNOWN
The DRM plugin did not report a security level, or an error occurred accessing it |
Public methods | |
---|---|
void
|
clearOnEventListener()
Clear the |
void
|
clearOnExpirationUpdateListener()
Clear the |
void
|
clearOnKeyStatusChangeListener()
Clear the |
void
|
clearOnSessionLostStateListener()
Clear the |
void
|
close()
Releases resources associated with the current session of MediaDrm. |
void
|
closeSession(byte[] sessionId)
Close a session on the MediaDrm object that was previously opened
with |
int
|
getConnectedHdcpLevel()
Return the HDCP level negotiated with downstream receivers the device is connected to. |
MediaDrm.CryptoSession
|
getCryptoSession(byte[] sessionId, String cipherAlgorithm, String macAlgorithm)
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.KeyRequest
|
getKeyRequest(byte[] scope, byte[] init, String mimeType, int keyType, HashMap<String, String> optionalParameters)
A key request/response exchange occurs between the app and a license server to obtain or release keys used to decrypt encrypted content. |
List<MediaDrm.LogMessage>
|
getLogMessages()
Returns recent |
int
|
getMaxHdcpLevel()
Return the maximum supported HDCP level. |
static
int
|
getMaxSecurityLevel()
Returns a value that may be passed as a parameter to |
int
|
getMaxSessionCount()
Return the maximum number of MediaDrm sessions that may be opened simultaneosly among all MediaDrm instances for the active DRM scheme. |
PersistableBundle
|
getMetrics()
Return Metrics data about the current MediaDrm instance. |
List<byte[]>
|
getOfflineLicenseKeySetIds()
The keys in an offline license allow protected content to be played even if the device is not connected to a network. |
int
|
getOfflineLicenseState(byte[] keySetId)
Request the state of an offline license. |
int
|
getOpenSessionCount()
Return the number of MediaDrm sessions that are currently opened simultaneously among all MediaDrm instances for the active DRM scheme. |
MediaDrm.PlaybackComponent
|
getPlaybackComponent(byte[] sessionId)
Obtain a |
byte[]
|
getPropertyByteArray(String propertyName)
Read a MediaDrm byte array property value, given the property name string. |
String
|
getPropertyString(String propertyName)
Read a MediaDrm String property value, given the property name string. |
MediaDrm.ProvisionRequest
|
getProvisionRequest()
A provision request/response exchange occurs between the app and a provisioning server to retrieve a device certificate. |
byte[]
|
getSecureStop(byte[] ssid)
This method was deprecated
in API level 33.
This method is deprecated and may be removed in a future
release. Use renewals by calling |
List<byte[]>
|
getSecureStopIds()
This method was deprecated
in API level 33.
This method is deprecated and may be removed in a future
release. Use renewals by calling |
List<byte[]>
|
getSecureStops()
This method was deprecated
in API level 33.
This method is deprecated and may be removed in a future
release. Secure stops are a way to enforce limits on the number of
concurrent streams per subscriber across devices. They provide secure
monitoring of the lifetime of content decryption keys in MediaDrm
sessions. Limits on concurrent streams may also be enforced by
periodically renewing licenses. This can be achieved by calling
|
int
|
getSecurityLevel(byte[] sessionId)
Return the current security level of a session. |
static
List<UUID>
|
getSupportedCryptoSchemes()
|
static
boolean
|
isCryptoSchemeSupported(UUID uuid, String mimeType)
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. |
static
boolean
|
isCryptoSchemeSupported(UUID uuid, String mimeType, int 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. |
static
boolean
|
isCryptoSchemeSupported(UUID uuid)
Query if the given scheme identified by its UUID is supported on this device. |
byte[]
|
openSession()
Open a new session with the MediaDrm object. |
byte[]
|
openSession(int level)
Open a new session at a requested security level. |
byte[]
|
provideKeyResponse(byte[] scope, byte[] response)
A key response is received from the license server by the app, then it is provided to the MediaDrm instance using provideKeyResponse. |
void
|
provideProvisionResponse(byte[] response)
After a provision response is received by the app, it is provided to the MediaDrm instance using this method. |
HashMap<String, String>
|
queryKeyStatus(byte[] sessionId)
Request an informative description of the key status for the session. |
void
|
release()
This method was deprecated
in API level 28.
replaced by |
void
|
releaseAllSecureStops()
This method was deprecated
in API level 28.
Remove all secure stops using |
void
|
releaseSecureStops(byte[] ssRelease)
This method was deprecated
in API level 33.
This method is deprecated and may be removed in a future
release. Use renewals by calling |
void
|
removeAllSecureStops()
This method was deprecated
in API level 33.
This method is deprecated and may be removed in a future
release. Use renewals by calling |
void
|
removeKeys(byte[] sessionId)
Remove the current keys from a session. |
void
|
removeOfflineLicense(byte[] keySetId)
Normally offline licenses are released using a key request/response
exchange using |
void
|
removeSecureStop(byte[] ssid)
This method was deprecated
in API level 33.
This method is deprecated and may be removed in a future
release. Use renewals by calling |
boolean
|
requiresSecureDecoder(String mime)
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. |
boolean
|
requiresSecureDecoder(String mime, int level)
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. |
void
|
restoreKeys(byte[] sessionId, byte[] keySetId)
Restore persisted offline keys into a new session. |
void
|
setOnEventListener(Executor executor, MediaDrm.OnEventListener listener)
Register a callback to be invoked when an event occurs |
void
|
setOnEventListener(MediaDrm.OnEventListener listener, Handler handler)
Register a callback to be invoked when an event occurs |
void
|
setOnEventListener(MediaDrm.OnEventListener listener)
Register a callback to be invoked when an event occurs |
void
|
setOnExpirationUpdateListener(MediaDrm.OnExpirationUpdateListener listener, Handler handler)
Register a callback to be invoked when a session expiration update occurs. |
void
|
setOnExpirationUpdateListener(Executor executor, MediaDrm.OnExpirationUpdateListener listener)
Register a callback to be invoked when a session expiration update occurs. |
void
|
setOnKeyStatusChangeListener(Executor executor, MediaDrm.OnKeyStatusChangeListener listener)
Register a callback to be invoked when the state of keys in a session change. |
void
|
setOnKeyStatusChangeListener(MediaDrm.OnKeyStatusChangeListener listener, Handler handler)
Register a callback to be invoked when the state of keys in a session change, e.g. when a license update occurs or when a license expires. |
void
|
setOnSessionLostStateListener(Executor executor, MediaDrm.OnSessionLostStateListener listener)
Register a callback to be invoked when session state has been lost. |
void
|
setOnSessionLostStateListener(MediaDrm.OnSessionLostStateListener listener, Handler handler)
Register a callback to be invoked when session state has been lost. |
void
|
setPropertyByteArray(String propertyName, byte[] value)
Set a MediaDrm byte array property value, given the property name string and new value for the property. |
void
|
setPropertyString(String propertyName, String value)
Set a MediaDrm String property value, given the property name string and new value for the property. |
Protected methods | |
---|---|
void
|
finalize()
Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. |
Inherited methods | |||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| |||||||||||||||||||||||
|
Constants
EVENT_KEY_EXPIRED
public static final int EVENT_KEY_EXPIRED
This constant was deprecated
in API level 26.
Use OnKeyStatusChangeListener#onKeyStatusChange
and check for MediaDrm.KeyStatus#STATUS_EXPIRED
in the MediaDrm.KeyStatus
instead.
This event type indicates that the licensed usage duration for keys in a session has expired. The keys are no longer valid.
Constant Value: 3 (0x00000003)
EVENT_KEY_REQUIRED
public static final int EVENT_KEY_REQUIRED
This event type indicates that the app needs to request keys from a license
server. The request message data is obtained using getKeyRequest(byte, byte, String, int, HashMap)
.
Constant Value: 2 (0x00000002)
EVENT_PROVISION_REQUIRED
public static final int EVENT_PROVISION_REQUIRED
This constant was deprecated
in API level 23.
Handle provisioning via NotProvisionedException
instead.
This event type indicates that the app needs to request a certificate from
the provisioning server. The request message data is obtained using
getProvisionRequest()
Constant Value: 1 (0x00000001)
EVENT_SESSION_RECLAIMED
public static final int EVENT_SESSION_RECLAIMED
This event indicates that a session opened by the app has been reclaimed by the resource manager.
Constant Value: 5 (0x00000005)
EVENT_VENDOR_DEFINED
public static final int EVENT_VENDOR_DEFINED
This event may indicate some specific vendor-defined condition, see your DRM provider documentation for details
Constant Value: 4 (0x00000004)
HDCP_LEVEL_UNKNOWN
public static final int HDCP_LEVEL_UNKNOWN
The DRM plugin did not report an HDCP level, or an error occurred accessing it
Constant Value: 0 (0x00000000)
HDCP_NONE
public static final int HDCP_NONE
HDCP is not supported on this device, content is unprotected
Constant Value: 1 (0x00000001)
HDCP_NO_DIGITAL_OUTPUT
public static final int HDCP_NO_DIGITAL_OUTPUT
No digital output, implicitly secure
Constant Value: 2147483647 (0x7fffffff)
HDCP_V1
public static final int HDCP_V1
HDCP version 1.0
Constant Value: 2 (0x00000002)
HDCP_V2
public static final int HDCP_V2
HDCP version 2.0 Type 1.
Constant Value: 3 (0x00000003)
HDCP_V2_1
public static final int HDCP_V2_1
HDCP version 2.1 Type 1.
Constant Value: 4 (0x00000004)
HDCP_V2_2
public static final int HDCP_V2_2
HDCP version 2.2 Type 1.
Constant Value: 5 (0x00000005)
HDCP_V2_3
public static final int HDCP_V2_3
HDCP version 2.3 Type 1.
Constant Value: 6 (0x00000006)
KEY_TYPE_OFFLINE
public static final int KEY_TYPE_OFFLINE
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.
Constant Value: 2 (0x00000002)
KEY_TYPE_RELEASE
public static final int KEY_TYPE_RELEASE
This key request type specifies that previously saved offline keys should be released.
Constant Value: 3 (0x00000003)
KEY_TYPE_STREAMING
public static final int KEY_TYPE_STREAMING
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.
Constant Value: 1 (0x00000001)
OFFLINE_LICENSE_STATE_RELEASED
public static final int OFFLINE_LICENSE_STATE_RELEASED
Offline license is released, the keys have been marked for
release using getKeyRequest(byte, byte, String, int, HashMap)
with KEY_TYPE_RELEASE but
the key response has not been received.
Constant Value: 2 (0x00000002)
OFFLINE_LICENSE_STATE_UNKNOWN
public static final int OFFLINE_LICENSE_STATE_UNKNOWN
Offline license state is unknown, an error occurred while trying to access it.
Constant Value: 0 (0x00000000)
OFFLINE_LICENSE_STATE_USABLE
public static final int OFFLINE_LICENSE_STATE_USABLE
Offline license is usable, the keys may be used for decryption.
Constant Value: 1 (0x00000001)
PROPERTY_ALGORITHMS
public static final String PROPERTY_ALGORITHMS
String property name: a comma-separated list of cipher and mac algorithms supported by CryptoSession. The list may be empty if the DRM plugin does not support CryptoSession operations.
Constant Value: "algorithms"
PROPERTY_DESCRIPTION
public static final String PROPERTY_DESCRIPTION
String property name: describes the DRM plugin
Constant Value: "description"
PROPERTY_DEVICE_UNIQUE_ID
public static final String PROPERTY_DEVICE_UNIQUE_ID
Byte array property name: the device unique identifier is established during device provisioning and provides a means of uniquely identifying each device.
Constant Value: "deviceUniqueId"
PROPERTY_VENDOR
public static final String PROPERTY_VENDOR
String property name: identifies the maker of the DRM plugin
Constant Value: "vendor"
PROPERTY_VERSION
public static final String PROPERTY_VERSION
String property name: identifies the version of the DRM plugin
Constant Value: "version"
SECURITY_LEVEL_HW_SECURE_ALL
public static final int SECURITY_LEVEL_HW_SECURE_ALL
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.
Constant Value: 5 (0x00000005)
SECURITY_LEVEL_HW_SECURE_CRYPTO
public static final int SECURITY_LEVEL_HW_SECURE_CRYPTO
DRM key management and crypto operations are performed within a hardware backed trusted execution environment.
Constant Value: 3 (0x00000003)
SECURITY_LEVEL_HW_SECURE_DECODE
public static final int SECURITY_LEVEL_HW_SECURE_DECODE
DRM key management, crypto operations and decoding of content are performed within a hardware backed trusted execution environment.
Constant Value: 4 (0x00000004)
SECURITY_LEVEL_SW_SECURE_CRYPTO
public static final int SECURITY_LEVEL_SW_SECURE_CRYPTO
DRM key management uses software-based whitebox crypto.
Constant Value: 1 (0x00000001)
SECURITY_LEVEL_SW_SECURE_DECODE
public static final int SECURITY_LEVEL_SW_SECURE_DECODE
DRM key management and decoding use software-based whitebox crypto.
Constant Value: 2 (0x00000002)
SECURITY_LEVEL_UNKNOWN
public static final int SECURITY_LEVEL_UNKNOWN
The DRM plugin did not report a security level, or an error occurred accessing it
Constant Value: 0 (0x00000000)
Public constructors
MediaDrm
public MediaDrm (UUID uuid)
Instantiate a MediaDrm object
Parameters | |
---|---|
uuid |
UUID : The UUID of the crypto scheme.
This value cannot be null . |
Throws | |
---|---|
UnsupportedSchemeException |
if the device does not support the specified scheme UUID |
Public methods
clearOnEventListener
public void clearOnEventListener ()
Clear the OnEventListener
.
clearOnExpirationUpdateListener
public void clearOnExpirationUpdateListener ()
Clear the OnExpirationUpdateListener
.
clearOnKeyStatusChangeListener
public void clearOnKeyStatusChangeListener ()
Clear the OnKeyStatusChangeListener
.
clearOnSessionLostStateListener
public void clearOnSessionLostStateListener ()
Clear the OnSessionLostStateListener
.
close
public void close ()
Releases resources associated with the current session of
MediaDrm. It is considered good practice to call this method when
the MediaDrm
object is no longer needed in your
application. After this method is called, MediaDrm
is no
longer usable since it has lost all of its required resource.
This method was added in API 28. In API versions 18 through 27, release()
should be called instead. There is no need to do anything for API
versions prior to 18.
closeSession
public void closeSession (byte[] sessionId)
Close a session on the MediaDrm object that was previously opened
with openSession()
.
Parameters | |
---|---|
sessionId |
byte : This value cannot be null . |
getConnectedHdcpLevel
public int getConnectedHdcpLevel ()
Return the HDCP level negotiated with downstream receivers the device is connected to. If multiple HDCP-capable displays are simultaneously connected to separate interfaces, this method returns the lowest negotiated level of all interfaces.
This method should only be used for informational purposes, not for enforcing compliance with HDCP requirements. Trusted enforcement of HDCP policies must be handled by the DRM system.
Returns | |
---|---|
int |
the connected HDCP level
Value is HDCP_LEVEL_UNKNOWN , HDCP_NONE , HDCP_V1 , HDCP_V2 , HDCP_V2_1 , HDCP_V2_2 , HDCP_V2_3 , or HDCP_NO_DIGITAL_OUTPUT |
getCryptoSession
public MediaDrm.CryptoSession getCryptoSession (byte[] sessionId, String cipherAlgorithm, String macAlgorithm)
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 getKeyRequest(byte, byte, String, int, HashMap)
and
provideKeyResponse(byte, byte)
using a session key server.
Parameters | |
---|---|
sessionId |
byte : the session ID for the session containing keys
to be used for encrypt, decrypt, sign and/or verify
This value cannot be null . |
cipherAlgorithm |
String : the algorithm to use for encryption and
decryption ciphers. The algorithm string conforms to JCA Standard
Names for Cipher Transforms and is case insensitive. For example
"AES/CBC/NoPadding".
This value cannot be null . |
macAlgorithm |
String : the algorithm to use for sign and verify
The algorithm string conforms to JCA Standard Names for Mac
Algorithms and is case insensitive. For example "HmacSHA256".
The list of supported algorithms for a DRM plugin can be obtained
using the method |
Returns | |
---|---|
MediaDrm.CryptoSession |
getKeyRequest
public MediaDrm.KeyRequest getKeyRequest (byte[] scope, byte[] init, String mimeType, int keyType, HashMap<String, String> optionalParameters)
A key request/response exchange occurs between the app and a license server to obtain or release keys used to decrypt encrypted content.
getKeyRequest() is used to obtain an opaque key request byte array that is delivered to the license server. The opaque key request byte array is returned in KeyRequest.data. The recommended URL to deliver the key request to is returned in KeyRequest.defaultUrl.
After the app has received the key request response from the server,
it should deliver to the response to the MediaDrm instance using the method
provideKeyResponse(byte, byte)
.
Parameters | |
---|---|
scope |
byte : may be a sessionId or a keySetId, depending on the specified keyType.
When the keyType is KEY_TYPE_STREAMING or KEY_TYPE_OFFLINE,
scope should be set to the sessionId the keys will be provided to. When the keyType
is KEY_TYPE_RELEASE, scope should be set to the keySetId of the keys
being released. Releasing keys from a device invalidates them for all sessions.
This value cannot be null . |
init |
byte : container-specific data, its meaning is interpreted based on the
mime type provided in the mimeType parameter. It could contain, for example,
the content ID, key ID or other data obtained from the content metadata that is
required in generating the key request. May be null when keyType is
KEY_TYPE_RELEASE or if the request is a renewal, i.e. not the first key
request for the session. |
mimeType |
String : identifies the mime type of the content. May be null if the
keyType is KEY_TYPE_RELEASE or if the request is a renewal, i.e. not the
first key request for the session. |
keyType |
int : specifes the type of the request. The request may be to acquire
keys for streaming or offline content, or to release previously acquired
keys, which are identified by a keySetId.
Value is KEY_TYPE_STREAMING , KEY_TYPE_OFFLINE , or KEY_TYPE_RELEASE |
optionalParameters |
HashMap : 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 | |
---|---|
MediaDrm.KeyRequest |
This value cannot be null . |
Throws | |
---|---|
NotProvisionedException |
if reprovisioning is needed, due to a problem with the certifcate |
getLogMessages
public List<MediaDrm.LogMessage> getLogMessages ()
Returns recent LogMessages
associated with this MediaDrm
instance.
Returns | |
---|---|
List<MediaDrm.LogMessage> |
This value cannot be null . |
getMaxHdcpLevel
public int getMaxHdcpLevel ()
Return the maximum supported HDCP level. The maximum HDCP level is a constant for a given device, it does not depend on downstream receivers that may be connected. If multiple HDCP-capable interfaces are present, it indicates the highest of the maximum HDCP levels of all interfaces.
Returns | |
---|---|
int |
the maximum supported HDCP level
Value is HDCP_LEVEL_UNKNOWN , HDCP_NONE , HDCP_V1 , HDCP_V2 , HDCP_V2_1 , HDCP_V2_2 , HDCP_V2_3 , or HDCP_NO_DIGITAL_OUTPUT |
getMaxSecurityLevel
public static int getMaxSecurityLevel ()
Returns a value that may be passed as a parameter to openSession(int)
requesting that the session be opened at the maximum security level of
the device.
This security level is only valid for the application running on the physical Android
device (e.g. Context.DEVICE_ID_DEFAULT
). While running on a
VirtualDevice
the maximum supported security level
might be different.
Returns | |
---|---|
int |
getMaxSessionCount
public int getMaxSessionCount ()
Return the maximum number of MediaDrm sessions that may be opened simultaneosly among all MediaDrm instances for the active DRM scheme. The maximum number of sessions is not affected by any sessions that may have already been opened.
Returns | |
---|---|
int |
maximum sessions. |
getMetrics
public PersistableBundle getMetrics ()
Return Metrics data about the current MediaDrm instance.
Returns | |
---|---|
PersistableBundle |
a PersistableBundle containing the set of attributes and values
available for this instance of MediaDrm.
The attributes are described in MetricsConstants .
Additional vendor-specific fields may also be present in
the return value. |
getOfflineLicenseKeySetIds
public List<byte[]> getOfflineLicenseKeySetIds ()
The keys in an offline license allow protected content to be played even if the device is not connected to a network. Offline licenses are stored on the device after a key request/response exchange when the key request KeyType is OFFLINE. Normally each app is responsible for keeping track of the keySetIds it has created. If an app loses the keySetId for any stored licenses that it created, however, it must be able to recover the stored keySetIds so those licenses can be removed when they expire or when the app is uninstalled.
This method returns a list of the keySetIds for all offline licenses.
The offline license keySetId may be used to query the status of an
offline license with getOfflineLicenseState(byte)
or remove it with
removeOfflineLicense(byte)
.
Returns | |
---|---|
List<byte[]> |
a list of offline license keySetIds
This value cannot be null . |
getOfflineLicenseState
public int getOfflineLicenseState (byte[] keySetId)
Request the state of an offline license. An offline license may be usable
or inactive. The keys in a usable offline license are available for
decryption. When the offline license state is inactive, the keys have
been marked for release using getKeyRequest(byte, byte, String, int, HashMap)
with
KEY_TYPE_RELEASE but the key response has not been received. The keys in
an inactive offline license are not usable for decryption.
Parameters | |
---|---|
keySetId |
byte : selects the offline license
This value cannot be null . |
Returns | |
---|---|
int |
the offline license state
Value is OFFLINE_LICENSE_STATE_UNKNOWN , OFFLINE_LICENSE_STATE_USABLE , or OFFLINE_LICENSE_STATE_RELEASED |
Throws | |
---|---|
IllegalArgumentException |
if the keySetId does not refer to an offline license. |
getOpenSessionCount
public int getOpenSessionCount ()
Return the number of MediaDrm sessions that are currently opened simultaneously among all MediaDrm instances for the active DRM scheme.
Returns | |
---|---|
int |
the number of open sessions. |
getPlaybackComponent
public MediaDrm.PlaybackComponent getPlaybackComponent (byte[] sessionId)
Obtain a PlaybackComponent
associated with a DRM session.
Call PlaybackComponent#setLogSessionId(LogSessionId)
on
the returned object to associate a playback session with the DRM session.
Parameters | |
---|---|
sessionId |
byte : a DRM session ID obtained from openSession()
This value cannot be null . |
Returns | |
---|---|
MediaDrm.PlaybackComponent |
a PlaybackComponent associated with the session,
or null if the session is closed or does not exist. |
See also:
getPropertyByteArray
public byte[] getPropertyByteArray (String propertyName)
Read a MediaDrm byte array property value, given the property name string.
Standard fields names are PROPERTY_DEVICE_UNIQUE_ID
Parameters | |
---|---|
propertyName |
String |
Returns | |
---|---|
byte[] |
This value cannot be null . |
getPropertyString
public String getPropertyString (String propertyName)
Read a MediaDrm String property value, given the property name string.
Standard fields names are:
PROPERTY_VENDOR
, PROPERTY_VERSION
,
PROPERTY_DESCRIPTION
, PROPERTY_ALGORITHMS
Parameters | |
---|---|
propertyName |
String : This value cannot be null . |
Returns | |
---|---|
String |
This value cannot be null . |
getProvisionRequest
public MediaDrm.ProvisionRequest getProvisionRequest ()
A provision request/response exchange occurs between the app and a provisioning server to retrieve a device certificate. If provisionining is required, the EVENT_PROVISION_REQUIRED event will be sent to the event handler. getProvisionRequest is used to obtain the opaque provision request byte array that should be delivered to the provisioning server. The provision request byte array is returned in ProvisionRequest.data. The recommended URL to deliver the provision request to is returned in ProvisionRequest.defaultUrl.
Returns | |
---|---|
MediaDrm.ProvisionRequest |
This value cannot be null . |
getSecureStop
public byte[] getSecureStop (byte[] ssid)
This method was deprecated
in API level 33.
This method is deprecated and may be removed in a future
release. Use renewals by calling getKeyRequest(byte, byte, String, int, HashMap)
to track
concurrent playback. See additional information in
getSecureStops()
Access a specific secure stop given its secure stop ID. Each secure stop has a unique ID.
Parameters | |
---|---|
ssid |
byte : the ID of the secure stop to return
This value cannot be null . |
Returns | |
---|---|
byte[] |
the secure stop identified by ssid
This value cannot be null . |
getSecureStopIds
public List<byte[]> getSecureStopIds ()
This method was deprecated
in API level 33.
This method is deprecated and may be removed in a future
release. Use renewals by calling getKeyRequest(byte, byte, String, int, HashMap)
to track
concurrent playback. See additional information in
getSecureStops()
Return a list of all secure stop IDs currently in persistent memory. The secure stop ID can be used to access or remove the corresponding secure stop.
Returns | |
---|---|
List<byte[]> |
a list of secure stop IDs
This value cannot be null . |
getSecureStops
public List<byte[]> getSecureStops ()
This method was deprecated
in API level 33.
This method is deprecated and may be removed in a future
release. Secure stops are a way to enforce limits on the number of
concurrent streams per subscriber across devices. They provide secure
monitoring of the lifetime of content decryption keys in MediaDrm
sessions. Limits on concurrent streams may also be enforced by
periodically renewing licenses. This can be achieved by calling
getKeyRequest(byte, byte, String, int, HashMap)
to initiate a renewal. MediaDrm users should
transition away from secure stops to periodic renewals.
Secure stops are a way to enforce limits on the number of concurrent streams per subscriber across devices. They provide secure monitoring of the lifetime of content decryption keys in MediaDrm sessions.
A secure stop is written to secure persistent memory when keys are loaded into a MediaDrm session. The secure stop state indicates that the keys are available for use. When playback completes and the keys are removed or the session is destroyed, the secure stop state is updated to indicate that keys are no longer usable.
After playback, the app can query the secure stop and send it in a
message to the license server confirming that the keys are no longer
active. The license server returns a secure stop release response
message to the app which then deletes the secure stop from persistent
memory using releaseSecureStops(byte)
.
Each secure stop has a unique ID that can be used to identify it during enumeration, access and removal.
Returns | |
---|---|
List<byte[]> |
a list of all secure stops from secure persistent memory
This value cannot be null . |
getSecurityLevel
public int getSecurityLevel (byte[] sessionId)
Return the current security level of a session. A session has an initial
security level determined by the robustness of the DRM system's
implementation on the device. The security level may be changed at the
time a session is opened using openSession()
.
Parameters | |
---|---|
sessionId |
byte : the session to query.
This value cannot be |
Returns | |
---|---|
int |
the security level of the session
Value is SECURITY_LEVEL_UNKNOWN , SECURITY_LEVEL_SW_SECURE_CRYPTO , SECURITY_LEVEL_SW_SECURE_DECODE , SECURITY_LEVEL_HW_SECURE_CRYPTO , SECURITY_LEVEL_HW_SECURE_DECODE , or SECURITY_LEVEL_HW_SECURE_ALL |
getSupportedCryptoSchemes
public static List<UUID> getSupportedCryptoSchemes ()
Returns | |
---|---|
List<UUID> |
list of crypto schemes (as UUID s) for which
isCryptoSchemeSupported(java.util.UUID) returns true; each UUID
can be used as input to create MediaDrm objects via MediaDrm(java.util.UUID) .
This value cannot be null . |
isCryptoSchemeSupported
public static boolean isCryptoSchemeSupported (UUID uuid, String mimeType)
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.
Parameters | |
---|---|
uuid |
UUID : The UUID of the crypto scheme.
This value cannot be null . |
mimeType |
String : The MIME type of the media container, e.g. "video/mp4"
or "video/webm"
This value cannot be null . |
Returns | |
---|---|
boolean |
isCryptoSchemeSupported
public static boolean isCryptoSchemeSupported (UUID uuid, String mimeType, int 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.
Calling this method while the application is running on the physical Android device or a
VirtualDevice
may lead to different results, based on
the different DRM capabilities of the devices.
Parameters | |
---|---|
uuid |
UUID : The UUID of the crypto scheme.
This value cannot be null . |
mimeType |
String : The MIME type of the media container, e.g. "video/mp4"
or "video/webm"
This value cannot be null . |
securityLevel |
int : the security level requested
Value is SECURITY_LEVEL_UNKNOWN , SECURITY_LEVEL_SW_SECURE_CRYPTO , SECURITY_LEVEL_SW_SECURE_DECODE , SECURITY_LEVEL_HW_SECURE_CRYPTO , SECURITY_LEVEL_HW_SECURE_DECODE , or SECURITY_LEVEL_HW_SECURE_ALL |
Returns | |
---|---|
boolean |
isCryptoSchemeSupported
public static boolean isCryptoSchemeSupported (UUID uuid)
Query if the given scheme identified by its UUID is supported on this device.
Parameters | |
---|---|
uuid |
UUID : The UUID of the crypto scheme.
This value cannot be null . |
Returns | |
---|---|
boolean |
openSession
public byte[] openSession ()
Open a new session with the MediaDrm object. A session ID is returned.
By default, sessions are opened at the native security level of the device.
If the application is currently running on a VirtualDevice
the security level will be adjusted accordingly to the maximum supported level for the
display.
Returns | |
---|---|
byte[] |
This value cannot be null . |
Throws | |
---|---|
NotProvisionedException |
if provisioning is needed |
ResourceBusyException |
if required resources are in use |
openSession
public byte[] openSession (int level)
Open a new session at a requested security level. The security level
represents the robustness of the device's DRM implementation. By default,
sessions are opened at the native security level of the device.
Overriding the security level is necessary when the decrypted frames need
to be manipulated, such as for image compositing. The security level
parameter must be lower than the native level. Reducing the security
level will typically limit the content to lower resolutions, as
determined by the license policy. If the requested level is not
supported, the next lower supported security level will be set. The level
can be queried using getSecurityLevel(byte)
. A session
ID is returned.
If the application is currently running on a VirtualDevice
the security level will be adjusted accordingly to the maximum supported level for the
display.
Parameters | |
---|---|
level |
int : the new security level
Value is SECURITY_LEVEL_UNKNOWN , SECURITY_LEVEL_SW_SECURE_CRYPTO , SECURITY_LEVEL_SW_SECURE_DECODE , SECURITY_LEVEL_HW_SECURE_CRYPTO , SECURITY_LEVEL_HW_SECURE_DECODE , or SECURITY_LEVEL_HW_SECURE_ALL |
Returns | |
---|---|
byte[] |
This value cannot be null . |
Throws | |
---|---|
NotProvisionedException |
if provisioning is needed |
ResourceBusyException |
if required resources are in use |
IllegalArgumentException |
if the requested security level is higher than the native level or lower than the lowest supported level or if the device does not support specifying the security level when opening a session |
provideKeyResponse
public byte[] provideKeyResponse (byte[] scope, byte[] response)
A key response is received from the license server by the app, then it is
provided to the MediaDrm instance using provideKeyResponse. When the
response is for an offline key request, a keySetId is returned that can be
used to later restore the keys to a new session with the method
restoreKeys(byte, byte)
.
When the response is for a streaming or release request, an empty byte array
is returned.
Parameters | |
---|---|
scope |
byte : may be a sessionId or keySetId depending on the type of the
response. Scope should be set to the sessionId when the response is for either
streaming or offline key requests. Scope should be set to the keySetId when
the response is for a release request.
This value cannot be null . |
response |
byte : the byte array response from the server
This value cannot be null . |
Returns | |
---|---|
byte[] |
If the response is for an offline request, the keySetId for the offline
keys will be returned. If the response is for a streaming or release request
an empty byte array will be returned.
This value may be null . |
Throws | |
---|---|
NotProvisionedException |
if the response indicates that reprovisioning is required |
DeniedByServerException |
if the response indicates that the server rejected the request |
provideProvisionResponse
public void provideProvisionResponse (byte[] response)
After a provision response is received by the app, it is provided to the MediaDrm instance using this method.
Parameters | |
---|---|
response |
byte : the opaque provisioning response byte array to provide to the
MediaDrm instance.
This value cannot be null . |
Throws | |
---|---|
DeniedByServerException |
if the response indicates that the server rejected the request |
queryKeyStatus
public HashMap<String, String> queryKeyStatus (byte[] sessionId)
Request an informative description of the key status for the session. The status is in the form of {name, value} pairs. Since DRM license policies vary by vendor, the specific status field names are determined by each DRM vendor. Refer to your DRM provider documentation for definitions of the field names for a particular DRM plugin.
Parameters | |
---|---|
sessionId |
byte : the session ID for the DRM session
This value cannot be null . |
releaseAllSecureStops
public void releaseAllSecureStops ()
This method was deprecated
in API level 28.
Remove all secure stops using removeAllSecureStops()
instead.
Remove all secure stops without requiring a secure stop release message from the license server.
releaseSecureStops
public void releaseSecureStops (byte[] ssRelease)
This method was deprecated
in API level 33.
This method is deprecated and may be removed in a future
release. Use renewals by calling getKeyRequest(byte, byte, String, int, HashMap)
to track
concurrent playback. See additional information in
getSecureStops()
Process the secure stop server response message ssRelease. After authenticating the message, remove the secure stops identified in the response.
Parameters | |
---|---|
ssRelease |
byte : the server response indicating which secure stops to release
This value cannot be null . |
removeAllSecureStops
public void removeAllSecureStops ()
This method was deprecated
in API level 33.
This method is deprecated and may be removed in a future
release. Use renewals by calling getKeyRequest(byte, byte, String, int, HashMap)
to track
concurrent playback. See additional information in
getSecureStops()
Remove all secure stops without requiring a secure stop release message from
the license server.
This method was added in API 28. In API versions 18 through 27,
releaseAllSecureStops()
should be called instead. There is no need to
do anything for API versions prior to 18.
removeKeys
public void removeKeys (byte[] sessionId)
Remove the current keys from a session.
Parameters | |
---|---|
sessionId |
byte : the session ID for the DRM session
This value cannot be null . |
removeOfflineLicense
public void removeOfflineLicense (byte[] keySetId)
Normally offline licenses are released using a key request/response
exchange using getKeyRequest(byte, byte, String, int, HashMap)
where the key type is
KEY_TYPE_RELEASE, followed by provideKeyResponse(byte, byte)
. This allows
the server to cryptographically confirm that the license has been removed
and then adjust the count of offline licenses allocated to the device.
In some exceptional situations it may be necessary to directly remove offline licenses without notifying the server, which may be performed using this method.
Parameters | |
---|---|
keySetId |
byte : the id of the offline license to remove
This value cannot be null . |
Throws | |
---|---|
IllegalArgumentException |
if the keySetId does not refer to an offline license. |
removeSecureStop
public void removeSecureStop (byte[] ssid)
This method was deprecated
in API level 33.
This method is deprecated and may be removed in a future
release. Use renewals by calling getKeyRequest(byte, byte, String, int, HashMap)
to track
concurrent playback. See additional information in
getSecureStops()
Remove a specific secure stop without requiring a secure stop release message from the license server.
Parameters | |
---|---|
ssid |
byte : the ID of the secure stop to remove
This value cannot be null . |
requiresSecureDecoder
public boolean requiresSecureDecoder (String mime)
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. The default security level is defined as the highest security level supported on the device.
Parameters | |
---|---|
mime |
String : The mime type of the media data. Please use isCryptoSchemeSupported(java.util.UUID, java.lang.String) to query mime type support separately;
for unsupported mime types the return value of requiresSecureDecoder(java.lang.String) is crypto scheme dependent.
This value cannot be null . |
Returns | |
---|---|
boolean |
requiresSecureDecoder
public boolean requiresSecureDecoder (String mime, int level)
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.
Parameters | |
---|---|
mime |
String : The mime type of the media data. Please use isCryptoSchemeSupported(java.util.UUID, java.lang.String, int) to query mime type support
separately; for unsupported mime types the return value of requiresSecureDecoder(java.lang.String, int) is crypto scheme dependent.
This value cannot be null . |
level |
int : a security level between SECURITY_LEVEL_SW_SECURE_CRYPTO
and SECURITY_LEVEL_HW_SECURE_ALL . Otherwise the special value
getMaxSecurityLevel() is also permitted;
use getMaxSecurityLevel() to indicate the maximum security level
supported by the device.
Value is SECURITY_LEVEL_UNKNOWN , SECURITY_LEVEL_SW_SECURE_CRYPTO , SECURITY_LEVEL_SW_SECURE_DECODE , SECURITY_LEVEL_HW_SECURE_CRYPTO , SECURITY_LEVEL_HW_SECURE_DECODE , or SECURITY_LEVEL_HW_SECURE_ALL |
Returns | |
---|---|
boolean |
Throws | |
---|---|
IllegalArgumentException |
if the requested security level is none of the documented
values for the parameter level . |
restoreKeys
public void restoreKeys (byte[] sessionId, byte[] keySetId)
Restore persisted offline keys into a new session. keySetId identifies the
keys to load, obtained from a prior call to provideKeyResponse(byte, byte)
.
Parameters | |
---|---|
sessionId |
byte : the session ID for the DRM session
This value cannot be null . |
keySetId |
byte : identifies the saved key set to restore
This value cannot be null . |
setOnEventListener
public void setOnEventListener (Executor executor, MediaDrm.OnEventListener listener)
Register a callback to be invoked when an event occurs
Parameters | |
---|---|
executor |
Executor : the executor through which the listener should be invoked
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
Otherwise, provide an Executor that dispatches to an appropriate thread. |
listener |
MediaDrm.OnEventListener : the callback that will be run.
This value cannot be null . |
See also:
setOnEventListener
public void setOnEventListener (MediaDrm.OnEventListener listener, Handler handler)
Register a callback to be invoked when an event occurs
Parameters | |
---|---|
listener |
MediaDrm.OnEventListener : the callback that will be run. Use null to
stop receiving event callbacks. |
handler |
Handler : the handler on which the listener should be invoked, or
null if the listener should be invoked on the calling thread's looper. |
setOnEventListener
public void setOnEventListener (MediaDrm.OnEventListener listener)
Register a callback to be invoked when an event occurs
Parameters | |
---|---|
listener |
MediaDrm.OnEventListener : the callback that will be run. Use null to
stop receiving event callbacks. |
setOnExpirationUpdateListener
public void setOnExpirationUpdateListener (MediaDrm.OnExpirationUpdateListener listener, Handler handler)
Register a callback to be invoked when a session expiration update occurs. The app's OnExpirationUpdateListener will be notified when the expiration time of the keys in the session have changed.
Parameters | |
---|---|
listener |
MediaDrm.OnExpirationUpdateListener : the callback that will be run, or null to unregister the
previously registered callback. |
handler |
Handler : the handler on which the listener should be invoked, or
null if the listener should be invoked on the calling thread's looper. |
setOnExpirationUpdateListener
public void setOnExpirationUpdateListener (Executor executor, MediaDrm.OnExpirationUpdateListener listener)
Register a callback to be invoked when a session expiration update occurs.
Parameters | |
---|---|
executor |
Executor : the executor through which the listener should be invoked
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
Otherwise, provide an Executor that dispatches to an appropriate thread. |
listener |
MediaDrm.OnExpirationUpdateListener : the callback that will be run.
This value cannot be null . |
setOnKeyStatusChangeListener
public void setOnKeyStatusChangeListener (Executor executor, MediaDrm.OnKeyStatusChangeListener listener)
Register a callback to be invoked when the state of keys in a session change.
Parameters | |
---|---|
executor |
Executor : the executor on which the listener should be invoked.
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
Otherwise, provide an Executor that dispatches to an appropriate thread. |
listener |
MediaDrm.OnKeyStatusChangeListener : the callback that will be run when key status changes.
This value cannot be null . |
setOnKeyStatusChangeListener
public void setOnKeyStatusChangeListener (MediaDrm.OnKeyStatusChangeListener listener, Handler handler)
Register a callback to be invoked when the state of keys in a session change, e.g. when a license update occurs or when a license expires.
Parameters | |
---|---|
listener |
MediaDrm.OnKeyStatusChangeListener : the callback that will be run when key status changes, or
null to unregister the previously registered callback. |
handler |
Handler : the handler on which the listener should be invoked, or
null if the listener should be invoked on the calling thread's looper. |
setOnSessionLostStateListener
public void setOnSessionLostStateListener (Executor executor, MediaDrm.OnSessionLostStateListener listener)
Register a callback to be invoked when session state has been lost.
Parameters | |
---|---|
executor |
Executor : the executor on which the listener should be invoked.
This value cannot be null .
Callback and listener events are dispatched through this
Executor , providing an easy way to control which thread is
used. To dispatch events through the main thread of your
application, you can use
Context.getMainExecutor() .
Otherwise, provide an Executor that dispatches to an appropriate thread. |
listener |
MediaDrm.OnSessionLostStateListener : the callback that will be run.
This value may be null . |
setOnSessionLostStateListener
public void setOnSessionLostStateListener (MediaDrm.OnSessionLostStateListener listener, Handler handler)
Register a callback to be invoked when session state has been lost. This event can occur on devices that are not capable of retaining crypto session state across device suspend/resume cycles. When this event occurs, the session must be closed and a new session opened to resume operation.
Parameters | |
---|---|
listener |
MediaDrm.OnSessionLostStateListener : the callback that will be run, or null to unregister the
previously registered callback. |
handler |
Handler : the handler on which the listener should be invoked, or
null if the listener should be invoked on the calling thread's looper. |
setPropertyByteArray
public void setPropertyByteArray (String propertyName, byte[] value)
Set a MediaDrm byte array property value, given the property name string and new value for the property.
Parameters | |
---|---|
propertyName |
String : This value cannot be null . |
value |
byte : This value cannot be null . |
setPropertyString
public void setPropertyString (String propertyName, String value)
Set a MediaDrm String property value, given the property name string and new value for the property.
Parameters | |
---|---|
propertyName |
String : This value cannot be null . |
value |
String : This value cannot be null . |
Protected methods
finalize
protected void finalize ()
Called by the garbage collector on an object when garbage collection
determines that there are no more references to the object.
A subclass overrides the finalize
method to dispose of
system resources or to perform other cleanup.
The general contract of finalize
is that it is invoked
if and when the Java virtual
machine has determined that there is no longer any
means by which this object can be accessed by any thread that has
not yet died, except as a result of an action taken by the
finalization of some other object or class which is ready to be
finalized. The finalize
method may take any action, including
making this object available again to other threads; the usual purpose
of finalize
, however, is to perform cleanup actions before
the object is irrevocably discarded. For example, the finalize method
for an object that represents an input/output connection might perform
explicit I/O transactions to break the connection before the object is
permanently discarded.
The finalize
method of class Object
performs no
special action; it simply returns normally. Subclasses of
Object
may override this definition.
The Java programming language does not guarantee which thread will
invoke the finalize
method for any given object. It is
guaranteed, however, that the thread that invokes finalize will not
be holding any user-visible synchronization locks when finalize is
invoked. If an uncaught exception is thrown by the finalize method,
the exception is ignored and finalization of that object terminates.
After the finalize
method has been invoked for an object, no
further action is taken until the Java virtual machine has again
determined that there is no longer any means by which this object can
be accessed by any thread that has not yet died, including possible
actions by other objects or classes which are ready to be finalized,
at which point the object may be discarded.
The finalize
method is never invoked more than once by a Java
virtual machine for any given object.
Any exception thrown by the finalize
method causes
the finalization of this object to be halted, but is otherwise
ignored.
Throws | |
---|---|
Throwable |