官方文档

MediaDrm | Android API 参考文档原文标题：MediaDrm | API reference | Android Developers

发表时间：（页面未标注）采集时间：2026-10-09 10:28:46来源：developer.android.com原文语言：en状态：抽取受限

原始链接：https://developer.android.com/reference/android/media/MediaDrm

内容概要总结

Android 官方 API 参考，介绍 android.media.MediaDrm 类（在 API level 18 引入，为 public final class，实现 AutoCloseable）。MediaDrm 与 MediaCrypto 配合，用于获取解密受保护媒体流所需的密钥，其 API 设计支持 ISO/IEC 23001-7: Common Encryption 标准，也可用于实现其他加密方案。

文档说明了完整的 DRM 播放交互流程：加密内容由加密服务器准备并存入内容库，经内容服务器串流或下载到客户端，许可从 License Server 获取；通过 key request 向许可服务器请求密钥，密钥响应交给 App 再提供给 MediaDrm API；可能还需要 Provisioning server 向设备分发设备唯一凭据（device-unique credentials）。限制同时播放内容的设备数量可通过密钥续期或 secure stop 方法实现。文中给出 MediaExtractor/MediaCodec/MediaCrypto 的构造与解密流程，并说明 MediaDrmStateException、MediaDrmResetException 的处理，以及回调需在带 Looper 的线程上创建 MediaDrm 对象。

本文档列出了完整的嵌套类（CryptoSession、ErrorCodes、KeyRequest、KeyStatus、LogMessage、MediaDrmStateException、MetricsConstants 及 OnEventListener/OnExpirationUpdateListener/OnKeyStatusChangeListener/OnSessionLostStateListener 等接口、PlaybackComponent、ProvisionRequest、SessionException）、全部常量（EVENT_*、HDCP_*、KEY_TYPE_*、OFFLINE_LICENSE_STATE_*、PROPERTY_*（含 PROPERTY_DEVICE_UNIQUE_ID）、SECURITY_LEVEL_*）、构造函数 MediaDrm(UUID) 与全部公开/受保护方法的签名、参数、返回值与异常说明。

翻译内容

原文内容（English）

⚠ 说明：原站直连返回 302 重定向循环，正文经浏览器渲染（browser-bridge）获取；已剔除站点导航（含庞大的包/类索引）与页脚，仅保留 MediaDrm 类主体。该页为完整 API 参考，已全文翻译。

在 API level 18 中新增

public final class MediaDrm
extends Object implements AutoCloseable

java.lang.Object
   ↳	android.media.MediaDrm

MediaDrm 可用于与 MediaCrypto 配合，获取解密受保护媒体流所需的密钥。MediaDrm API 设计用于支持 ISO/IEC 23001-7: Common Encryption 标准，但也可用于实现其他加密方案。

加密内容使用加密服务器（encryption server）准备，并存储在一个内容库中。加密内容经内容服务器从内容库串流或下载到客户端设备。观看内容的许可从 License Server 获取。

密钥通过 key request（密钥请求）从许可服务器请求。密钥响应（key response）交付给客户端 App，由 App 将响应提供给 MediaDrm API。

可能需要一台 Provisioning server 来向设备分发设备唯一凭据（device-unique credentials）。

与可同时播放内容的设备数量相关的要求，既可以通过密钥续期（key renewal）来强制执行，也可以使用 secure stop 方法。

以下时序图展示了在回放加密内容时，相关对象之间的交互：

App 首先构造 MediaExtractor 和 MediaCodec 对象。它访问标识 DRM 方案的 UUID（通常来自内容中的元数据），并用该 UUID 构造一个能够支持该内容所需 DRM 方案的 MediaDrm 对象实例。加密方案被分配 16 字节的 UUID。方法 isCryptoSchemeSupported(UUID) 可用于查询某给定方案是否在该设备上受支持。

App 调用 openSession() 生成一个 sessionId，它将在后续交互中唯一标识该会话。App 接下来使用 MediaDrm 对象获取一条密钥请求消息并发送给许可服务器，然后把服务器的响应提供给 MediaDrm 对象。

一旦 App 有了 sessionId，它就可以用该 UUID 和 sessionId 构造一个 MediaCrypto 对象。该 MediaCrypto 对象在 MediaCodec.configure 方法中注册给 MediaCodec，以使编解码器能够解密内容。

当 App 构造好 MediaExtractor、MediaCodec 和 MediaCrypto 对象后，它会从 extractor 中拉取样本并将它们排入解码器。对于加密内容，从 extractor 返回的样本保持加密状态，只有当样本被送到解码器时才会被解密。

当在 DRM 插件或安全硬件发生不可恢复故障的 MediaDrm 对象上调用方法时，MediaDrm 方法会抛出 MediaDrm.MediaDrmStateException。MediaDrm.MediaDrmStateException 扩展自 IllegalStateException，并附加了一个开发者可读的、与该异常相关的诊断信息字符串。

在 MediaDrm 对象处于活动状态时，若 mediaserver 进程崩溃或重启，MediaDrm 方法可能抛出 MediaDrmResetException。要恢复，App 必须释放该 MediaDrm 对象，然后创建并初始化一个新的。

由于 MediaDrmResetException 和 MediaDrm.MediaDrmStateException 都扩展自 IllegalStateException，如果分别处理，它们应放在比 IllegalStateException 更靠前的 catch() 块中。

回调（Callbacks）

应用程序应注册信息性事件，以便在回放或串流期间获知密钥状态更新。这些事件的注册通过调用 setOnEventListener(OnEventListener) 完成。为了接收与该监听器关联的相应回调，应用程序需要在带有自己 Looper 的线程上创建 MediaDrm 对象（主 UI 线程默认就有 Looper 在运行）。

摘要（Summary）

嵌套类（Nested classes）

类型	类/接口	说明
class	MediaDrm.CryptoSession	除了支持解密 DASH Common Encrypted Media 之外，MediaDrm API 还提供能力：基于出厂安装的信任根，将会话密钥从运营商的会话密钥服务器安全地交付到客户端设备，然后用该会话密钥对任意用户数据执行加密、解密、签名和验证操作。
class	MediaDrm.ErrorCodes	可能从 `MediaDrmStateException.getErrorCode()` 和 `MediaCodec.CryptoException.getErrorCode()` 返回的错误码。每个错误码的描述都包含可用于解决该错误状况的步骤。
class	MediaDrm.KeyRequest	包含 App 用于向许可服务器请求密钥的不透明数据。
class	MediaDrm.KeyStatus	定义密钥的状态。
class	MediaDrm.LogMessage	LogMessage 记录 MediaDrm 框架或厂商插件中的一个事件。
class	MediaDrm.MediaDrmStateException	在 MediaDrm 操作期间发生一般性故障时抛出。
class	MediaDrm.MetricsConstants	通过 `MediaDrm.getMetrics()` 调用上报的指标的定义。
interface	MediaDrm.OnEventListener	当发生 drm 事件时要调用的回调的接口定义。
interface	MediaDrm.OnExpirationUpdateListener	当发生 drm 会话过期更新时要调用的回调的接口定义。
interface	MediaDrm.OnKeyStatusChangeListener	当 drm 会话中的密钥状态发生变化时要调用的回调的接口定义。
interface	MediaDrm.OnSessionLostStateListener	当会话状态已丢失并现已失效时要调用的回调的接口定义。
class	MediaDrm.PlaybackComponent	此类包含 Drm 会话 ID 和日志会话 ID。
class	MediaDrm.ProvisionRequest	包含 App 用于向 provisioning server 请求证书的不透明数据。
class	MediaDrm.SessionException	SessionException 是个用词不当的名称，因为它可能发生在没有会话上下文的方法中。

常量（Constants）

类型	常量	说明
int	EVENT_KEY_EXPIRED	此常量在 API level 26 中已废弃。请改用 `OnKeyStatusChangeListener.onKeyStatusChange` 并在 MediaDrm.KeyStatus 中检查 `MediaDrm.KeyStatus.STATUS_EXPIRED`。
int	EVENT_KEY_REQUIRED	此事件类型表明 App 需要向许可服务器请求密钥。
int	EVENT_PROVISION_REQUIRED	此常量在 API level 23 中已废弃。请改为通过 NotProvisionedException 处理 provisioning。
int	EVENT_SESSION_RECLAIMED	此事件表明 App 打开的一个会话已被资源管理器回收。
int	EVENT_VENDOR_DEFINED	此事件可能表示某种厂商定义的特定状况，详见你的 DRM 提供商文档。
int	HDCP_LEVEL_UNKNOWN	DRM 插件未上报 HDCP 级别，或访问它时发生错误。
int	HDCP_NONE	该设备不支持 HDCP，内容未受保护。
int	HDCP_NO_DIGITAL_OUTPUT	无数字输出，隐式安全。
int	HDCP_V1	HDCP 1.0 版本。
int	HDCP_V2	HDCP 2.0 Type 1 版本。
int	HDCP_V2_1	HDCP 2.1 Type 1 版本。
int	HDCP_V2_2	HDCP 2.2 Type 1 版本。
int	HDCP_V2_3	HDCP 2.3 Type 1 版本。
int	KEY_TYPE_OFFLINE	此密钥请求类型指明密钥将用于离线用途，它们会被保存到设备上，以便设备未连接网络时使用。
int	KEY_TYPE_RELEASE	此密钥请求类型指明先前保存的离线密钥应被释放。
int	KEY_TYPE_STREAMING	此密钥请求类型指明密钥将用于在线用途，它们不会被保存到设备上供设备未连接网络时后续使用。
int	OFFLINE_LICENSE_STATE_RELEASED	离线许可已释放，密钥已通过 `getKeyRequest(byte, byte, String, int, HashMap)` 配合 KEY_TYPE_RELEASE 标记为待释放，但尚未收到密钥响应。
int	OFFLINE_LICENSE_STATE_UNKNOWN	离线许可状态未知，尝试访问它时发生了错误。
int	OFFLINE_LICENSE_STATE_USABLE	离线许可可用，密钥可用于解密。
String	PROPERTY_ALGORITHMS	String 属性名：由 CryptoSession 支持的 cipher 和 mac 算法的逗号分隔列表。
String	PROPERTY_DESCRIPTION	String 属性名：描述该 DRM 插件。
String	PROPERTY_DEVICE_UNIQUE_ID	Byte array 属性名：设备唯一标识符在设备 provisioning 期间建立，提供一种唯一标识每台设备的方式。
String	PROPERTY_VENDOR	String 属性名：标识该 DRM 插件的制造商。
String	PROPERTY_VERSION	String 属性名：标识该 DRM 插件的版本。
int	SECURITY_LEVEL_HW_SECURE_ALL	DRM 密钥管理、加密操作、内容解码以及媒体的所有处理（压缩和未压缩）都在由硬件支持的可信执行环境内完成。
int	SECURITY_LEVEL_HW_SECURE_CRYPTO	DRM 密钥管理和加密操作在由硬件支持的可信执行环境内执行。
int	SECURITY_LEVEL_HW_SECURE_DECODE	DRM 密钥管理、加密操作和内容解码在由硬件支持的可信执行环境内执行。
int	SECURITY_LEVEL_SW_SECURE_CRYPTO	DRM 密钥管理使用基于软件的白盒加密。
int	SECURITY_LEVEL_SW_SECURE_DECODE	DRM 密钥管理和解码使用基于软件的白盒加密。
int	SECURITY_LEVEL_UNKNOWN	DRM 插件未上报安全级别，或访问它时发生错误。

