public final class MediaDrm
extends Object
| java.lang.Object | |
| ↳ | android.media.MediaDrm |
MediaDrm可用于获取解密受保护媒体流的密钥，并与MediaCrypto结合使用。 MediaDrm API旨在支持ISO / IEC 23001-7：通用加密标准，但也可用于实现其他加密方案。
加密内容使用加密服务器准备并存储在内容库中。 加密的内容通过内容服务器流式传输或从内容库下载到客户端设备。 从许可证服务器获取查看内容的许可证。
使用密钥请求从许可证服务器请求密钥。 关键响应传递给客户端应用程序，该应用程序向MediaDrm API提供响应。
供应服务器可能需要将设备唯一凭证分配给设备。
可以通过密钥更新或使用安全停止方法来执行与可以同时播放内容的设备数量相关的要求。
以下序列图显示了播放加密内容时涉及的对象之间的交互：
该应用程序首先构造MediaExtractor和MediaCodec对象。 它通常根据内容中的元数据访问DRM方案标识UUID，并使用此UUID构造能够支持内容所需的DRM方案的MediaDrm对象实例。 加密方案被分配16个字节的UUID。 方法isCryptoSchemeSupported(UUID)可用于查询设备是否支持给定方案。
该应用程序调用openSession()来生成一个sessionId，它将在随后的交互中唯一标识该会话。 接下来，应用程序使用MediaDrm对象获取密钥请求消息并将其发送到许可证服务器，然后将服务器的响应提供给MediaDrm对象。
一旦应用程序具有sessionId，它就可以从UUID和sessionId构造一个MediaCrypto对象。 将MediaCrypto对象注册到configure(MediaFormat, Surface, MediaCrypto, int)方法中的MediaCodec以使编码解码器解密内容。
当应用程序已建成MediaExtractor ， MediaCodec和MediaCrypto对象，则它前进到从提取拉样本，并将它们排队到解码器。 对于加密内容，从提取器返回的样本保持加密状态，只有样本传送到解码器时才会解密。
MediaDrm方法在DRM插件或安全硬件中发生无法恢复的故障的MediaDrm对象上调用方法时抛出MediaDrm.MediaDrmStateException 。 MediaDrm.MediaDrmStateException扩展了IllegalStateException ，并增加了与异常关联的开发人员可读的诊断信息字符串。
如果在MediaDrm对象处于活动状态时Mediaserver进程崩溃或重新启动，则MediaDrm方法可能会抛出MediaDrmResetException 。 要恢复，应用程序必须释放MediaDrm对象，然后创建并初始化一个新对象。
由于 MediaDrmResetException和 MediaDrm.MediaDrmStateException都延伸 IllegalStateException ，如果单独处理它们，它们应该位于早于catch（）块的位置，而不是 IllegalStateException 。
应用程序应注册信息事件，以便在播放或流式传输过程中获知关键状态更新。 通过致电setOnEventListener(MediaDrm.OnEventListener)完成这些活动的注册。 为了接收与此侦听器相关的各自回调，应用程序需要在运行其自己的Looper的线程上创建MediaDrm对象（默认情况下，主UI线程的Looper正在运行）。
Nested classes |
|
|---|---|
class |
MediaDrm.CryptoSession 除了支持DASH通用加密媒体的解密外，MediaDrm API还提供了基于工厂安装的信任根，从运营商的会话密钥服务器向客户端设备安全传送会话密钥的能力，然后执行加密，解密，使用任意用户数据上的会话密钥签署和验证操作。 |
class |
MediaDrm.KeyRequest 包含应用程序用来从许可证服务器请求密钥的不透明数据 |
class |
MediaDrm.KeyStatus 定义密钥的状态。 |
class |
MediaDrm.MediaDrmStateException 在MediaDrm操作期间发生不可恢复的故障时引发。 |
interface |
MediaDrm.OnEventListener DRM事件发生时要调用的回调接口定义 |
interface |
MediaDrm.OnExpirationUpdateListener DRM会话过期更新发生时要调用的回调的接口定义 |
interface |
MediaDrm.OnKeyStatusChangeListener 当drm会话中的键更改状态时要调用的回调的接口定义。 |
class |
MediaDrm.ProvisionRequest 包含应用程序用于从供应服务器请求证书的不透明数据 |
Constants |
|
|---|---|
int |
EVENT_KEY_EXPIRED 此事件类型表示会话中密钥的许可使用持续时间已过期。 |
int |
EVENT_KEY_REQUIRED 此事件类型表示应用程序需要从许可证服务器请求密钥。 |
int |
EVENT_PROVISION_REQUIRED 此常数在API级别23中已弃用。 |
int |
EVENT_SESSION_RECLAIMED 此事件表示由应用程序打开的会话已被资源管理器回收。 |
int |
EVENT_VENDOR_DEFINED 此事件可能指示某些特定供应商定义的情况，请参阅您的DRM提供商文档以了解详细信息 |
int |
KEY_TYPE_OFFLINE 此密钥请求类型指定密钥将用于脱机使用，它们将被保存到设备以供设备未连接到网络时使用。 |
int |
KEY_TYPE_RELEASE 此密钥请求类型指定应释放先前保存的脱机密钥。 |
int |
KEY_TYPE_STREAMING 这种密钥请求类型可用于在线使用密钥，当设备未连接到网络时，它们将不会保存到设备中供以后使用。 |
String |
PROPERTY_ALGORITHMS 字符串属性名称：由CryptoSession支持的密码和mac算法的逗号分隔列表。 |
String |
PROPERTY_DESCRIPTION 字符串属性名称：描述DRM引擎插件 |
String |
PROPERTY_DEVICE_UNIQUE_ID 字节数组属性名称：设备唯一标识符在设备设置期间建立，并提供了唯一标识每个设备的方法。 |
String |
PROPERTY_VENDOR 字符串属性名称：标识DRM引擎插件的制造商 |
String |
PROPERTY_VERSION 字符串属性名称：标识DRM引擎插件的版本 |
Public constructors |
|
|---|---|
MediaDrm(UUID uuid) 实例化MediaDrm对象 |
|
Public methods |
|
|---|---|
void |
closeSession(byte[] sessionId) 关闭以前使用 |
MediaDrm.CryptoSession |
getCryptoSession(byte[] sessionId, String cipherAlgorithm, String macAlgorithm) 使用会话密钥服务器，使用方法 |
MediaDrm.KeyRequest |
getKeyRequest(byte[] scope, byte[] init, String mimeType, int keyType, HashMap<String, String> optionalParameters) 在应用程序和许可证服务器之间发生密钥请求/响应交换，以获取或释放用于解密加密内容的密钥。 |
byte[] |
getPropertyByteArray(String propertyName) 读取DRM引擎插件字节数组属性值，给定属性名称字符串。 |
String |
getPropertyString(String propertyName) 读取DRM引擎插件字符串属性值，给定属性名称字符串。 |
MediaDrm.ProvisionRequest |
getProvisionRequest() 在应用程序和供应服务器之间进行供应请求/响应交换以检索设备证书。 |
byte[] |
getSecureStop(byte[] ssid) 通过安全停止ID访问安全停止。 |
List<byte[]> |
getSecureStops() 通过SecureStop提供了一种强制限制跨设备每用户并发流数量的方法。 |
static final boolean |
isCryptoSchemeSupported(UUID uuid, String mimeType) 查询此设备是否支持由其UUID标识的给定方案，以及drm插件是否能够处理由mimeType指定的媒体容器格式。 |
static final boolean |
isCryptoSchemeSupported(UUID uuid) 查询此设备是否支持由其UUID标识的给定方案。 |
byte[] |
openSession() 使用MediaDrm对象打开新会话。 |
byte[] |
provideKeyResponse(byte[] scope, byte[] response) 应用程序从许可证服务器接收到一个关键响应，然后使用provideKeyResponse将其提供给DRM引擎插件。 |
void |
provideProvisionResponse(byte[] response) 在应用程序收到供应响应后，将使用此方法将其提供给DRM引擎插件。 |
HashMap<String, String> |
queryKeyStatus(byte[] sessionId) 要求提供关于会议关键状态的信息描述。 |
final void |
release() |
void |
releaseAllSecureStops() 无需与服务器进行交互，即可移除所有安全停止。 |
void |
releaseSecureStops(byte[] ssRelease) 处理SecureStop服务器响应消息ssRelease。 |
void |
removeKeys(byte[] sessionId) 从会话中删除当前密钥。 |
void |
restoreKeys(byte[] sessionId, byte[] keySetId) 将持久保存的离线密钥还原到新会话中。 |
void |
setOnEventListener(MediaDrm.OnEventListener listener) 注册要在发生事件时调用的回调 |
void |
setOnExpirationUpdateListener(MediaDrm.OnExpirationUpdateListener listener, Handler handler) 在会话过期更新发生时注册要调用的回调。 |
void |
setOnKeyStatusChangeListener(MediaDrm.OnKeyStatusChangeListener listener, Handler handler) 当会话中的密钥状态发生变化时，注册一个回调以供调用，例如 |
void |
setPropertyByteArray(String propertyName, byte[] value) 设置DRM引擎插件字节数组属性值。 |
void |
setPropertyString(String propertyName, String value) 设置DRM引擎插件字符串属性值。 |
Protected methods |
|
|---|---|
void |
finalize() 当垃圾收集确定没有更多对该对象的引用时，由对象上的垃圾回收器调用。 |
Inherited methods |
|
|---|---|
 From class java.lang.Object
