1# native_mediakeysession.h 2 3## 概述 4 5定义Drm MediaKeySession API。提供以下功能：<br> 生成媒体密钥请求、处理媒体密钥响应、事件监听、获取内容保护级别、检查媒体密钥状态、删除媒体密钥等。 6 7**引用文件：** <multimedia/drm_framework/native_mediakeysession.h> 8 9**库：** libnative_drm.z.so 10 11**系统能力：** SystemCapability.Multimedia.Drm.Core 12 13**起始版本：** 11 14 15**相关模块：** [Drm](capi-drm.md) 16 17## 汇总 18 19### 结构体 20 21| 名称 | typedef关键字 | 描述 | 22| -- | -- | -- | 23| [MediaKeySession_Callback](capi-drm-mediakeysession-callback.md) | MediaKeySession_Callback | MediaKeySession_Callback结构体，用于监听密钥过期、密钥更改等事件，不返回媒体密钥会话实例，适用于单媒体密钥会话解密场景。 | 24| [OH_MediaKeySession_Callback](capi-drm-oh-mediakeysession-callback.md) | OH_MediaKeySession_Callback | OH_MediaKeySession_Callback结构体，用于监听密钥过期、密钥更改等事件，返回媒体密钥会话实例，适用多个媒体密钥会话解密场景。 | 25 26### 函数 27 28| 名称 | typedef关键字 | 描述 | 29| -- | -- | -- | 30| [typedef Drm_ErrCode (\*MediaKeySession_EventCallback)(DRM_EventType eventType, uint8_t *info,int32_t infoLen, char *extra)](#mediakeysession_eventcallback) | MediaKeySession_EventCallback | MediaKeySession事件触发时将调用的回调，如密钥过期事件。 | 31| [typedef Drm_ErrCode (\*MediaKeySession_KeyChangeCallback)(DRM_KeysInfo *keysInfo, bool newKeysAvailable)](#mediakeysession_keychangecallback) | MediaKeySession_KeyChangeCallback | 密钥变换时将调用回调。 | 32| [typedef Drm_ErrCode (\*OH_MediaKeySession_EventCallback)(MediaKeySession *mediaKeySession, DRM_EventType eventType,uint8_t *info, int32_t infoLen, char *extra)](#oh_mediakeysession_eventcallback) | OH_MediaKeySession_EventCallback | 事件触发时将调用的回调。 | 33| [typedef Drm_ErrCode (\*OH_MediaKeySession_KeyChangeCallback)(MediaKeySession *mediaKeySession, DRM_KeysInfo *keysInfo, bool newKeysAvailable)](#oh_mediakeysession_keychangecallback) | OH_MediaKeySession_KeyChangeCallback | 密钥变换时将调用的回调。 | 34| [Drm_ErrCode OH_MediaKeySession_GenerateMediaKeyRequest(MediaKeySession *mediaKeySession, DRM_MediaKeyRequestInfo *info, DRM_MediaKeyRequest *mediaKeyRequest)](#oh_mediakeysession_generatemediakeyrequest) | - | 生成媒体密钥请求。 | 35| [Drm_ErrCode OH_MediaKeySession_ProcessMediaKeyResponse(MediaKeySession *mediaKeySession, uint8_t *response, int32_t responseLen, uint8_t *offlineMediaKeyId, int32_t *offlineMediaKeyIdLen)](#oh_mediakeysession_processmediakeyresponse) | - | 处理媒体密钥请求响应。 | 36| [Drm_ErrCode OH_MediaKeySession_CheckMediaKeyStatus(MediaKeySession *mediaKeySession, DRM_MediaKeyStatus *mediaKeyStatus)](#oh_mediakeysession_checkmediakeystatus) | - | 检查媒体密钥状态。 | 37| [Drm_ErrCode OH_MediaKeySession_ClearMediaKeys(MediaKeySession *mediaKeySession)](#oh_mediakeysession_clearmediakeys) | - | 清除当前会话的媒体密钥。 | 38| [Drm_ErrCode OH_MediaKeySession_GenerateOfflineReleaseRequest(MediaKeySession *mediaKeySession, uint8_t *offlineMediaKeyId, int32_t offlineMediaKeyIdLen, uint8_t *releaseRequest,int32_t *releaseRequestLen)](#oh_mediakeysession_generateofflinereleaserequest) | - | 生成离线媒体密钥释放请求。 | 39| [Drm_ErrCode OH_MediaKeySession_ProcessOfflineReleaseResponse(MediaKeySession *mediaKeySession, uint8_t *offlineMediaKeyId, int32_t offlineMediaKeyIdLen, uint8_t *releaseReponse,int32_t releaseReponseLen)](#oh_mediakeysession_processofflinereleaseresponse) | - | 处理离线媒体密钥释放请求响应。 | 40| [Drm_ErrCode OH_MediaKeySession_RestoreOfflineMediaKeys(MediaKeySession *mediaKeySession, uint8_t *offlineMediaKeyId, int32_t offlineMediaKeyIdLen)](#oh_mediakeysession_restoreofflinemediakeys) | - | 恢复离线媒体密钥到当前会话。 | 41| [Drm_ErrCode OH_MediaKeySession_GetContentProtectionLevel(MediaKeySession *mediaKeySession, DRM_ContentProtectionLevel *contentProtectionLevel)](#oh_mediakeysession_getcontentprotectionlevel) | - | 获取会话的内容保护级别。 | 42| [Drm_ErrCode OH_MediaKeySession_RequireSecureDecoderModule(MediaKeySession *mediaKeySession, const char *mimeType, bool *status)](#oh_mediakeysession_requiresecuredecodermodule) | - | 是否需要安全解码。 | 43| [Drm_ErrCode OH_MediaKeySession_SetMediaKeySessionCallback(MediaKeySession *mediaKeySession, MediaKeySession_Callback *callback)](#oh_mediakeysession_setmediakeysessioncallback) | - | 设置MediaKeySession会话事件回调。 | 44| [Drm_ErrCode OH_MediaKeySession_SetCallback(MediaKeySession *mediaKeySession, OH_MediaKeySession_Callback *callback)](#oh_mediakeysession_setcallback) | - | 设置MediaKeySession事件回调。 | 45| [Drm_ErrCode OH_MediaKeySession_Destroy(MediaKeySession *mediaKeySession)](#oh_mediakeysession_destroy) | - | 销毁MediaKeySession实例。 | 46 47## 函数说明 48 49### MediaKeySession_EventCallback() 50 51``` 52typedef Drm_ErrCode (*MediaKeySession_EventCallback)(DRM_EventType eventType, uint8_t *info,int32_t infoLen, char *extra) 53``` 54 55**描述** 56 57MediaKeySession事件触发时将调用的回调，如密钥过期事件。 58 59**起始版本：** 11 60 61 62**参数：** 63 64| 参数项 | 描述 | 65| -- | -- | 66| [DRM_EventType](capi-native-drm-common-h.md#drm_eventtype) eventType | 事件类型。 | 67| uint8_t *info | 从媒体密钥会话获取的事件信息。 | 68| int32_t infoLen | 事件信息长度。 | 69| char *extra | 从媒体密钥会话中获得的额外信息。 | 70 71**返回：** 72 73| 类型 | 说明 | 74| -- | -- | 75| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | 错误码。 | 76 77### MediaKeySession_KeyChangeCallback() 78 79``` 80typedef Drm_ErrCode (*MediaKeySession_KeyChangeCallback)(DRM_KeysInfo *keysInfo, bool newKeysAvailable) 81``` 82 83**描述** 84 85密钥变换时将调用回调。 86 87**起始版本：** 11 88 89 90**参数：** 91 92| 参数项 | 描述 | 93| -- | -- | 94| [DRM_KeysInfo](capi-drm-drm-keysinfo.md) *keysInfo | 密钥信息。 | 95| bool newKeysAvailable | 新密钥是否可用。 | 96 97**返回：** 98 99| 类型 | 说明 | 100| -- | -- | 101| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | DRM_ERR_OK：执行成功。<br>DRM_ERR_INVALID_VAL：参数检查失败。 | 102 103### OH_MediaKeySession_EventCallback() 104 105``` 106typedef Drm_ErrCode (*OH_MediaKeySession_EventCallback)(MediaKeySession *mediaKeySession, DRM_EventType eventType,uint8_t *info, int32_t infoLen, char *extra) 107``` 108 109**描述** 110 111事件触发时将调用的回调。 112 113**起始版本：** 12 114 115 116**参数：** 117 118| 参数项 | 描述 | 119| -- | -- | 120| [MediaKeySession](capi-drm-mediakeysession.md) *mediaKeySession | 会话实例。 | 121| [DRM_EventType](capi-native-drm-common-h.md#drm_eventtype) eventType | 事件类型。 | 122| uint8_t *info | 事件信息。 | 123| int32_t infoLen | 事件信息长度。 | 124| char *extra | 增量信息。 | 125 126**返回：** 127 128| 类型 | 说明 | 129| -- | -- | 130| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | 错误码。 | 131 132### OH_MediaKeySession_KeyChangeCallback() 133 134``` 135typedef Drm_ErrCode (*OH_MediaKeySession_KeyChangeCallback)(MediaKeySession *mediaKeySession, DRM_KeysInfo *keysInfo,bool newKeysAvailable) 136``` 137 138**描述** 139 140密钥变换时将调用的回调。 141 142**起始版本：** 12 143 144 145**参数：** 146 147| 参数项 | 描述 | 148| -- | -- | 149| [MediaKeySession](capi-drm-mediakeysession.md) *mediaKeySession | 媒体密钥会话实例。 | 150| [DRM_KeysInfo](capi-drm-drm-keysinfo.md) *keysInfo | 密钥信息。 | 151| bool newKeysAvailable | 新密钥是否可用，true表示可用，false表示不可用。 | 152 153**返回：** 154 155| 类型 | 说明 | 156| -- | -- | 157| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | DRM_ERR_OK：执行成功。<br>DRM_ERR_INVALID_VAL：参数检查失败。 | 158 159### OH_MediaKeySession_GenerateMediaKeyRequest() 160 161``` 162Drm_ErrCode OH_MediaKeySession_GenerateMediaKeyRequest(MediaKeySession *mediaKeySession,DRM_MediaKeyRequestInfo *info, DRM_MediaKeyRequest *mediaKeyRequest) 163``` 164 165**描述** 166 167生成媒体密钥请求。 168 169**起始版本：** 11 170 171 172**参数：** 173 174| 参数项 | 描述 | 175| -- | -- | 176| [MediaKeySession](capi-drm-mediakeysession.md) *mediaKeySession | MediaKeySession实例。 | 177| [DRM_MediaKeyRequestInfo](capi-drm-drm-mediakeyrequestinfo.md) *info | 媒体密钥请求信息。 | 178| [DRM_MediaKeyRequest](capi-drm-drm-mediakeyrequest.md) *mediaKeyRequest | 媒体密钥请求。 | 179 180**返回：** 181 182| 类型 | 说明 | 183| -- | -- | 184| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | DRM_ERR_OK：执行成功。<br>DRM_ERR_NO_MEMORY：内存不足，内存分配失败。<br>DRM_ERR_INVALID_VAL：输入参数mediaKeySession为空指针或无效，或输入参数info为空指针，或输入参数mediaKeyRequest为空指针。<br>DRM_ERR_UNKNOWN：发生内部错误，请查看日志详细信息。 | 185 186### OH_MediaKeySession_ProcessMediaKeyResponse() 187 188``` 189Drm_ErrCode OH_MediaKeySession_ProcessMediaKeyResponse(MediaKeySession *mediaKeySession,uint8_t *response, int32_t responseLen, uint8_t *offlineMediaKeyId, int32_t *offlineMediaKeyIdLen) 190``` 191 192**描述** 193 194处理媒体密钥请求响应。 195 196**起始版本：** 11 197 198 199**参数：** 200 201| 参数项 | 描述 | 202| -- | -- | 203| [MediaKeySession](capi-drm-mediakeysession.md) *mediaKeySession | MediaKeySession实例。 | 204| uint8_t *response | 媒体密钥请求响应。 | 205| int32_t responseLen | 媒体密钥请求响应长度。 | 206| uint8_t *offlineMediaKeyId | 离线媒体密钥标识。 | 207| int32_t *offlineMediaKeyIdLen | 离线媒体密钥标识的长度。 | 208 209**返回：** 210 211| 类型 | 说明 | 212| -- | -- | 213| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | DRM_ERR_OK：执行成功。<br>DRM_ERR_NO_MEMORY：内存不足，内存分配失败。<br>DRM_ERR_INVALID_VAL：输入参数mediaKeySession为空指针或无效，或其它指针类型输入参数为空指针。<br>DRM_ERR_UNKNOWN：发生内部错误，请查看日志详细信息。 | 214 215### OH_MediaKeySession_CheckMediaKeyStatus() 216 217``` 218Drm_ErrCode OH_MediaKeySession_CheckMediaKeyStatus(MediaKeySession *mediaKeySession,DRM_MediaKeyStatus *mediaKeyStatus) 219``` 220 221**描述** 222 223检查媒体密钥状态。 224 225**起始版本：** 11 226 227 228**参数：** 229 230| 参数项 | 描述 | 231| -- | -- | 232| [MediaKeySession](capi-drm-mediakeysession.md) *mediaKeySession | MediaKeySession实例。 | 233| [DRM_MediaKeyStatus](capi-drm-drm-mediakeystatus.md) *mediaKeyStatus | 媒体密钥状态。 | 234 235**返回：** 236 237| 类型 | 说明 | 238| -- | -- | 239| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | DRM_ERR_OK：执行成功。<br>DRM_ERR_NO_MEMORY：内存不足，内存分配失败。<br>DRM_ERR_INVALID_VAL：输入参数mediaKeySession为空指针或无效，或输入参数mediaKeyStatus为空指针。<br>DRM_ERR_UNKNOWN：发生内部错误，请查看日志详细信息。 | 240 241### OH_MediaKeySession_ClearMediaKeys() 242 243``` 244Drm_ErrCode OH_MediaKeySession_ClearMediaKeys(MediaKeySession *mediaKeySession) 245``` 246 247**描述** 248 249清除当前会话的媒体密钥。 250 251**起始版本：** 11 252 253 254**参数：** 255 256| 参数项 | 描述 | 257| -- | -- | 258| [MediaKeySession](capi-drm-mediakeysession.md) *mediaKeySession | MediaKeySession实例。 | 259 260**返回：** 261 262| 类型 | 说明 | 263| -- | -- | 264| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | DRM_ERR_OK：执行成功。<br>DRM_ERR_INVALID_VAL：输入参数mediaKeySession为空指针或无效。<br>DRM_ERR_UNKNOWN：发生内部错误，请查看日志详细信息。 | 265 266### OH_MediaKeySession_GenerateOfflineReleaseRequest() 267 268``` 269Drm_ErrCode OH_MediaKeySession_GenerateOfflineReleaseRequest(MediaKeySession *mediaKeySession,uint8_t *offlineMediaKeyId, int32_t offlineMediaKeyIdLen, uint8_t *releaseRequest,int32_t *releaseRequestLen) 270``` 271 272**描述** 273 274生成离线媒体密钥释放请求。 275 276**起始版本：** 11 277 278 279**参数：** 280 281| 参数项 | 描述 | 282| -- | -- | 283| [MediaKeySession](capi-drm-mediakeysession.md) *mediaKeySession | MediaKeySession实例。 | 284| uint8_t *offlineMediaKeyId | 离线媒体密钥标识。 | 285| int32_t *releaseRequestLen | 离线媒体密钥标识长度。 | 286| uint8_t *releaseRequest | 离线媒体密钥释放请求。 | 287| int32_t *releaseRequestLen | 离线媒体密钥释放请求长度。 | 288 289**返回：** 290 291| 类型 | 说明 | 292| -- | -- | 293| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | DRM_ERR_OK：执行成功。<br>DRM_ERR_NO_MEMORY：内存不足，内存分配失败。<br>DRM_ERR_INVALID_VAL：输入参数mediaKeySession为空指针或无效，或其它指针类型输入参数为空指针。<br>DRM_ERR_UNKNOWN：发生内部错误或设备上的DRM解决方案不支持离线媒体密钥释放，请查看日志详细信息。 | 294 295### OH_MediaKeySession_ProcessOfflineReleaseResponse() 296 297``` 298Drm_ErrCode OH_MediaKeySession_ProcessOfflineReleaseResponse(MediaKeySession *mediaKeySession,uint8_t *offlineMediaKeyId, int32_t offlineMediaKeyIdLen, uint8_t *releaseReponse,int32_t releaseReponseLen) 299``` 300 301**描述** 302 303处理离线媒体密钥释放请求响应。 304 305**起始版本：** 11 306 307 308**参数：** 309 310| 参数项 | 描述 | 311| -- | -- | 312| [MediaKeySession](capi-drm-mediakeysession.md) *mediaKeySession | MediaKeySession实例。 | 313| uint8_t *offlineMediaKeyId | 离线媒体密钥标识。 | 314| int32_t offlineMediaKeyIdLen | 离线媒体密钥标识长度。 | 315| uint8_t *releaseReponse | 媒体密钥释放请求响应。 | 316| int32_t releaseReponseLen | 媒体密钥释放请求响应长度。 | 317 318**返回：** 319 320| 类型 | 说明 | 321| -- | -- | 322| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | DRM_ERR_OK：执行成功。<br>DRM_ERR_INVALID_VAL：输入参数mediaKeySession为空指针或无效，或其它指针类型输入参数为空指针。<br>DRM_ERR_UNKNOWN：发生内部错误或设备上的DRM解决方案不支持离线媒体密钥释放，请查看日志详细信息。 | 323 324### OH_MediaKeySession_RestoreOfflineMediaKeys() 325 326``` 327Drm_ErrCode OH_MediaKeySession_RestoreOfflineMediaKeys(MediaKeySession *mediaKeySession,uint8_t *offlineMediaKeyId, int32_t offlineMediaKeyIdLen) 328``` 329 330**描述** 331 332恢复离线媒体密钥到当前会话。 333 334**起始版本：** 11 335 336 337**参数：** 338 339| 参数项 | 描述 | 340| -- | -- | 341| [MediaKeySession](capi-drm-mediakeysession.md) *mediaKeySession | MediaKeySession实例。 | 342| uint8_t *offlineMediaKeyId | 离线媒体密钥标识。 | 343| int32_t offlineMediaKeyIdLen | 离线媒体密钥标识长度。 | 344 345**返回：** 346 347| 类型 | 说明 | 348| -- | -- | 349| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | DRM_ERR_OK：执行成功。<br>DRM_ERR_INVALID_VAL：输入参数mediaKeySession为空指针或无效，或其它指针类型输入参数为空指针。<br>DRM_ERR_UNKNOWN：发生内部错误，请查看日志详细信息。 | 350 351### OH_MediaKeySession_GetContentProtectionLevel() 352 353``` 354Drm_ErrCode OH_MediaKeySession_GetContentProtectionLevel(MediaKeySession *mediaKeySession,DRM_ContentProtectionLevel *contentProtectionLevel) 355``` 356 357**描述** 358 359获取会话的内容保护级别。 360 361**起始版本：** 11 362 363 364**参数：** 365 366| 参数项 | 描述 | 367| -- | -- | 368| [MediaKeySession](capi-drm-mediakeysession.md) *mediaKeySession | MediaKeySession实例。 | 369| [DRM_ContentProtectionLevel](capi-native-drm-common-h.md#drm_contentprotectionlevel) *contentProtectionLevel | 内容保护级别。 | 370 371**返回：** 372 373| 类型 | 说明 | 374| -- | -- | 375| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | DRM_ERR_OK：执行成功。<br>DRM_ERR_INVALID_VAL：输入参数mediaKeySession为空指针或无效，或输入参数contentProtectionLevel为空指针。<br>DRM_ERR_UNKNOWN：发生内部错误，请查看日志详细信息。 | 376 377### OH_MediaKeySession_RequireSecureDecoderModule() 378 379``` 380Drm_ErrCode OH_MediaKeySession_RequireSecureDecoderModule(MediaKeySession *mediaKeySession,const char *mimeType, bool *status) 381``` 382 383**描述** 384 385是否需要安全解码。 386 387**起始版本：** 11 388 389 390**参数：** 391 392| 参数项 | 描述 | 393| -- | -- | 394| [MediaKeySession](capi-drm-mediakeysession.md) *mediaKeySession | MediaKeySession实例。 | 395| const char *mimeType | 媒体类型，支持的媒体类型取决于DRM解决方案，如：video/avc、video/hev。 | 396| bool *status | 安全解码模块状态。 | 397 398**返回：** 399 400| 类型 | 说明 | 401| -- | -- | 402| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | DRM_ERR_OK：执行成功。<br>DRM_ERR_INVALID_VAL：输入参数mediaKeySession为空指针或无效，或其它指针类型输入参数为空指针。<br>DRM_ERR_UNKNOWN：发生内部错误，请查看日志详细信息。 | 403 404### OH_MediaKeySession_SetMediaKeySessionCallback() 405 406``` 407Drm_ErrCode OH_MediaKeySession_SetMediaKeySessionCallback(MediaKeySession *mediaKeySession,MediaKeySession_Callback *callback) 408``` 409 410**描述** 411 412设置MediaKeySession会话事件回调。 413 414**起始版本：** 11 415 416 417**参数：** 418 419| 参数项 | 描述 | 420| -- | -- | 421| [MediaKeySession](capi-drm-mediakeysession.md) *mediaKeySession | MediaKeySession实例。 | 422| [MediaKeySession_Callback](capi-drm-mediakeysession-callback.md) *callback | MediaKeySession的回调。 | 423 424**返回：** 425 426| 类型 | 说明 | 427| -- | -- | 428| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | DRM_ERR_OK：执行成功。<br>DRM_ERR_INVALID_VAL：输入参数mediaKeySession为空指针或无效，或输入参数callback为空指针。 | 429 430### OH_MediaKeySession_SetCallback() 431 432``` 433Drm_ErrCode OH_MediaKeySession_SetCallback(MediaKeySession *mediaKeySession,OH_MediaKeySession_Callback *callback) 434``` 435 436**描述** 437 438设置MediaKeySession事件回调。 439 440**起始版本：** 12 441 442 443**参数：** 444 445| 参数项 | 描述 | 446| -- | -- | 447| [MediaKeySession](capi-drm-mediakeysession.md) *mediaKeySession | MediaKeySession实例。 | 448| [OH_MediaKeySession_Callback](capi-drm-oh-mediakeysession-callback.md) *callback | MediaKeySession的回调。 | 449 450**返回：** 451 452| 类型 | 说明 | 453| -- | -- | 454| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | DRM_ERR_OK：执行成功。<br>DRM_ERR_INVALID_VAL：输入参数mediaKeySession为空指针或无效，或输入参数callback为空指针。 | 455 456### OH_MediaKeySession_Destroy() 457 458``` 459Drm_ErrCode OH_MediaKeySession_Destroy(MediaKeySession *mediaKeySession) 460``` 461 462**描述** 463 464销毁MediaKeySession实例。 465 466**起始版本：** 11 467 468 469**参数：** 470 471| 参数项 | 描述 | 472| -- | -- | 473| [MediaKeySession](capi-drm-mediakeysession.md) *mediaKeySession | MediaKeySession实例。 | 474 475**返回：** 476 477| 类型 | 说明 | 478| -- | -- | 479| [Drm_ErrCode](capi-native-drm-err-h.md#drm_errcode) | DRM_ERR_OK：执行成功。<br>DRM_ERR_INVALID_VAL：输入参数mediaKeySession为空指针或无效。<br>DRM_ERR_UNKNOWN：发生内部错误，请查看日志详细信息。 | 480 481 482