公开构造函数（Public constructors）

MediaDrm(UUID uuid) —— 实例化一个 MediaDrm 对象。

公开方法（Public methods）

void clearOnEventListener() —— 清除 OnEventListener。
void clearOnExpirationUpdateListener() —— 清除 OnExpirationUpdateListener。
void clearOnKeyStatusChangeListener() —— 清除 OnKeyStatusChangeListener。
void clearOnSessionLostStateListener() —— 清除 OnSessionLostStateListener。
void close() —— 释放与 MediaDrm 当前会话关联的资源。
void closeSession(byte[] sessionId) —— 关闭 MediaDrm 对象上先前用 openSession() 打开的会话。
int getConnectedHdcpLevel() —— 返回与设备所连接的下游接收器协商得到的 HDCP 级别。
MediaDrm.CryptoSession getCryptoSession(byte[] sessionId, String cipherAlgorithm, String macAlgorithm) —— 获取一个 CryptoSession 对象，可用于使用通过 getKeyRequest(byte, byte, String, int, HashMap) 和 provideKeyResponse(byte, byte) 借助会话密钥服务器为该会话建立的会话密钥，来加密、解密、签名和验证消息或数据。
MediaDrm.KeyRequest getKeyRequest(byte[] scope, byte[] init, String mimeType, int keyType, HashMap<String, String> optionalParameters) —— 在 App 与许可服务器之间发生一次密钥请求/响应交换，以获取或释放用于解密加密内容的密钥。
List<MediaDrm.LogMessage> getLogMessages() —— 返回与此 MediaDrm 实例关联的近期 LogMessage。
int getMaxHdcpLevel() —— 返回支持的最大 HDCP 级别。
static int getMaxSecurityLevel() —— 返回一个值，可作为参数传给 openSession(int)，请求以设备的最高安全级别打开会话。
int getMaxSessionCount() —— 返回针对当前 DRM 方案，所有 MediaDrm 实例之间可同时打开的最大 MediaDrm 会话数。
PersistableBundle getMetrics() —— 返回关于当前 MediaDrm 实例的 Metrics 数据。
List<byte[]> getOfflineLicenseKeySetIds() —— 离线许可中的密钥允许设备即使未连接网络也能播放受保护内容。
int getOfflineLicenseState(byte[] keySetId) —— 请求离线许可的状态。
int getOpenSessionCount() —— 返回针对当前 DRM 方案，所有 MediaDrm 实例之间当前同时打开的 MediaDrm 会话数。
MediaDrm.PlaybackComponent getPlaybackComponent(byte[] sessionId) —— 获取与某个 DRM 会话关联的 PlaybackComponent。
byte[] getPropertyByteArray(String propertyName) —— 给定属性名字符串，读取一个 MediaDrm 字节数组属性值。
String getPropertyString(String propertyName) —— 给定属性名字符串，读取一个 MediaDrm String 属性值。
MediaDrm.ProvisionRequest getProvisionRequest() —— 在 App 与 provisioning server 之间发生一次 provision 请求/响应交换，以获取设备证书。
byte[] getSecureStop(byte[] ssid) —— 此方法在 API level 33 中已废弃。 此方法已废弃，可能在未来的版本中被移除。请改为通过调用 getKeyRequest(byte, byte, String, int, HashMap) 进行续期来追踪并发播放。更多信息见 getSecureStops()。
List<byte[]> getSecureStopIds() —— 此方法在 API level 33 中已废弃。（同上，改用续期。）
List<byte[]> getSecureStops() —— 此方法在 API level 33 中已废弃。 secure stop 是一种跨设备对每个订阅者的并发流数量强制限制的方式，它们对 MediaDrm 会话中内容解密密钥的生命周期提供安全监控。对并发流的限制也可以通过定期续期许可来强制执行。MediaDrm 用户应从 secure stop 迁移到定期续期。
int getSecurityLevel(byte[] sessionId) —— 返回会话当前的安全级别。
static List<UUID> getSupportedCryptoSchemes() —— 返回 crypto scheme（以 UUID 表示）的列表。
static boolean isCryptoSchemeSupported(UUID uuid, String mimeType) —— 查询由 UUID 标识的给定方案是否在此设备上受支持，以及 DRM 插件是否能处理由 mimeType 指定的媒体容器格式。
static boolean isCryptoSchemeSupported(UUID uuid, String mimeType, int securityLevel) —— 查询由 UUID 标识的给定方案是否在此设备上受支持，以及 DRM 插件是否能在所请求的安全级别下处理由 mimeType 指定的媒体容器格式。
static boolean isCryptoSchemeSupported(UUID uuid) —— 查询由 UUID 标识的给定方案是否在此设备上受支持。
byte[] openSession() —— 打开一个与 MediaDrm 对象的新会话。
byte[] openSession(int level) —— 在所请求的安全级别上打开一个新会话。
byte[] provideKeyResponse(byte[] scope, byte[] response) —— App 从许可服务器收到密钥响应后，使用 provideKeyResponse 把它提供给 MediaDrm 实例。
void provideProvisionResponse(byte[] response) —— App 收到 provision 响应后，使用此方法把它提供给 MediaDrm 实例。
HashMap<String, String> queryKeyStatus(byte[] sessionId) —— 请求对该会话密钥状态的信息性描述。
void release() —— 此方法在 API level 28 中已废弃。 由 close() 取代。
void releaseAllSecureStops() —— 此方法在 API level 28 中已废弃。 请改用 removeAllSecureStops() 移除所有 secure stop。
void releaseSecureStops(byte[] ssRelease) —— 此方法在 API level 33 中已废弃。（改用续期。）
void removeAllSecureStops() —— 此方法在 API level 33 中已废弃。（改用续期。）
void removeKeys(byte[] sessionId) —— 从会话中移除当前密钥。
void removeOfflineLicense(byte[] keySetId) —— 通常离线许可通过 getKeyRequest(byte, byte, String, int, HashMap)（密钥类型为 KEY_TYPE_RELEASE）后接 provideKeyResponse(byte, byte) 的密钥请求/响应交换来释放。
void removeSecureStop(byte[] ssid) —— 此方法在 API level 33 中已废弃。（改用续期。）
boolean requiresSecureDecoder(String mime) —— 查询该 crypto scheme 是否要求使用安全解码器来在默认安全级别下解码给定 mime 类型的数据。
boolean requiresSecureDecoder(String mime, int level) —— 查询该 crypto scheme 是否要求使用安全解码器来在给定安全级别下解码给定 mime 类型的数据。
void restoreKeys(byte[] sessionId, byte[] keySetId) —— 把持久化的离线密钥恢复到新会话中。
void setOnEventListener(Executor executor, MediaDrm.OnEventListener listener) —— 注册一个在事件发生时要调用的回调。
void setOnEventListener(MediaDrm.OnEventListener listener, Handler handler) —— 注册一个在事件发生时要调用的回调。
void setOnEventListener(MediaDrm.OnEventListener listener) —— 注册一个在事件发生时要调用的回调。
void setOnExpirationUpdateListener(MediaDrm.OnExpirationUpdateListener listener, Handler handler) —— 注册一个在会话过期更新发生时要调用的回调。
void setOnExpirationUpdateListener(Executor executor, MediaDrm.OnExpirationUpdateListener listener) —— 注册一个在会话过期更新发生时要调用的回调。
void setOnKeyStatusChangeListener(Executor executor, MediaDrm.OnKeyStatusChangeListener listener) —— 注册一个在会话中密钥状态发生变化时要调用的回调。
void setOnKeyStatusChangeListener(MediaDrm.OnKeyStatusChangeListener listener, Handler handler) —— 注册一个在会话中密钥状态发生变化时要调用的回调，例如发生许可更新或许可过期时。
void setOnSessionLostStateListener(Executor executor, MediaDrm.OnSessionLostStateListener listener) —— 注册一个在会话状态已丢失时要调用的回调。
void setOnSessionLostStateListener(MediaDrm.OnSessionLostStateListener listener, Handler handler) —— 注册一个在会话状态已丢失时要调用的回调。
void setPropertyByteArray(String propertyName, byte[] value) —— 给定属性名字符串和属性的新值，设置一个 MediaDrm 字节数组属性值。
void setPropertyString(String propertyName, String value) —— 给定属性名字符串和属性的新值，设置一个 MediaDrm String 属性值。

受保护的方法（Protected methods）

void finalize() —— 当垃圾回收判定不再有对该对象的引用时，由垃圾回收器在对象上调用。

继承的方法（Inherited methods）

来自 java.lang.Object 类；来自 java.lang.AutoCloseable 接口。

常量

EVENT_KEY_EXPIRED

在 API level 18 中新增。在 API level 26 中废弃。

public static final int EVENT_KEY_EXPIRED

此常量在 API level 26 中已废弃。请改用 OnKeyStatusChangeListener.onKeyStatusChange 并在 MediaDrm.KeyStatus 中检查 MediaDrm.KeyStatus.STATUS_EXPIRED。

此事件类型表明会话中密钥的许可使用时长已过期。密钥不再有效。

常量值：3 (0x00000003)

EVENT_KEY_REQUIRED

在 API level 18 中新增。

public static final int EVENT_KEY_REQUIRED

此事件类型表明 App 需要向许可服务器请求密钥。请求消息数据通过 getKeyRequest(byte, byte, String, int, HashMap) 获取。

常量值：2 (0x00000002)

EVENT_PROVISION_REQUIRED

在 API level 18 中新增。在 API level 23 中废弃。

public static final int EVENT_PROVISION_REQUIRED

此常量在 API level 23 中已废弃。请改为通过 NotProvisionedException 处理 provisioning。

此事件类型表明 App 需要向 provisioning server 请求证书。请求消息数据通过 getProvisionRequest() 获取。

常量值：1 (0x00000001)

EVENT_SESSION_RECLAIMED

在 API level 23 中新增。

public static final int EVENT_SESSION_RECLAIMED

此事件表明 App 打开的一个会话已被资源管理器回收。

常量值：5 (0x00000005)

EVENT_VENDOR_DEFINED

在 API level 18 中新增。

public static final int EVENT_VENDOR_DEFINED

此事件可能表示某种厂商定义的特定状况，详见你的 DRM 提供商文档。

常量值：4 (0x00000004)

HDCP_LEVEL_UNKNOWN

在 API level 28 中新增。

public static final int HDCP_LEVEL_UNKNOWN

DRM 插件未上报 HDCP 级别，或访问它时发生错误。

常量值：0 (0x00000000)

HDCP_NONE

在 API level 28 中新增。

public static final int HDCP_NONE

该设备不支持 HDCP，内容未受保护。

常量值：1 (0x00000001)

HDCP_NO_DIGITAL_OUTPUT

在 API level 28 中新增。

public static final int HDCP_NO_DIGITAL_OUTPUT

无数字输出，隐式安全。

常量值：2147483647 (0x7fffffff)

HDCP_V1

在 API level 28 中新增。

public static final int HDCP_V1

HDCP 1.0 版本。

常量值：2 (0x00000002)

HDCP_V2

在 API level 28 中新增。

public static final int HDCP_V2

HDCP 2.0 Type 1 版本。