|
|
int EVENT_KEY_EXPIRED
此事件类型表示会话中密钥的许可使用持续时间已过期。 密钥不再有效。
常量值：3（0x00000003）
int EVENT_KEY_REQUIRED
此事件类型表示应用程序需要从许可证服务器请求密钥。 请求消息数据使用getKeyRequest(byte[], byte[], String, int, HashMap
。
常量值：2（0x00000002）
int EVENT_PROVISION_REQUIRED
此常数在API级别23中已弃用。
改为通过NotProvisionedException处理配置。
此事件类型表示应用程序需要从配置服务器请求证书。 请求消息数据使用getProvisionRequest()
常数值：1（0x00000001）
int EVENT_SESSION_RECLAIMED
此事件表示由应用程序打开的会话已被资源管理器回收。
常量值：5（0x00000005）
int EVENT_VENDOR_DEFINED
此事件可能指示某些特定供应商定义的情况，请参阅您的DRM提供商文档以了解详细信息
常量值：4（0x00000004）
int KEY_TYPE_OFFLINE
此密钥请求类型指定密钥将用于脱机使用，它们将被保存到设备以供设备未连接到网络时使用。
常量值：2（0x00000002）
int KEY_TYPE_RELEASE
此密钥请求类型指定应释放先前保存的脱机密钥。
常量值：3（0x00000003）
int KEY_TYPE_STREAMING
这种密钥请求类型可用于在线使用密钥，当设备未连接到网络时，它们将不会保存到设备中供以后使用。
常数值：1（0x00000001）
String PROPERTY_ALGORITHMS
字符串属性名称：由CryptoSession支持的密码和mac算法的逗号分隔列表。 如果DRM引擎插件不支持CryptoSession操作，则列表可能为空。
常量值：“算法”
String PROPERTY_DEVICE_UNIQUE_ID
字节数组属性名称：设备唯一标识符在设备设置期间建立，并提供了唯一标识每个设备的方法。
常量值：“deviceUniqueId”
MediaDrm (UUID uuid)
实例化MediaDrm对象
| Parameters | |
|---|---|
uuid |
UUID: The UUID of the crypto scheme. |
| Throws | |
|---|---|
UnsupportedSchemeException |
if the device does not support the specified scheme UUID |
void closeSession (byte[] sessionId)
关闭以前使用 openSession()打开的MediaDrm对象上的会话。
| Parameters | |
|---|---|
sessionId |
byte
|
MediaDrm.CryptoSession getCryptoSession (byte[] sessionId, String cipherAlgorithm, String macAlgorithm)
使用会话密钥服务器，使用方法 getKeyRequest(byte[], byte[], String, int, HashMap
和 provideKeyResponse(byte[], byte[])获取可用于使用为会话建立的会话密钥来加密，解密，签名和验证消息或数据的CryptoSession对象。
| Parameters | |
|---|---|
sessionId |
byte: the session ID for the session containing keys to be used for encrypt, decrypt, sign and/or verify |
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". |
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". 可以使用属性名称为“算法”的方法 |
| Returns | |
|---|---|
MediaDrm.CryptoSession |
|
MediaDrm.KeyRequest getKeyRequest (byte[] scope, byte[] init, String mimeType, int keyType, HashMap<String, String> optionalParameters)
在应用程序和许可证服务器之间发生密钥请求/响应交换，以获取或释放用于解密加密内容的密钥。
getKeyRequest（）用于获取传递到许可证服务器的不透明密钥请求字节数组。 KeyRequest.data中返回不透明的密钥请求字节数组。 KeyRequest.defaultUrl中将返回推荐的密钥请求的URL。
应用程序收到来自服务器的密钥请求响应后，应使用方法 provideKeyResponse(byte[], byte[])将响应传递给DRM引擎插件。
| 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. |
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. init may be null when keyType is KEY_TYPE_RELEASE. |
mimeType |
String: identifies the mime type of the content |
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. |
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 |
|
| Throws | |
|---|---|
NotProvisionedException |
if reprovisioning is needed, due to a problem with the certifcate |
byte[] getPropertyByteArray (String propertyName)
读取DRM引擎插件字节数组属性值，给定属性名称字符串。
标准字段名称是 PROPERTY_DEVICE_UNIQUE_ID
| Parameters | |
|---|---|
propertyName |
String
|
| Returns | |
|---|---|
byte[] |
|
String getPropertyString (String propertyName)
读取DRM引擎插件字符串属性值，给定属性名称字符串。
标准字段名称是： PROPERTY_VENDOR ， PROPERTY_VERSION ， PROPERTY_DESCRIPTION ， PROPERTY_ALGORITHMS
| Parameters | |
|---|---|
propertyName |
String
|
| Returns | |
|---|---|
String |
|
MediaDrm.ProvisionRequest getProvisionRequest ()
在应用程序和供应服务器之间进行供应请求/响应交换以检索设备证书。 如果需要设置，EVENT_PROVISION_REQUIRED事件将被发送到事件处理程序。 getProvisionRequest用于获取应提供给配置服务器的不透明配置请求字节数组。 提供请求字节数组在ProvisionRequest.data中返回。 在ProvisionRequest.defaultUrl中返回推荐提供请求的URL。
| Returns | |
|---|---|
MediaDrm.ProvisionRequest |
|
byte[] getSecureStop (byte[] ssid)
通过安全停止ID访问安全停止。
| Parameters | |
|---|---|
ssid |
byte: - The secure stop ID provided by the license server. |
| Returns | |
|---|---|
byte[] |
|
List<byte[]> getSecureStops ()
通过SecureStop提供了一种强制限制跨设备每用户并发流数量的方法。 这是通过安全地监控会话的生命周期来实现的。
当创建每个MediaCrypto对象时，与当前回放会话相关的来自服务器的信息被写入设备上的永久存储器。
在正常情况下，播放将完成，会话被破坏并且安全停留将被查询。 应用程序查询安全停止并将安全停止消息转发给验证签名的服务器，并通知服务器端数据库已确认会话销毁。 在正确确认服务器使用releaseSecureStops（）接收到消息后，才会删除客户端上的持久记录。
| Returns | |
|---|---|
List<byte[]> |
|
boolean isCryptoSchemeSupported (UUID uuid, String mimeType)
查询此设备是否支持由其UUID标识的给定方案，以及drm插件是否能够处理由mimeType指定的媒体容器格式。
| Parameters | |
|---|---|
uuid |
UUID: The UUID of the crypto scheme. |
mimeType |
String: The MIME type of the media container, e.g. "video/mp4" or "video/webm" |
| Returns | |
|---|---|
boolean |
|
boolean isCryptoSchemeSupported (UUID uuid)
查询此设备是否支持由其UUID标识的给定方案。
| Parameters | |
|---|---|
uuid |
UUID: The UUID of the crypto scheme. |
| Returns | |
|---|---|
boolean |
|
byte[] openSession ()
使用MediaDrm对象打开新会话。 会话ID被返回。
| Returns | |
|---|---|
byte[] |
|
| Throws | |
|---|---|
NotProvisionedException |
if provisioning is needed |
ResourceBusyException |
if required resources are in use |
Android开发手册
byte[] provideKeyResponse (byte[] scope,
byte[] response)
应用程序从许可证服务器接收到一个关键响应，然后使用provideKeyResponse将其提供给DRM引擎插件。 当响应用于脱机密钥请求时，会返回一个keySetId，以便以后可以使用方法restoreKeys(byte[], byte[])将密钥恢复到新会话。 当响应是针对流或释放请求时，返回null。
| 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. |
response |
byte: the byte array response from the server |
| Returns | |
|---|---|
byte[] |
|
| Throws | |
|---|---|
NotProvisionedException |
if the response indicates that reprovisioning is required |
DeniedByServerException |
if the response indicates that the server rejected the request |
void provideProvisionResponse (byte[] response)
在应用程序收到供应响应后，将使用此方法将其提供给DRM引擎插件。
| Parameters | |
|---|---|
response |
byte: the opaque provisioning response byte array to provide to the DRM engine plugin. |
| Throws | |
|---|---|
DeniedByServerException |
if the response indicates that the server rejected the request |
HashMap<String, String> queryKeyStatus (byte[] sessionId)
要求提供关于会议关键状态的信息描述。 状态为{name，value}对的形式。 由于DRM许可证策略因供应商而异，因此特定状态字段名称由每个DRM供应商确定。 有关特定DRM引擎插件字段名称的定义，请参阅您的DRM提供商文档。
| Parameters | |
|---|---|
sessionId |
byte: the session ID for the DRM session |
| Returns | |
|---|---|
HashMap<String, String> |
|
void releaseSecureStops (byte[] ssRelease)
处理SecureStop服务器响应消息ssRelease。 验证消息后，删除响应中标识的SecureStops。
| Parameters | |
|---|---|
ssRelease |
byte: the server response indicating which secure stops to release |
void removeKeys (byte[] sessionId)
从会话中删除当前密钥。
| Parameters | |
|---|---|
sessionId |
byte: the session ID for the DRM session |
void restoreKeys (byte[] sessionId,
byte[] keySetId)
将持久保存的离线密钥还原到新会话中。 keySetId标识要加载的密钥，从先前调用provideKeyResponse(byte[], byte[]) 。
| Parameters | |
|---|---|
sessionId |
byte: the session ID for the DRM session |
keySetId |
byte: identifies the saved key set to restore |
void setOnEventListener (MediaDrm.OnEventListener listener)
注册要在发生事件时调用的回调
| Parameters | |
|---|---|
listener |
MediaDrm.OnEventListener: the callback that will be run. Use null to stop receiving event callbacks. |
void setOnExpirationUpdateListener (MediaDrm.OnExpirationUpdateListener listener, Handler handler)
在会话过期更新发生时注册要调用的回调。 应用程序的OnExpirationUpdateListener将在会话中的密钥到期时间发生变化时收到通知。
| 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. |
void setOnKeyStatusChangeListener (MediaDrm.OnKeyStatusChangeListener listener, Handler handler)
当会话中的密钥状态发生变化时（例如发生许可证更新或许可证过期时），注册要调用的回调。
| 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. |
void setPropertyByteArray (String propertyName, byte[] value)
设置DRM引擎插件字节数组属性值。
| Parameters | |
|---|---|
propertyName |
String
|
value |
byte
|
void setPropertyString (String propertyName, String value)
设置DRM引擎插件字符串属性值。
| Parameters | |
|---|---|
propertyName |
String
|
value |
String
|
void finalize ()
当垃圾收集确定没有更多对该对象的引用时，由对象上的垃圾回收器调用。 子类会覆盖finalize方法以处置系统资源或执行其他清理。
的常规协定finalize是，它被调用，如果当在Java TM虚拟机已确定不再有由该目的可以通过还没有死亡，除了作为一个动作的结果的任何线程访问的任何手段取决于某些其他可以完成的对象或类别的最终定稿。 finalize方法可以采取任何行动，包括使该对象再次可用于其他线程; 但是， finalize的通常目的是在对象被不可撤销地丢弃之前执行清理操作。 例如，表示输入/输出连接的对象的finalize方法可能会执行显式I / O事务，以在永久丢弃该对象之前中断连接。
类Object的finalize方法Object执行特殊操作; 它只是正常返回。 Object子类可能会覆盖此定义。
Java编程语言不保证哪个线程将为任何给定对象调用finalize方法。 但是，保证调用finalize的线程在调用finalize时不会保留任何用户可见的同步锁。 如果finalize方法引发未捕获的异常，则忽略该异常，并终止该对象的终止。
在针对某个对象调用 finalize方法之后，在Java虚拟机再次确定不再有任何方法可以通过尚未死亡的任何线程访问此对象，包括可能的操作通过准备完成的其他对象或类别，此时该对象可能被丢弃。
对于任何给定的对象，Java虚拟机永远不会多次调用 finalize方法。
finalize方法抛出的任何异常 finalize导致终止此对象的终止，但会被忽略。