常量值：3 (0x00000003)

HDCP_V2_1

在 API level 28 中新增。

public static final int HDCP_V2_1

HDCP 2.1 Type 1 版本。

常量值：4 (0x00000004)

HDCP_V2_2

在 API level 28 中新增。

public static final int HDCP_V2_2

HDCP 2.2 Type 1 版本。

常量值：5 (0x00000005)

HDCP_V2_3

在 API level 29 中新增。

public static final int HDCP_V2_3

HDCP 2.3 Type 1 版本。

常量值：6 (0x00000006)

KEY_TYPE_OFFLINE

在 API level 18 中新增。

public static final int KEY_TYPE_OFFLINE

此密钥请求类型指明密钥将用于离线用途，它们会被保存到设备上，以便设备未连接网络时使用。

常量值：2 (0x00000002)

KEY_TYPE_RELEASE

在 API level 18 中新增。

public static final int KEY_TYPE_RELEASE

此密钥请求类型指明先前保存的离线密钥应被释放。

常量值：3 (0x00000003)

KEY_TYPE_STREAMING

在 API level 18 中新增。

public static final int KEY_TYPE_STREAMING

此密钥请求类型指明密钥将用于在线用途，它们不会被保存到设备上供设备未连接网络时后续使用。

常量值：1 (0x00000001)

OFFLINE_LICENSE_STATE_RELEASED

在 API level 29 中新增。

public static final int OFFLINE_LICENSE_STATE_RELEASED

离线许可已释放，密钥已通过 getKeyRequest(byte, byte, String, int, HashMap) 配合 KEY_TYPE_RELEASE 标记为待释放，但尚未收到密钥响应。

常量值：2 (0x00000002)

OFFLINE_LICENSE_STATE_UNKNOWN

在 API level 29 中新增。

public static final int OFFLINE_LICENSE_STATE_UNKNOWN

离线许可状态未知，尝试访问它时发生了错误。

常量值：0 (0x00000000)

OFFLINE_LICENSE_STATE_USABLE

在 API level 29 中新增。

public static final int OFFLINE_LICENSE_STATE_USABLE

离线许可可用，密钥可用于解密。

常量值：1 (0x00000001)

PROPERTY_ALGORITHMS

在 API level 18 中新增。

public static final String PROPERTY_ALGORITHMS

String 属性名：由 CryptoSession 支持的 cipher 和 mac 算法的逗号分隔列表。如果 DRM 插件不支持 CryptoSession 操作，该列表可能为空。

常量值："algorithms"

PROPERTY_DESCRIPTION

在 API level 18 中新增。

public static final String PROPERTY_DESCRIPTION

String 属性名：描述该 DRM 插件。

常量值："description"

PROPERTY_DEVICE_UNIQUE_ID

在 API level 18 中新增。

public static final String PROPERTY_DEVICE_UNIQUE_ID

Byte array 属性名：设备唯一标识符在设备 provisioning 期间建立，提供一种唯一标识每台设备的方式。

常量值："deviceUniqueId"

PROPERTY_VENDOR

在 API level 18 中新增。

public static final String PROPERTY_VENDOR

String 属性名：标识该 DRM 插件的制造商。

常量值："vendor"

PROPERTY_VERSION

在 API level 18 中新增。

public static final String PROPERTY_VERSION

String 属性名：标识该 DRM 插件的版本。

常量值："version"

SECURITY_LEVEL_HW_SECURE_ALL

在 API level 28 中新增。

public static final int SECURITY_LEVEL_HW_SECURE_ALL

DRM 密钥管理、加密操作、内容解码以及媒体的所有处理（压缩和未压缩）都在由硬件支持的可信执行环境内完成。

常量值：5 (0x00000005)

SECURITY_LEVEL_HW_SECURE_CRYPTO

在 API level 28 中新增。

public static final int SECURITY_LEVEL_HW_SECURE_CRYPTO

DRM 密钥管理和加密操作在由硬件支持的可信执行环境内执行。

常量值：3 (0x00000003)

SECURITY_LEVEL_HW_SECURE_DECODE

在 API level 28 中新增。

public static final int SECURITY_LEVEL_HW_SECURE_DECODE

DRM 密钥管理、加密操作和内容解码在由硬件支持的可信执行环境内执行。

常量值：4 (0x00000004)

SECURITY_LEVEL_SW_SECURE_CRYPTO

在 API level 28 中新增。

public static final int SECURITY_LEVEL_SW_SECURE_CRYPTO

DRM 密钥管理使用基于软件的白盒加密。

常量值：1 (0x00000001)

SECURITY_LEVEL_SW_SECURE_DECODE

在 API level 28 中新增。

public static final int SECURITY_LEVEL_SW_SECURE_DECODE

DRM 密钥管理和解码使用基于软件的白盒加密。

常量值：2 (0x00000002)

SECURITY_LEVEL_UNKNOWN

在 API level 28 中新增。

public static final int SECURITY_LEVEL_UNKNOWN

DRM 插件未上报安全级别，或访问它时发生错误。

常量值：0 (0x00000000)

公开构造函数

MediaDrm

在 API level 18 中新增。

public MediaDrm (UUID uuid)

实例化一个 MediaDrm 对象。

参数：

uuid —— UUID：crypto scheme 的 UUID。该值不能为 null。

抛出：

UnsupportedSchemeException —— 如果设备不支持指定的 scheme UUID。

公开方法

clearOnEventListener

在 API level 29 中新增。

public void clearOnEventListener ()

清除 OnEventListener。

clearOnExpirationUpdateListener

在 API level 29 中新增。

public void clearOnExpirationUpdateListener ()

清除 OnExpirationUpdateListener。

clearOnKeyStatusChangeListener

在 API level 29 中新增。

public void clearOnKeyStatusChangeListener ()

清除 OnKeyStatusChangeListener。

clearOnSessionLostStateListener

在 API level 29 中新增。

public void clearOnSessionLostStateListener ()

清除 OnSessionLostStateListener。

close

在 API level 28 中新增。

public void close ()

释放与 MediaDrm 当前会话关联的资源。当你的应用程序不再需要该 MediaDrm 对象时，调用此方法被认为是良好实践。调用此方法后，MediaDrm 不再可用，因为它已丢失其全部所需资源。此方法在 API 28 中新增。在 API 版本 18 到 27 中，应改为调用 release()。对于 API 版本 18 之前的情况，无需做任何操作。

closeSession

在 API level 18 中新增。

public void closeSession (byte[] sessionId)

关闭 MediaDrm 对象上先前用 openSession() 打开的会话。

参数：

sessionId —— byte：该值不能为 null。

getConnectedHdcpLevel

在 API level 28 中新增。

public int getConnectedHdcpLevel ()

返回与设备所连接的下游接收器协商得到的 HDCP 级别。如果同时有多个支持 HDCP 的显示器连接到不同的接口，此方法返回所有接口中协商得到的最低级别。

此方法应仅用于信息性目的，不应用于强制执行对 HDCP 要求的合规。对 HDCP 策略的可信强制执行必须由 DRM 系统处理。

int：所连接的 HDCP 级别。取值为以下之一：HDCP_LEVEL_UNKNOWN、HDCP_NONE、HDCP_V1、HDCP_V2、HDCP_V2_1、HDCP_V2_2、HDCP_V2_3、HDCP_NO_DIGITAL_OUTPUT。

getCryptoSession

在 API level 18 中新增。

public MediaDrm.CryptoSession getCryptoSession (byte[] sessionId, 
                String cipherAlgorithm, 
                String macAlgorithm)

获取一个 CryptoSession 对象，可用于使用通过 getKeyRequest(byte, byte, String, int, HashMap) 和 provideKeyResponse(byte, byte) 借助会话密钥服务器为该会话建立的会话密钥，来加密、解密、签名和验证消息或数据。

参数：

sessionId —— byte：包含将用于加密、解密、签名和/或验证的密钥的会话的会话 ID。该值不能为 null。
cipherAlgorithm —— String：用于加密和解密 cipher 的算法。算法字符串遵循 JCA Standard Names for Cipher Transforms，且不区分大小写。例如 "AES/CBC/NoPadding"。该值不能为 null。
macAlgorithm —— String：用于签名和验证的算法。算法字符串遵循 JCA Standard Names for Mac Algorithms，且不区分大小写。例如 "HmacSHA256"。

某 DRM 插件所支持算法的列表，可通过方法 getPropertyString(String) 并传入属性名 "algorithms" 来获取。该值不能为 null。

MediaDrm.CryptoSession

getKeyRequest

在 API level 18 中新增。

public MediaDrm.KeyRequest getKeyRequest (byte[] scope, 
                byte[] init, 
                String mimeType, 
                int keyType, 
                HashMap<String, String> optionalParameters)

在 App 与许可服务器之间发生一次密钥请求/响应交换，以获取或释放用于解密加密内容的密钥。

getKeyRequest() 用于获取一个不透明的密钥请求字节数组，它被交付给许可服务器。该不透明的密钥请求字节数组在 KeyRequest.data 中返回。用于交付该密钥请求的推荐 URL 在 KeyRequest.defaultUrl 中返回。

在 App 从服务器收到密钥请求响应后，它应使用 provideKeyResponse(byte, byte) 方法把该响应交付给 MediaDrm 实例。

参数：

scope —— byte：可以是 sessionId 或 keySetId，取决于指定的 keyType。当 keyType 为 KEY_TYPE_STREAMING 或 KEY_TYPE_OFFLINE 时，scope 应设为密钥将被提供给的那个 sessionId。当 keyType 为 KEY_TYPE_RELEASE 时，scope 应设为正在被释放的密钥的 keySetId。从设备释放密钥会使它们对所有会话都失效。该值不能为 null。
init —— byte：容器特定的数据，其含义依据 mimeType 参数中提供的 mime 类型来解释。例如，它可能包含生成密钥请求所需的内容 ID、密钥 ID 或从内容元数据中获取的其他数据。当 keyType 为 KEY_TYPE_RELEASE 时，或当该请求是一次续期（即并非该会话的首次密钥请求）时，可以为 null。
mimeType —— String：标识内容的 mime 类型。如果 keyType 为 KEY_TYPE_RELEASE，或该请求是一次续期（即并非该会话的首次密钥请求），则可以为 null。
keyType —— int：指定请求的类型。请求可能是获取用于串流或离线内容的密钥，或释放先前获取的、由 keySetId 标识的密钥。取值为以下之一：KEY_TYPE_STREAMING、KEY_TYPE_OFFLINE、KEY_TYPE_RELEASE。
optionalParameters —— HashMap：被包含在密钥请求消息中，以允许客户端应用程序向服务器提供额外的消息参数。如果无需发送额外参数，则可以为 null。

MediaDrm.KeyRequest：该值不能为 null。

抛出：

NotProvisionedException —— 如果由于证书问题而需要重新 provisioning。

getLogMessages

在 API level 31 中新增。

public List<MediaDrm.LogMessage> getLogMessages ()

返回与此 MediaDrm 实例关联的近期 LogMessage。

List<MediaDrm.LogMessage>：该值不能为 null。

getMaxHdcpLevel

在 API level 28 中新增。

public int getMaxHdcpLevel ()

返回支持的最大 HDCP 级别。最大 HDCP 级别对某给定设备是一个常量，它不取决于可能连接的下游接收器。如果存在多个支持 HDCP 的接口，它表示所有接口最大 HDCP 级别中的最高者。

int：支持的最大 HDCP 级别。取值为以下之一：HDCP_LEVEL_UNKNOWN、HDCP_NONE、HDCP_V1、HDCP_V2、HDCP_V2_1、HDCP_V2_2、HDCP_V2_3、HDCP_NO_DIGITAL_OUTPUT。

getMaxSecurityLevel

在 API level 28 中新增。

public static int getMaxSecurityLevel ()

返回一个值，可作为参数传给 openSession(int)，请求以设备的最高安全级别打开会话。此安全级别仅对运行在物理 Android 设备（例如 Context.DEVICE_ID_DEFAULT）上的应用程序有效。当运行在 VirtualDevice 上时，支持的最高安全级别可能不同。

getMaxSessionCount

在 API level 28 中新增。

public int getMaxSessionCount ()

返回针对当前 DRM 方案，所有 MediaDrm 实例之间可同时打开的最大 MediaDrm 会话数。该最大会话数不受可能已经打开的任何会话的影响。

int：最大会话数。

getMetrics

在 API level 28 中新增。

public PersistableBundle getMetrics ()

返回关于当前 MediaDrm 实例的 Metrics 数据。

PersistableBundle：一个 PersistableBundle，包含此 MediaDrm 实例可用的属性与值集合。这些属性在 MetricsConstants 中描述。返回值中还可能存在额外的厂商特定字段。

getOfflineLicenseKeySetIds

在 API level 29 中新增。

public List<byte[]> getOfflineLicenseKeySetIds ()

离线许可中的密钥允许设备即使未连接网络也能播放受保护内容。当密钥请求的 KeyType 为 OFFLINE 时，离线许可在一次密钥请求/响应交换之后被存储在设备上。通常每个 App 负责追踪它已创建的 keySetId。然而，如果 App 丢失了它创建的某个已存储许可的 keySetId，它必须能够恢复已存储的 keySetId，以便这些许可在过期或 App 被卸载时能被移除。

此方法返回所有离线许可的 keySetId 列表。离线许可的 keySetId 可用于通过 getOfflineLicenseState(byte) 查询离线许可的状态，或通过 removeOfflineLicense(byte) 移除它。

List<byte[]>：离线许可 keySetId 的列表。该值不能为 null。

getOfflineLicenseState

在 API level 29 中新增。

public int getOfflineLicenseState (byte[] keySetId)

请求离线许可的状态。离线许可可能是可用的或非活动的。可用离线许可中的密钥可用于解密。当离线许可状态为非活动时，密钥已通过 getKeyRequest(byte, byte, String, int, HashMap) 配合 KEY_TYPE_RELEASE 标记为待释放，但尚未收到密钥响应。非活动离线许可中的密钥不可用于解密。

参数：

keySetId —— byte：选择该离线许可。该值不能为 null。

int：离线许可状态。取值为以下之一：OFFLINE_LICENSE_STATE_UNKNOWN、OFFLINE_LICENSE_STATE_USABLE、OFFLINE_LICENSE_STATE_RELEASED。

抛出：

IllegalArgumentException —— 如果 keySetId 指向的不是一个离线许可。

getOpenSessionCount

在 API level 28 中新增。

public int getOpenSessionCount ()

返回针对当前 DRM 方案，所有 MediaDrm 实例之间当前同时打开的 MediaDrm 会话数。

int：打开会话的数量。

getPlaybackComponent

在 API level 31 中新增。

public MediaDrm.PlaybackComponent getPlaybackComponent (byte[] sessionId)

获取与某个 DRM 会话关联的 PlaybackComponent。在返回的对象上调用 PlaybackComponent.setLogSessionId(LogSessionId)，以把一次播放会话与 DRM 会话关联起来。

参数：

sessionId —— byte：从 openSession() 获得的 DRM 会话 ID。该值不能为 null。

MediaDrm.PlaybackComponent：与该会话关联的 PlaybackComponent，如果该会话已关闭或不存在则为 null。

另见：PlaybackComponent

getPropertyByteArray

在 API level 18 中新增。

public byte[] getPropertyByteArray (String propertyName)

给定属性名字符串，读取一个 MediaDrm 字节数组属性值。

标准字段名为 PROPERTY_DEVICE_UNIQUE_ID。

参数：

propertyName —— String

byte[]：该值不能为 null。

getPropertyString

在 API level 18 中新增。

public String getPropertyString (String propertyName)

给定属性名字符串，读取一个 MediaDrm String 属性值。

标准字段名为：PROPERTY_VENDOR、PROPERTY_VERSION、PROPERTY_DESCRIPTION、PROPERTY_ALGORITHMS。

参数：

propertyName —— String：该值不能为 null。

String：该值不能为 null。

getProvisionRequest

在 API level 18 中新增。

public MediaDrm.ProvisionRequest getProvisionRequest ()

在 App 与 provisioning server 之间发生一次 provision 请求/响应交换，以获取设备证书。如果需要 provisioning，EVENT_PROVISION_REQUIRED 事件会被发送给事件处理器。getProvisionRequest 用于获取应交付给 provisioning server 的不透明 provision 请求字节数组。该 provision 请求字节数组在 ProvisionRequest.data 中返回。用于交付该 provision 请求的推荐 URL 在 ProvisionRequest.defaultUrl 中返回。

MediaDrm.ProvisionRequest：该值不能为 null。

getSecureStop

在 API level 22 中新增。在 API level 33 中废弃。

public byte[] getSecureStop (byte[] ssid)

此方法在 API level 33 中已废弃。此方法已废弃，可能在未来的版本中被移除。请改为通过调用 getKeyRequest(byte, byte, String, int, HashMap) 进行续期来追踪并发播放。更多信息见 getSecureStops()。

给定其 secure stop ID，访问一个特定的 secure stop。每个 secure stop 都有一个唯一的 ID。

参数：

ssid —— byte：要返回的 secure stop 的 ID。该值不能为 null。

byte[]：由 ssid 标识的 secure stop。该值不能为 null。

getSecureStopIds

在 API level 28 中新增。在 API level 33 中废弃。

public List<byte[]> getSecureStopIds ()

此方法在 API level 33 中已废弃。（同上，改用续期。）

返回当前位于持久内存中的所有 secure stop ID 的列表。secure stop ID 可用于访问或移除相应的 secure stop。

List<byte[]>：secure stop ID 的列表。该值不能为 null。

getSecureStops

在 API level 18 中新增。在 API level 33 中废弃。

public List<byte[]> getSecureStops ()

此方法在 API level 33 中已废弃。此方法已废弃，可能在未来的版本中被移除。secure stop 是一种跨设备对每个订阅者的并发流数量强制限制的方式。它们对 MediaDrm 会话中内容解密密钥的生命周期提供安全监控。对并发流的限制也可以通过定期续期许可来强制执行。这可通过调用 getKeyRequest(byte, byte, String, int, HashMap) 发起一次续期来实现。MediaDrm 用户应从 secure stop 迁移到定期续期。

secure stop 是一种跨设备对每个订阅者的并发流数量强制限制的方式。它们对 MediaDrm 会话中内容解密密钥的生命周期提供安全监控。

当密钥被加载到一个 MediaDrm 会话时，一个 secure stop 会被写入安全持久内存。secure stop 状态表明密钥可供使用。当播放完成且密钥被移除或会话被销毁时，secure stop 状态会被更新以表明密钥不再可用。

播放之后，App 可以查询该 secure stop 并把它放在一条消息中发送给许可服务器，确认密钥不再活动。许可服务器向 App 返回一条 secure stop 释放响应消息，App 随后使用 releaseSecureStops(byte) 从持久内存中删除该 secure stop。

每个 secure stop 都有一个唯一的 ID，可用于在枚举、访问和移除期间标识它。

List<byte[]>：来自安全持久内存的所有 secure stop 的列表。该值不能为 null。

getSecurityLevel

在 API level 28 中新增。

public int getSecurityLevel (byte[] sessionId)

返回会话当前的安全级别。一个会话具有一个初始安全级别，它由设备上 DRM 系统实现的健壮性决定。安全级别可以在会话通过 openSession() 打开时被更改。

参数：

sessionId —— byte：要查询的会话。该值不能为 null。

int：会话的安全级别。取值为以下之一：SECURITY_LEVEL_UNKNOWN、SECURITY_LEVEL_SW_SECURE_CRYPTO、SECURITY_LEVEL_SW_SECURE_DECODE、SECURITY_LEVEL_HW_SECURE_CRYPTO、SECURITY_LEVEL_HW_SECURE_DECODE、SECURITY_LEVEL_HW_SECURE_ALL。

getSupportedCryptoSchemes

在 API level 30 中新增。

public static List<UUID> getSupportedCryptoSchemes ()

List<UUID>：使 isCryptoSchemeSupported(UUID) 返回 true 的 crypto scheme（以 UUID 表示）的列表；每个 UUID 都可作为输入，通过 MediaDrm(UUID) 创建 MediaDrm 对象。该值不能为 null。

isCryptoSchemeSupported

在 API level 19 中新增。

public static boolean isCryptoSchemeSupported (UUID uuid, 
                String mimeType)

查询由 UUID 标识的给定方案是否在此设备上受支持，以及 DRM 插件是否能处理由 mimeType 指定的媒体容器格式。

参数：

uuid —— UUID：crypto scheme 的 UUID。该值不能为 null。
mimeType —— String：媒体容器的 MIME 类型，例如 "video/mp4" 或 "video/webm"。该值不能为 null。

boolean

isCryptoSchemeSupported

在 API level 29 中新增。

public static boolean isCryptoSchemeSupported (UUID uuid, 
                String mimeType, 
                int securityLevel)

查询由 UUID 标识的给定方案是否在此设备上受支持，以及 DRM 插件是否能在所请求的安全级别下处理由 mimeType 指定的媒体容器格式。当应用程序运行在物理 Android 设备或 VirtualDevice 上时调用此方法，可能因设备 DRM 能力不同而导致不同结果。

参数：

uuid —— UUID：crypto scheme 的 UUID。该值不能为 null。
mimeType —— String：媒体容器的 MIME 类型，例如 "video/mp4" 或 "video/webm"。该值不能为 null。
securityLevel —— int：所请求的安全级别。取值为以下之一：SECURITY_LEVEL_UNKNOWN、SECURITY_LEVEL_SW_SECURE_CRYPTO、SECURITY_LEVEL_SW_SECURE_DECODE、SECURITY_LEVEL_HW_SECURE_CRYPTO、SECURITY_LEVEL_HW_SECURE_DECODE、SECURITY_LEVEL_HW_SECURE_ALL。

boolean

isCryptoSchemeSupported

在 API level 18 中新增。

public static boolean isCryptoSchemeSupported (UUID uuid)

查询由 UUID 标识的给定方案是否在此设备上受支持。

参数：

uuid —— UUID：crypto scheme 的 UUID。该值不能为 null。

boolean

openSession

在 API level 18 中新增。

public byte[] openSession ()

打开一个与 MediaDrm 对象的新会话。返回一个会话 ID。默认情况下，会话以设备原生安全级别打开。如果应用程序当前运行在 VirtualDevice 上，安全级别将相应调整为该显示器支持的最高级别。

byte[]：该值不能为 null。

抛出：

NotProvisionedException —— 如果需要 provisioning。
ResourceBusyException —— 如果所需资源正在使用中。

openSession

在 API level 28 中新增。

public byte[] openSession (int level)

在所请求的安全级别上打开一个新会话。安全级别表示设备 DRM 实现的健壮性。默认情况下，会话以设备原生安全级别打开。当解密后的帧需要被操作（例如用于图像合成）时，覆盖安全级别是必要的。安全级别参数必须低于原生级别。降低安全级别通常会依据许可策略把内容限制到较低分辨率。如果所请求的级别不受支持，则会设置为下一个较低的受支持安全级别。该级别可通过 getSecurityLevel(byte) 查询。返回一个会话 ID。如果应用程序当前运行在 VirtualDevice 上，安全级别将相应调整为该显示器支持的最高级别。

参数：

level —— int：新的安全级别。取值为以下之一：SECURITY_LEVEL_UNKNOWN、SECURITY_LEVEL_SW_SECURE_CRYPTO、SECURITY_LEVEL_SW_SECURE_DECODE、SECURITY_LEVEL_HW_SECURE_CRYPTO、SECURITY_LEVEL_HW_SECURE_DECODE、SECURITY_LEVEL_HW_SECURE_ALL。

byte[]：该值不能为 null。

抛出：

NotProvisionedException —— 如果需要 provisioning。
ResourceBusyException —— 如果所需资源正在使用中。
IllegalArgumentException —— 如果所请求的安全级别高于原生级别、或低于支持的最低级别，或如果设备不支持在打开会话时指定安全级别。

provideKeyResponse

在 API level 18 中新增。

public byte[] provideKeyResponse (byte[] scope, 
                byte[] response)

App 从许可服务器收到密钥响应后，使用 provideKeyResponse 把它提供给 MediaDrm 实例。当该响应针对一次离线密钥请求时，会返回一个 keySetId，之后可用方法 restoreKeys(byte, byte) 用它把密钥恢复到新会话中。当该响应针对一次串流或释放请求时，返回一个空字节数组。

参数：

scope —— byte：可以是 sessionId 或 keySetId，取决于响应的类型。当响应针对串流或离线密钥请求时，scope 应设为 sessionId。当响应针对释放请求时，scope 应设为 keySetId。该值不能为 null。
response —— byte：来自服务器的字节数组响应。该值不能为 null。

byte[]：如果响应针对一次离线请求，将返回离线密钥的 keySetId。如果响应针对一次串流或释放请求，将返回一个空字节数组。该值可能为 null。

抛出：

DeniedByServerException —— 如果响应表明服务器拒绝了该请求。
NotProvisionedException —— 如果响应表明需要重新 provisioning。

provideProvisionResponse

在 API level 18 中新增。

public void provideProvisionResponse (byte[] response)

App 收到 provision 响应后，使用此方法把它提供给 MediaDrm 实例。

参数：

response —— byte：要提供给 MediaDrm 实例的不透明 provisioning 响应字节数组。该值不能为 null。

抛出：

DeniedByServerException —— 如果响应表明服务器拒绝了该请求。

queryKeyStatus

在 API level 18 中新增。

public HashMap<String, String> queryKeyStatus (byte[] sessionId)

请求对该会话密钥状态的信息性描述。状态以 {name, value} 对的形式表示。由于 DRM 许可策略因厂商而异，具体状态字段名由各 DRM 厂商确定。关于某特定 DRM 插件的字段名定义，请参阅你的 DRM 提供商文档。

参数：

sessionId —— byte：该 DRM 会话的会话 ID。该值不能为 null。

HashMap<String, String>：该值不能为 null。

release

在 API level 18 中新增。在 API level 28 中废弃。

public void release ()

此方法在 API level 28 中已废弃。由 close() 取代。

releaseAllSecureStops

在 API level 22 中新增。在 API level 28 中废弃。

public void releaseAllSecureStops ()

此方法在 API level 28 中已废弃。请改用 removeAllSecureStops() 移除所有 secure stop。

无需来自许可服务器的 secure stop 释放消息，即移除所有 secure stop。

releaseSecureStops

在 API level 18 中新增。在 API level 33 中废弃。

public void releaseSecureStops (byte[] ssRelease)

此方法在 API level 33 中已废弃。（同上，改用续期。）

处理 secure stop 服务器响应消息 ssRelease。在认证该消息之后，移除响应中标识的 secure stop。

参数：

ssRelease —— byte：表明要释放哪些 secure stop 的服务器响应。该值不能为 null。

removeAllSecureStops

在 API level 28 中新增。在 API level 33 中废弃。

public void removeAllSecureStops ()

此方法在 API level 33 中已废弃。（同上，改用续期。）

无需来自许可服务器的 secure stop 释放消息，即移除所有 secure stop。此方法在 API 28 中新增。在 API 版本 18 到 27 中，应改为调用 releaseAllSecureStops()。对于 API 版本 18 之前的情况，无需做任何操作。

removeKeys

在 API level 18 中新增。

public void removeKeys (byte[] sessionId)

从会话中移除当前密钥。

参数：

sessionId —— byte：该 DRM 会话的会话 ID。该值不能为 null。

removeOfflineLicense

在 API level 29 中新增。

public void removeOfflineLicense (byte[] keySetId)

通常离线许可通过一次密钥请求/响应交换来释放，该交换使用 getKeyRequest(byte, byte, String, int, HashMap)（密钥类型为 KEY_TYPE_RELEASE），随后接 provideKeyResponse(byte, byte)。这允许服务器以密码学方式确认该许可已被移除，然后调整分配给该设备的离线许可数量。

在某些例外情况下，可能有必要在不通知服务器的情况下直接移除离线许可，这可以使用此方法执行。

参数：

keySetId —— byte：要移除的离线许可的 id。该值不能为 null。

抛出：

IllegalArgumentException —— 如果 keySetId 指向的不是一个离线许可。

removeSecureStop

在 API level 28 中新增。在 API level 33 中废弃。

public void removeSecureStop (byte[] ssid)

此方法在 API level 33 中已废弃。（同上，改用续期。）

无需来自许可服务器的 secure stop 释放消息，即移除一个特定的 secure stop。

参数：

ssid —— byte：要移除的 secure stop 的 ID。该值不能为 null。

requiresSecureDecoder

在 API level 31 中新增。

public boolean requiresSecureDecoder (String mime)

查询该 crypto scheme 是否要求使用安全解码器来在默认安全级别下解码给定 mime 类型的数据。默认安全级别定义为该设备支持的最高安全级别。

参数：

mime —— String：媒体数据的 mime 类型。请使用 isCryptoSchemeSupported(UUID,String) 单独查询 mime 类型支持情况；对于不受支持的 mime 类型，requiresSecureDecoder(String) 的返回值取决于 crypto scheme。该值不能为 null。

boolean

requiresSecureDecoder

在 API level 31 中新增。

public boolean requiresSecureDecoder (String mime, 
                int level)

查询该 crypto scheme 是否要求使用安全解码器来在给定安全级别下解码给定 mime 类型的数据。

参数：

mime —— String：媒体数据的 mime 类型。请使用 isCryptoSchemeSupported(UUID,String,int) 单独查询 mime 类型支持情况；对于不受支持的 mime 类型，requiresSecureDecoder(String,int) 的返回值取决于 crypto scheme。该值不能为 null。
level —— int：一个介于 SECURITY_LEVEL_SW_SECURE_CRYPTO 与 SECURITY_LEVEL_HW_SECURE_ALL 之间的安全级别。此外，也允许特殊值 getMaxSecurityLevel()；使用 getMaxSecurityLevel() 表示该设备支持的最高安全级别。取值为以下之一：SECURITY_LEVEL_UNKNOWN、SECURITY_LEVEL_SW_SECURE_CRYPTO、SECURITY_LEVEL_SW_SECURE_DECODE、SECURITY_LEVEL_HW_SECURE_CRYPTO、SECURITY_LEVEL_HW_SECURE_DECODE、SECURITY_LEVEL_HW_SECURE_ALL。

boolean

抛出：

IllegalArgumentException —— 如果所请求的安全级别不属于参数 level 的文档化取值。

restoreKeys

在 API level 18 中新增。

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

把持久化的离线密钥恢复到新会话中。keySetId 标识要加载的密钥，来自先前一次对 provideKeyResponse(byte, byte) 的调用。

参数：

sessionId —— byte：该 DRM 会话的会话 ID。该值不能为 null。
keySetId —— byte：标识要恢复的已保存密钥集。该值不能为 null。

setOnEventListener

在 API level 29 中新增。

public void setOnEventListener (Executor executor, 
                MediaDrm.OnEventListener listener)

注册一个在事件发生时要调用的回调。

参数：

executor —— Executor：应通过其调用该监听器的 executor。该值不能为 null。回调和监听器事件通过此 Executor 分派，提供一种控制使用哪个线程的简便方式。要通过你的应用程序的主线程分派事件，你可以使用 Context.getMainExecutor()。否则，请提供一个分派到合适线程的 Executor。
listener —— MediaDrm.OnEventListener：将要运行的回调。该值不能为 null。

另见：setOnEventListener(OnEventListener)

setOnEventListener

在 API level 29 中新增。

public void setOnEventListener (MediaDrm.OnEventListener listener, 
                Handler handler)

注册一个在事件发生时要调用的回调。

参数：

listener —— MediaDrm.OnEventListener：将要运行的回调。使用 null 停止接收事件回调。
handler —— Handler：应在其上调用该监听器的 handler；如果应在调用线程的 looper 上调用该监听器，则为 null。

setOnEventListener

在 API level 18 中新增。

public void setOnEventListener (MediaDrm.OnEventListener listener)

注册一个在事件发生时要调用的回调。

参数：

listener —— MediaDrm.OnEventListener：将要运行的回调。使用 null 停止接收事件回调。

另见：setOnEventListener(OnEventListener,Handler)

setOnExpirationUpdateListener

在 API level 23 中新增。

public void setOnExpirationUpdateListener (MediaDrm.OnExpirationUpdateListener listener, 
                Handler handler)

注册一个在会话过期更新发生时要调用的回调。当会话中密钥的过期时间发生变化时，App 的 OnExpirationUpdateListener 将收到通知。

参数：

listener —— MediaDrm.OnExpirationUpdateListener：将要运行的回调，或 null 以注销先前注册的回调。
handler —— Handler：应在其上调用该监听器的 handler；如果应在调用线程的 looper 上调用该监听器，则为 null。

setOnExpirationUpdateListener

在 API level 29 中新增。

public void setOnExpirationUpdateListener (Executor executor, 
                MediaDrm.OnExpirationUpdateListener listener)

注册一个在会话过期更新发生时要调用的回调。

参数：

executor —— Executor：应通过其调用该监听器的 executor。该值不能为 null。（同上，可通过 Context.getMainExecutor() 在主线程分派。）
listener —— MediaDrm.OnExpirationUpdateListener：将要运行的回调。该值不能为 null。

另见：setOnExpirationUpdateListener(OnExpirationUpdateListener,Handler)

setOnKeyStatusChangeListener

在 API level 29 中新增。

public void setOnKeyStatusChangeListener (Executor executor, 
                MediaDrm.OnKeyStatusChangeListener listener)

注册一个在会话中密钥状态发生变化时要调用的回调。

参数：

executor —— Executor：应在其上调用该监听器的 executor。该值不能为 null。（同上，可通过 Context.getMainExecutor() 在主线程分派。）
listener —— MediaDrm.OnKeyStatusChangeListener：密钥状态变化时要运行的回调。该值不能为 null。

另见：setOnKeyStatusChangeListener(OnKeyStatusChangeListener,Handler)

setOnKeyStatusChangeListener

在 API level 23 中新增。

public void setOnKeyStatusChangeListener (MediaDrm.OnKeyStatusChangeListener listener, 
                Handler handler)

注册一个在会话中密钥状态发生变化时要调用的回调，例如发生许可更新或许可过期时。

参数：

listener —— MediaDrm.OnKeyStatusChangeListener：密钥状态变化时要运行的回调，或 null 以注销先前注册的回调。
handler —— Handler：应在其上调用该监听器的 handler；如果应在调用线程的 looper 上调用该监听器，则为 null。

setOnSessionLostStateListener

在 API level 29 中新增。

public void setOnSessionLostStateListener (Executor executor, 
                MediaDrm.OnSessionLostStateListener listener)

注册一个在会话状态已丢失时要调用的回调。

参数：

executor —— Executor：应在其上调用该监听器的 executor。该值不能为 null。（同上，可通过 Context.getMainExecutor() 在主线程分派。）
listener —— MediaDrm.OnSessionLostStateListener：将要运行的回调。该值可能为 null。

另见：setOnSessionLostStateListener(OnSessionLostStateListener,Handler)

setOnSessionLostStateListener

在 API level 29 中新增。

public void setOnSessionLostStateListener (MediaDrm.OnSessionLostStateListener listener, 
                Handler handler)

注册一个在会话状态已丢失时要调用的回调。此事件可能发生在无法跨设备挂起/恢复周期保留 crypto 会话状态的设备上。当此事件发生时，必须关闭该会话并打开一个新会话来恢复操作。

参数：

listener —— MediaDrm.OnSessionLostStateListener：将要运行的回调，或 null 以注销先前注册的回调。
handler —— Handler：应在其上调用该监听器的 handler；如果应在调用线程的 looper 上调用该监听器，则为 null。

setPropertyByteArray

在 API level 18 中新增。

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

给定属性名字符串和属性的新值，设置一个 MediaDrm 字节数组属性值。

参数：

propertyName —— String：该值不能为 null。
value —— byte：该值不能为 null。

setPropertyString

在 API level 18 中新增。

public void setPropertyString (String propertyName, 
                String value)

给定属性名字符串和属性的新值，设置一个 MediaDrm String 属性值。

参数：

propertyName —— String：该值不能为 null。
value —— String：该值不能为 null。

受保护的方法

finalize

在 API level 18 中新增。

protected void finalize ()

当垃圾回收判定不再有对该对象的引用时，由垃圾回收器在对象上调用。子类重写 finalize 方法以释放系统资源或执行其他清理。

finalize 的通用契约是：当且仅当 Java 虚拟机已判定，除因某个其他已准备好被终结的对象或类被终结而采取的操作之外，不再有任何手段能让尚未终止的线程访问该对象时，它会被调用。finalize 方法可以采取任何操作，包括使该对象再次对其他线程可用；然而，finalize 的通常目的是在对象被不可挽回地丢弃之前执行清理操作。例如，一个表示输入/输出连接的对象，其 finalize 方法可能执行显式 I/O 事务，以便在对象被永久丢弃之前断开连接。

类 Object 的 finalize 方法不执行任何特殊操作；它只是正常返回。Object 的子类可以重写此定义。

Java 编程语言不保证哪个线程会为任何给定对象调用 finalize 方法。但保证：调用 finalize 的线程在 finalize 被调用时不持有任何用户可见的同步锁。如果 finalize 方法抛出一个未捕获的异常，该异常会被忽略，且该对象的终结终止。

在对某对象调用 finalize 方法之后，直到 Java 虚拟机再次判定不再有任何手段能让尚未终止的线程访问该对象（包括可能由其他已准备好被终结的对象或类采取的操作）时，才会采取进一步操作，此时该对象可能被丢弃。

对于任何给定对象，Java 虚拟机绝不会对 finalize 方法调用超过一次。

finalize 方法抛出的任何异常都会导致此对象的终结被中止，但除此之外会被忽略。

抛出：

Throwable

本页内容与代码示例受「Content License」中所述许可的约束。Java 和 OpenJDK 是 Oracle 和/或其关联公司的商标或注册商标。

最后更新于 2026-10-08 UTC。

Skip to main content
Essentials
Design & Plan
Develop
Google Play
Blog
More
Android Studio
Sign in
API REFERENCE
Android API Reference
Overview
Android Platform
Packages
API level
REL
37.2
37.1
37
36.1
36
35
34
33
32
31
30
29
28
27
26
25
24
23
22
21
20
19
18
17
16
15
14
13
12
11
10
9
8
7
6
5
4
3
2
1
Class Index
Package Index
android
android.accessibilityservice
android.accounts
android.adservices
android.adservices.adid
android.adservices.adselection
android.adservices.appsetid
android.adservices.common
android.adservices.customaudience
android.adservices.exceptions
android.adservices.measurement
android.adservices.ondevicepersonalization
android.adservices.signals
android.adservices.topics
android.agenticon
android.animation
android.annotation
android.app
android.app.admin
android.app.admin.policy
android.app.appfunctions
android.app.appsearch
android.app.appsearch.exceptions
android.app.appsearch.observer
android.app.appsearch.util
android.app.assist
android.app.backup
android.app.blob
android.app.contentsafety
android.app.jank
android.app.job
android.app.people
android.app.permissionui
android.app.personalcontext
android.app.personalcontext.hint
android.app.personalcontext.insight
android.app.personalcontext.insight.interaction
android.app.personalcontext.understander
android.app.privatecompute
android.app.role
android.app.sdksandbox
android.app.sdksandbox.sdkprovider
android.app.slice
android.app.time
android.app.usage
android.app.voiceinteraction
android.app.wallpaper
android.appwidget
android.bluetooth
android.bluetooth.le
android.companion
android.companion.virtual
android.content
android.content.om
android.content.pm
android.content.pm.verify.domain
android.content.pm.webapp
android.content.res
android.content.res.loader
android.credentials
android.crypto.hpke
android.database
android.database.sqlite
android.devicelock
android.drm
android.gesture
android.graphics
android.graphics.drawable
android.graphics.drawable.shapes
android.graphics.fonts
android.graphics.pdf
android.graphics.pdf.component
android.graphics.pdf.content
android.graphics.pdf.models
android.graphics.pdf.models.selection
android.graphics.text
android.hardware
android.hardware.biometrics
android.hardware.camera2
android.hardware.camera2.params
android.hardware.display
android.hardware.hid
android.hardware.input
android.hardware.lights
android.hardware.serial
android.hardware.usb
android.health.connect
android.health.connect.changelog
android.health.connect.datatypes
android.health.connect.datatypes.units
android.icu.lang
android.icu.math
android.icu.number
android.icu.text
android.icu.util
android.inputmethodservice
android.location
android.location.altitude
android.location.provider
android.media
Overview
Interfaces
Classes
ApplicationMediaCapabilities
ApplicationMediaCapabilities.Builder
AsyncPlayer
AudioAttributes
AudioAttributes.Builder
AudioDescriptor
AudioDeviceCallback
AudioDeviceInfo
AudioFocusRequest
AudioFocusRequest.Builder
AudioFormat
AudioFormat.Builder
AudioManager
AudioManager.AudioPlaybackCallback
AudioManager.AudioRecordingCallback
AudioMetadata
AudioMetadata.Format
AudioMixerAttributes
AudioMixerAttributes.Builder
AudioPlaybackCaptureConfiguration
AudioPlaybackCaptureConfiguration.Builder
AudioPlaybackConfiguration
AudioPresentation
AudioPresentation.Builder
AudioProfile
AudioRecord
AudioRecord.Builder
AudioRecord.MetricsConstants
AudioRecordingConfiguration
AudioTimestamp
AudioTrack
AudioTrack.Builder
AudioTrack.MetricsConstants
AudioTrack.StreamEventCallback
CamcorderProfile
CameraProfile
DrmInitData
DrmInitData.SchemeInitData
EncoderProfiles
EncoderProfiles.AudioProfile
EncoderProfiles.VideoProfile
ExifInterface
FaceDetector
FaceDetector.Face
Image
Image.Plane
ImageReader
ImageReader.Builder
ImageWriter
ImageWriter.Builder
JetPlayer
LoudnessCodecController
MediaActionSound
MediaCas
MediaCas.PluginDescriptor
MediaCas.Session
MediaCodec
MediaCodec.BufferInfo
MediaCodec.Callback
MediaCodec.CryptoInfo
MediaCodec.CryptoInfo.Pattern
MediaCodec.LinearBlock
MediaCodec.MetricsConstants
MediaCodec.OutputFrame
MediaCodec.ParameterDescriptor
MediaCodec.QueueRequest
MediaCodecInfo
MediaCodecInfo.AudioCapabilities
MediaCodecInfo.CodecCapabilities
MediaCodecInfo.CodecProfileLevel
MediaCodecInfo.EncoderCapabilities
MediaCodecInfo.VideoCapabilities
MediaCodecInfo.VideoCapabilities.PerformancePoint
MediaCodecList
MediaCommunicationManager
MediaController2
MediaController2.Builder
MediaController2.ControllerCallback
MediaCrypto
MediaDataSource
MediaDescrambler
MediaDescription
MediaDescription.Builder
MediaDrm
MediaDrm.CryptoSession
MediaDrm.ErrorCodes
MediaDrm.KeyRequest
MediaDrm.KeyStatus
MediaDrm.LogMessage
MediaDrm.MetricsConstants
MediaDrm.PlaybackComponent
MediaDrm.ProvisionRequest
MediaExtractor
MediaExtractor.CasInfo
MediaExtractor.MetricsConstants
MediaFeature
MediaFeature.HdrType
MediaFormat
MediaFormat.QpOffsetRect
MediaMetadata
MediaMetadata.Builder
MediaMetadataEditor
MediaMetadataRetriever
MediaMetadataRetriever.BitmapParams
MediaMuxer
MediaMuxer.OutputFormat
MediaParser
MediaParser.SeekMap
MediaParser.SeekPoint
MediaParser.TrackData
MediaPlayer
MediaPlayer.DrmInfo
MediaPlayer.MetricsConstants
MediaPlayer.TrackInfo
MediaRecorder
MediaRecorder.AudioEncoder
MediaRecorder.AudioSource
MediaRecorder.MetricsConstants
MediaRecorder.OutputFormat
MediaRecorder.VideoEncoder
MediaRecorder.VideoSource
MediaRoute2Info
MediaRoute2Info.Builder
MediaRoute2ProviderService
MediaRouter
MediaRouter.Callback
MediaRouter.RouteCategory
MediaRouter.RouteGroup
MediaRouter.RouteInfo
MediaRouter.SimpleCallback
MediaRouter.UserRouteInfo
MediaRouter.VolumeCallback
MediaRouter2
MediaRouter2.ControllerCallback
MediaRouter2.RouteCallback
MediaRouter2.RoutingController
MediaRouter2.ScanRequest
MediaRouter2.ScanRequest.Builder
MediaRouter2.ScanToken
MediaRouter2.TransferCallback
MediaScannerConnection
MediaSession2
MediaSession2.Builder
MediaSession2.ControllerInfo
MediaSession2.SessionCallback
MediaSession2Service
MediaSession2Service.MediaNotification
MediaSync
MediaSync.Callback
MediaSyncEvent
MediaTimestamp
MicrophoneInfo
MicrophoneInfo.Coordinate3F
PlaybackParams
Rating
RemoteControlClient
RemoteControlClient.MetadataEditor
RemoteController
RemoteController.MetadataEditor
Ringtone
RingtoneManager
RouteDiscoveryPreference
RouteDiscoveryPreference.Builder
RouteListingPreference
RouteListingPreference.Builder
RouteListingPreference.Item
RouteListingPreference.Item.Builder
RoutingSessionInfo
RoutingSessionInfo.Builder
Session2Command
Session2Command.Result
Session2CommandGroup
Session2CommandGroup.Builder
Session2Token
SoundPool
SoundPool.Builder
Spatializer
SubtitleData
SuggestedDeviceInfo
SuggestedDeviceInfo.Builder
SyncParams
ThumbnailUtils
TimedMetaData
TimedText
ToneGenerator
VolumeProvider
VolumeShaper
VolumeShaper.Configuration
VolumeShaper.Configuration.Builder
VolumeShaper.Operation
Exceptions
android.media.audiofx
android.media.browse
android.media.effect
android.media.metrics
android.media.midi
android.media.projection
android.media.quality
android.media.session
android.media.tv
android.media.tv.ad
android.media.tv.interactive
android.mtp
android.net
android.net.dns
android.net.eap
android.net.http
android.net.ipsec.ike
android.net.ipsec.ike.exceptions
android.net.nsd
android.net.rtp
android.net.sip
android.net.ssl
android.net.vcn
android.net.wifi
android.net.wifi.aware
android.net.wifi.hotspot2
android.net.wifi.hotspot2.omadm
android.net.wifi.hotspot2.pps
android.net.wifi.p2p
android.net.wifi.p2p.nsd
android.net.wifi.rtt
android.nfc
android.nfc.cardemulation
android.nfc.tech
android.opengl
android.os
android.os.ext
android.os.flagging
android.os.health
android.os.multisensory
android.os.storage
android.os.storage.operations
android.os.storage.operations.sources
android.os.storage.operations.targets
android.os.strictmode
android.os.vibrator
android.preference
android.print
android.print.pdf
android.printservice
android.provider
android.ranging
android.ranging.ble
android.ranging.ble.cs
android.ranging.ble.rssi
android.ranging.oob
android.ranging.raw
android.ranging.uwb
android.ranging.wifi.pd
android.ranging.wifi.rtt
android.renderscript
android.sax
android.se.omapi
android.security
android.security.advancedprotection
android.security.authenticationpolicy
android.security.identity
android.security.keystore
android.security.net.config
android.service.assist.classification
android.service.autofill
android.service.carrier
android.service.chooser
android.service.contentsafety
android.service.controls
android.service.controls.actions
android.service.controls.templates
android.service.credentials
android.service.dreams
android.service.media
android.service.messaging
android.service.notification
android.service.persistentdata
android.service.personalcontext.embedded
android.service.personalcontext.insight
android.service.personalcontext.insight.interaction
android.service.personalcontext.understander
android.service.quickaccesswallet
android.service.quicksettings
android.service.restrictions
android.service.settings.preferences
android.service.textservice
android.service.voice
android.service.vr
android.service.wallpaper
android.speech
android.speech.tts
android.system
android.telecom
android.telephony
android.telephony.cdma
android.telephony.data
android.telephony.emergency
android.telephony.euicc
android.telephony.gsm
android.telephony.ims
android.telephony.ims.feature
android.telephony.ims.stub
android.telephony.mbms
android.telephony.satellite
android.test
android.test.mock
android.test.suitebuilder
android.test.suitebuilder.annotation
android.text
android.text.format
android.text.method
android.text.style
android.text.util
android.transition
android.util
android.util.function
android.util.proto
android.view
android.view.accessibility
android.view.animation
android.view.autofill
android.view.contentcapture
android.view.displayhash
android.view.inputmethod
android.view.inspector
android.view.textclassifier
android.view.textservice
android.view.translation
android.webkit
android.widget
android.widget.inline
android.widget.photopicker
android.window
dalvik.annotation
dalvik.annotation.optimization
dalvik.bytecode
dalvik.system
java.awt.font
java.beans
java.io
java.lang
java.lang.annotation
java.lang.invoke
java.lang.ref
java.lang.reflect
java.lang.runtime
java.math
java.net
java.nio
java.nio.channels
java.nio.channels.spi
java.nio.charset
java.nio.charset.spi
java.nio.file
java.nio.file.attribute
java.nio.file.spi
java.security
java.security.acl
java.security.cert
java.security.interfaces
java.security.spec
java.sql
java.text
java.time
java.time.chrono
java.time.format
java.time.temporal
java.time.zone
java.util
java.util.concurrent
java.util.concurrent.atomic
java.util.concurrent.locks
java.util.function
java.util.jar
java.util.logging
java.util.prefs
java.util.random
java.util.regex
java.util.stream
java.util.zip
javax.annotation.processing
javax.crypto
javax.crypto.interfaces
javax.crypto.spec
javax.microedition.khronos.egl
javax.microedition.khronos.opengles
javax.net
javax.net.ssl
javax.security.auth
javax.security.auth.callback
javax.security.auth.login
javax.security.auth.x500
javax.security.cert
javax.sql
javax.xml
javax.xml.datatype
javax.xml.namespace
javax.xml.parsers
javax.xml.transform
javax.xml.transform.dom
javax.xml.transform.sax
javax.xml.transform.stream
javax.xml.validation
javax.xml.xpath
org.apache.http.conn
org.apache.http.conn.scheme
org.apache.http.conn.ssl
org.apache.http.params
org.json
org.w3c.dom
org.w3c.dom.ls
org.xml.sax
org.xml.sax.ext
org.xml.sax.helpers
org.xmlpull.v1
org.xmlpull.v1.sax2
On this page
Callbacks
Summary
Nested classes
Constants
Public constructors
Public methods
Protected methods
Inherited methods
Constants
EVENT_KEY_EXPIRED
EVENT_KEY_REQUIRED
EVENT_PROVISION_REQUIRED
EVENT_SESSION_RECLAIMED
EVENT_VENDOR_DEFINED
HDCP_LEVEL_UNKNOWN
HDCP_NONE
HDCP_NO_DIGITAL_OUTPUT
HDCP_V1
HDCP_V2
HDCP_V2_1
HDCP_V2_2
HDCP_V2_3
KEY_TYPE_OFFLINE
KEY_TYPE_RELEASE
KEY_TYPE_STREAMING
OFFLINE_LICENSE_STATE_RELEASED
OFFLINE_LICENSE_STATE_UNKNOWN
OFFLINE_LICENSE_STATE_USABLE
PROPERTY_ALGORITHMS
PROPERTY_DESCRIPTION
PROPERTY_DEVICE_UNIQUE_ID
PROPERTY_VENDOR
PROPERTY_VERSION
SECURITY_LEVEL_HW_SECURE_ALL
SECURITY_LEVEL_HW_SECURE_CRYPTO
SECURITY_LEVEL_HW_SECURE_DECODE
SECURITY_LEVEL_SW_SECURE_CRYPTO
SECURITY_LEVEL_SW_SECURE_DECODE
SECURITY_LEVEL_UNKNOWN
Public constructors
MediaDrm
Public methods
clearOnEventListener
clearOnExpirationUpdateListener
clearOnKeyStatusChangeListener
clearOnSessionLostStateListener
close
closeSession
getConnectedHdcpLevel
getCryptoSession
getKeyRequest
getLogMessages
getMaxHdcpLevel
getMaxSecurityLevel
getMaxSessionCount
getMetrics
getOfflineLicenseKeySetIds
getOfflineLicenseState
getOpenSessionCount
getPlaybackComponent
getPropertyByteArray
getPropertyString
getProvisionRequest
getSecureStop
getSecureStopIds
getSecureStops
getSecurityLevel
getSupportedCryptoSchemes
isCryptoSchemeSupported
isCryptoSchemeSupported
isCryptoSchemeSupported
openSession
openSession
provideKeyResponse
provideProvisionResponse
queryKeyStatus
release
releaseAllSecureStops
releaseSecureStops
removeAllSecureStops
removeKeys
removeOfflineLicense
removeSecureStop
requiresSecureDecoder
requiresSecureDecoder
restoreKeys
setOnEventListener
setOnEventListener
setOnEventListener
setOnExpirationUpdateListener
setOnExpirationUpdateListener
setOnKeyStatusChangeListener
setOnKeyStatusChangeListener
setOnSessionLostStateListener
setOnSessionLostStateListener
setPropertyByteArray
setPropertyString
Protected methods
finalize
Android Developers
Develop
API reference
Added in API level 18
MediaDrm
Kotlin |Java

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 MediaDrmStateException.getErrorCode() and MediaCodec.CryptoException.getErrorCode()

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 LogMessage records an event in the MediaDrm framework or vendor plugin.

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 MediaDrm.getMetrics() call.

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

SessionException is a misnomer because it may occur in methods without a session context.

Constants

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.

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 NotProvisionedException instead.

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 getKeyRequest(byte, byte, String, int, HashMap) with KEY_TYPE_RELEASE but the key response has not been received.

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 constructors

MediaDrm(UUID uuid)

Instantiate a MediaDrm object

Public methods

void clearOnEventListener()

Clear the OnEventListener.

void clearOnExpirationUpdateListener()

Clear the OnExpirationUpdateListener.

void clearOnKeyStatusChangeListener()

Clear the OnKeyStatusChangeListener.

void clearOnSessionLostStateListener()

Clear the OnSessionLostStateListener.

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 openSession().

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 getKeyRequest(byte, byte, String, int, HashMap) and provideKeyResponse(byte, byte) using a session key server.

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 LogMessages associated with this MediaDrm instance.

int getMaxHdcpLevel()

Return the maximum supported HDCP level.

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.

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 PlaybackComponent associated with a DRM session.

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 getKeyRequest(byte, byte, String, int, HashMap) to track concurrent playback. See additional information in getSecureStops()

List<byte[]> getSecureStopIds()

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.

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)

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 close().

void releaseAllSecureStops()

This method was deprecated in API level 28. Remove all secure stops using removeAllSecureStops() instead.

void releaseSecureStops(byte[] ssRelease)

void removeAllSecureStops()

void removeKeys(byte[] sessionId)

Remove the current keys from a session.

void removeOfflineLicense(byte[] keySetId)

void removeSecureStop(byte[] ssid)

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)

void setOnEventListener(MediaDrm.OnEventListener listener, Handler handler)

void setOnEventListener(MediaDrm.OnEventListener listener)

void setOnExpirationUpdateListener(MediaDrm.OnExpirationUpdateListener listener, Handler handler)

void setOnExpirationUpdateListener(Executor executor, MediaDrm.OnExpirationUpdateListener listener)

void setOnKeyStatusChangeListener(Executor executor, MediaDrm.OnKeyStatusChangeListener listener)

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)

void setOnSessionLostStateListener(MediaDrm.OnSessionLostStateListener listener, Handler handler)

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

From class java.lang.Object

From interface java.lang.AutoCloseable
Constants
EVENT_KEY_EXPIRED
Added in API level 18
Deprecated in API level 26
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
Added in API level 18
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
Added in API level 18
Deprecated in API level 23
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
Added in API level 23
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
Added in API level 18
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
Added in API level 28
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
Added in API level 28
public static final int HDCP_NONE

HDCP is not supported on this device, content is unprotected

Constant Value: 1 (0x00000001)

HDCP_NO_DIGITAL_OUTPUT
Added in API level 28
public static final int HDCP_NO_DIGITAL_OUTPUT

No digital output, implicitly secure

Constant Value: 2147483647 (0x7fffffff)

HDCP_V1
Added in API level 28
public static final int HDCP_V1

HDCP version 1.0

Constant Value: 2 (0x00000002)

HDCP_V2
Added in API level 28
public static final int HDCP_V2

HDCP version 2.0 Type 1.

Constant Value: 3 (0x00000003)

HDCP_V2_1
Added in API level 28
public static final int HDCP_V2_1

HDCP version 2.1 Type 1.

Constant Value: 4 (0x00000004)

HDCP_V2_2
Added in API level 28
public static final int HDCP_V2_2

HDCP version 2.2 Type 1.

Constant Value: 5 (0x00000005)

HDCP_V2_3
Added in API level 29
public static final int HDCP_V2_3

HDCP version 2.3 Type 1.

Constant Value: 6 (0x00000006)

KEY_TYPE_OFFLINE
Added in API level 18
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
Added in API level 18
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
Added in API level 18
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
Added in API level 29
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
Added in API level 29
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
Added in API level 29
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
Added in API level 18
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
Added in API level 18
public static final String PROPERTY_DESCRIPTION

String property name: describes the DRM plugin

Constant Value: "description"

PROPERTY_DEVICE_UNIQUE_ID
Added in API level 18
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
Added in API level 18
public static final String PROPERTY_VENDOR

String property name: identifies the maker of the DRM plugin

Constant Value: "vendor"

PROPERTY_VERSION
Added in API level 18
public static final String PROPERTY_VERSION

String property name: identifies the version of the DRM plugin

Constant Value: "version"

SECURITY_LEVEL_HW_SECURE_ALL
Added in API level 28
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
Added in API level 28
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
Added in API level 28
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
Added in API level 28
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
Added in API level 28
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
Added in API level 28
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
Added in API level 18
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
Added in API level 29
public void clearOnEventListener ()

Clear the OnEventListener.

clearOnExpirationUpdateListener
Added in API level 29
public void clearOnExpirationUpdateListener ()

Clear the OnExpirationUpdateListener.

clearOnKeyStatusChangeListener
Added in API level 29
public void clearOnKeyStatusChangeListener ()

Clear the OnKeyStatusChangeListener.

clearOnSessionLostStateListener
Added in API level 29
public void clearOnSessionLostStateListener ()

Clear the OnSessionLostStateListener.

close
Added in API level 28
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
Added in API level 18
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
Added in API level 28
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 one of the following:
HDCP_LEVEL_UNKNOWN
HDCP_NONE
HDCP_V1
HDCP_V2
HDCP_V2_1
HDCP_V2_2
HDCP_V2_3
HDCP_NO_DIGITAL_OUTPUT

getCryptoSession
Added in API level 18
public MediaDrm.CryptoSession getCryptoSession (byte[] sessionId,
String cipherAlgorithm,
String macAlgorithm)

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 getPropertyString(String) with the property name "algorithms".
This value cannot be null.

Returns
MediaDrm.CryptoSession

getKeyRequest
Added in API level 18
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 one of the following:
KEY_TYPE_STREAMING
KEY_TYPE_OFFLINE
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 certificate
getLogMessages
Added in API level 31
public List<MediaDrm.LogMessage> getLogMessages ()

Returns recent LogMessages associated with this MediaDrm instance.

Returns
List<MediaDrm.LogMessage> This value cannot be null.

getMaxHdcpLevel
Added in API level 28
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 one of the following:
HDCP_LEVEL_UNKNOWN
HDCP_NONE
HDCP_V1
HDCP_V2
HDCP_V2_1
HDCP_V2_2
HDCP_V2_3
HDCP_NO_DIGITAL_OUTPUT

getMaxSecurityLevel
Added in API level 28
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
Added in API level 28
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
Added in API level 28
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
Added in API level 29
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
Added in API level 29
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 one of the following:
OFFLINE_LICENSE_STATE_UNKNOWN
OFFLINE_LICENSE_STATE_USABLE
OFFLINE_LICENSE_STATE_RELEASED

Throws
IllegalArgumentException if the keySetId does not refer to an offline license.
getOpenSessionCount
Added in API level 28
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
Added in API level 31
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:

PlaybackComponent
getPropertyByteArray
Added in API level 18
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
Added in API level 18
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
Added in API level 18
public MediaDrm.ProvisionRequest getProvisionRequest ()

A provision request/response exchange occurs between the app and a provisioning server to retrieve a device certificate. If provisioning 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
Added in API level 22
Deprecated in API level 33
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
Added in API level 28
Deprecated in API level 33
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
Added in API level 18
Deprecated in API level 33
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
Added in API level 28
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 null.

Returns
int the security level of the session.
Value is one of the following:
SECURITY_LEVEL_UNKNOWN
SECURITY_LEVEL_SW_SECURE_CRYPTO
SECURITY_LEVEL_SW_SECURE_DECODE
SECURITY_LEVEL_HW_SECURE_CRYPTO
SECURITY_LEVEL_HW_SECURE_DECODE
SECURITY_LEVEL_HW_SECURE_ALL

getSupportedCryptoSchemes
Added in API level 30
public static List<UUID> getSupportedCryptoSchemes ()

Returns
List<UUID> list of crypto schemes (as UUIDs) for which isCryptoSchemeSupported(UUID) returns true; each UUID can be used as input to create MediaDrm objects via MediaDrm(UUID).
This value cannot be null.

isCryptoSchemeSupported
Added in API level 19
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
Added in API level 29
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 one of the following:
SECURITY_LEVEL_UNKNOWN
SECURITY_LEVEL_SW_SECURE_CRYPTO
SECURITY_LEVEL_SW_SECURE_DECODE
SECURITY_LEVEL_HW_SECURE_CRYPTO
SECURITY_LEVEL_HW_SECURE_DECODE
SECURITY_LEVEL_HW_SECURE_ALL

Returns
boolean

isCryptoSchemeSupported
Added in API level 18
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
Added in API level 18
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
Added in API level 28
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 one of the following:
SECURITY_LEVEL_UNKNOWN
SECURITY_LEVEL_SW_SECURE_CRYPTO
SECURITY_LEVEL_SW_SECURE_DECODE
SECURITY_LEVEL_HW_SECURE_CRYPTO
SECURITY_LEVEL_HW_SECURE_DECODE
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
Added in API level 18
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
DeniedByServerException if the response indicates that the server rejected the request
NotProvisionedException if the response indicates that reprovisioning is required
provideProvisionResponse
Added in API level 18
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
Added in API level 18
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.

Returns
HashMap<String, String> This value cannot be null.

release
Added in API level 18
Deprecated in API level 28
public void release ()

This method was deprecated in API level 28.
replaced by close().

releaseAllSecureStops
Added in API level 22
Deprecated in API level 28
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
Added in API level 18
Deprecated in API level 33
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
Added in API level 28
Deprecated in API level 33
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
Added in API level 18
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
Added in API level 29
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
Added in API level 28
Deprecated in API level 33
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
Added in API level 31
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(UUID,String) to query mime type support separately; for unsupported mime types the return value of requiresSecureDecoder(String) is crypto scheme dependent.
This value cannot be null.

Returns
boolean

requiresSecureDecoder
Added in API level 31
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(UUID,String,int) to query mime type support separately; for unsupported mime types the return value of requiresSecureDecoder(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 one of the following:
SECURITY_LEVEL_UNKNOWN
SECURITY_LEVEL_SW_SECURE_CRYPTO
SECURITY_LEVEL_SW_SECURE_DECODE
SECURITY_LEVEL_HW_SECURE_CRYPTO
SECURITY_LEVEL_HW_SECURE_DECODE
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
Added in API level 18
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
Added in API level 29
public void setOnEventListener (Executor executor,
MediaDrm.OnEventListener listener)

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(OnEventListener)
setOnEventListener
Added in API level 29
public void setOnEventListener (MediaDrm.OnEventListener listener,
Handler handler)

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
Added in API level 18
public void setOnEventListener (MediaDrm.OnEventListener listener)

Parameters
listener MediaDrm.OnEventListener: the callback that will be run. Use null to stop receiving event callbacks.

See also:

setOnEventListener(OnEventListener,Handler)
setOnExpirationUpdateListener
Added in API level 23
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
Added in API level 29
public void setOnExpirationUpdateListener (Executor executor,
MediaDrm.OnExpirationUpdateListener listener)

listener MediaDrm.OnExpirationUpdateListener: the callback that will be run.
This value cannot be null.

See also:

setOnExpirationUpdateListener(OnExpirationUpdateListener,Handler)
setOnKeyStatusChangeListener
Added in API level 29
public void setOnKeyStatusChangeListener (Executor executor,
MediaDrm.OnKeyStatusChangeListener listener)

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.

See also:

setOnKeyStatusChangeListener(OnKeyStatusChangeListener,Handler)
setOnKeyStatusChangeListener
Added in API level 23
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
Added in API level 29
public void setOnSessionLostStateListener (Executor executor,
MediaDrm.OnSessionLostStateListener listener)

listener MediaDrm.OnSessionLostStateListener: the callback that will be run.
This value may be null.

See also:

setOnSessionLostStateListener(OnSessionLostStateListener,Handler)
setOnSessionLostStateListener
Added in API level 29
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
Added in API level 18
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
Added in API level 18
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
Added in API level 18
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

Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.

Last updated 2026-08-03 UTC.

X
Follow @AndroidDev on X
YouTube
Check out Android Developers on YouTube
LinkedIn
Connect with the Android Developers community on LinkedIn
MORE ANDROID
Android
Android for Enterprise
Security
Source
News
Blog
Podcasts
DISCOVER
Gaming
Machine Learning
Health & Fitness
Camera & Media
Privacy
5G
ANDROID DEVICES
Large screens
Wear OS
ChromeOS devices
Android for cars
Android TV
RELEASES
Android 17
Android 16
Android 15
Android 14
Android 13
Android 12
Android 11
DOCUMENTATION AND DOWNLOADS
Android Studio guide
Developers guides
API reference
Download Studio
Android NDK
SUPPORT
Report platform bug
Report documentation bug
Google Play support
Join research studies
Android
Chrome
Firebase
Google Cloud Platform
All products
Privacy
License
Brand guidelines
Get news and tips by email
Subscribe

MediaDrm | Android API 参考文档 原文标题：MediaDrm | API reference | Android Developers

内容概要总结

翻译内容

原文内容（English）

回调（Callbacks）

摘要（Summary）

常量

公开构造函数

公开方法

受保护的方法

MediaDrm | Android API 参考文档原文标题：MediaDrm | API reference | Android Developers