1# Multimedia_Drm 2 3 4## Overview 5 6The Multimedia_Drm module provides APIs for you to set decryption parameters. After a DRM instance and session are created, you can decrypt a DRM encrypted program. 7 8**System capability**: SystemCapability.Multimedia.Media.Spliter 9 10**Since**: 12 11 12 13## Summary 14 15 16### Files 17 18| Name| Description| 19| -------- | -------- | 20| [native_cencinfo.h](native__cencinfo_8h.md) | Declares the native APIs used to set decryption parameters.| 21 22 23### Structs 24 25| Name| Description| 26| -------- | -------- | 27| struct [DrmSubsample](_drm_subsample.md) | Describes the subsample type.| 28 29 30### Macros 31 32| Name| Description| 33| -------- | -------- | 34| [DRM_KEY_ID_SIZE](#drm_key_id_size) 16 | The length of the key ID is 16 bytes.| 35| [DRM_KEY_IV_SIZE](#drm_key_iv_size) 16 | The length of the Initialization Vector (IV) is 16 bytes.| 36| [DRM_KEY_MAX_SUB_SAMPLE_NUM](#drm_key_max_sub_sample_num) 64 | The maximum number of subsamples is 64.| 37 38 39### Types 40 41| Name| Description| 42| -------- | -------- | 43| typedef struct [OH_AVBuffer](#oh_avbuffer) [OH_AVBuffer](#oh_avbuffer) | Defines a struct for the audio/video buffer.| 44| typedef struct [OH_AVCencInfo](#oh_avcencinfo) [OH_AVCencInfo](#oh_avcencinfo) | Defines a struct for the audio/video Common Encryption Scheme (CENC) information.| 45| typedef enum [DrmCencAlgorithm](#drmcencalgorithm) [DrmCencAlgorithm](#drmcencalgorithm) | Defines an enum for the DRM CENC algorithm types.| 46| typedef enum [DrmCencInfoMode](#drmcencinfomode) [DrmCencInfoMode](#drmcencinfomode) | Defines an enum for the modes for setting the key ID, IV, and subsample information in the CENC information.| 47| typedef struct [DrmSubsample](_drm_subsample.md) [DrmSubsample](#drmsubsample) | Defines a struct for the subsample type.| 48 49 50### Enums 51 52| Name| Description| 53| -------- | -------- | 54| [DrmCencAlgorithm](#drmcencalgorithm) {<br>DRM_ALG_CENC_UNENCRYPTED = 0x0, DRM_ALG_CENC_AES_CTR = 0x1,<br>DRM_ALG_CENC_AES_WV = 0x2, DRM_ALG_CENC_AES_CBC = 0x3,<br>DRM_ALG_CENC_SM4_CBC = 0x4, DRM_ALG_CENC_SM4_CTR = 0x5<br>} | Enumerates the DRM CENC algorithm types.| 55| [DrmCencInfoMode](#drmcencinfomode) {<br>DRM_CENC_INFO_KEY_IV_SUBSAMPLES_SET = 0x0,<br>DRM_CENC_INFO_KEY_IV_SUBSAMPLES_NOT_SET = 0x1 } | Enumerates the modes for setting the key ID, IV, and subsample information in the CENC information.| 56 57 58### Functions 59 60| Name| Description| 61| -------- | -------- | 62| [OH_AVCencInfo](#oh_avcencinfo) \* [OH_AVCencInfo_Create](#oh_avcencinfo_create) () | Creates an **OH_AVCencInfo** instance for setting the CENC information.| 63| OH_AVErrCode [OH_AVCencInfo_Destroy](#oh_avcencinfo_destroy) ([OH_AVCencInfo](#oh_avcencinfo) \*cencInfo) | Destroys an **OH_AVCencInfo** instance and clears internal resources.| 64| OH_AVErrCode [OH_AVCencInfo_SetAlgorithm](#oh_avcencinfo_setalgorithm) ([OH_AVCencInfo](#oh_avcencinfo) \*cencInfo, enum [DrmCencAlgorithm](#drmcencalgorithm) algo) | Sets an encryption algorithm of the CENC information.| 65| OH_AVErrCode [OH_AVCencInfo_SetKeyIdAndIv](#oh_avcencinfo_setkeyidandiv) ([OH_AVCencInfo](#oh_avcencinfo) \*cencInfo, uint8_t \*keyId, uint32_t keyIdLen, uint8_t \*iv, uint32_t ivLen) | Sets the key ID and IV in the CENC information.| 66| OH_AVErrCode [OH_AVCencInfo_SetSubsampleInfo](#oh_avcencinfo_setsubsampleinfo) ([OH_AVCencInfo](#oh_avcencinfo) \*cencInfo, uint32_t encryptedBlockCount, uint32_t skippedBlockCount, uint32_t firstEncryptedOffset, uint32_t subsampleCount, [DrmSubsample](_drm_subsample.md) \*subsamples) | Sets the subsample information in the CENC information.| 67| OH_AVErrCode [OH_AVCencInfo_SetMode](#oh_avcencinfo_setmode) ([OH_AVCencInfo](#oh_avcencinfo) \*cencInfo, enum [DrmCencInfoMode](#drmcencinfomode) mode) | Sets the CENC information mode.| 68| OH_AVErrCode [OH_AVCencInfo_SetAVBuffer](#oh_avcencinfo_setavbuffer) ([OH_AVCencInfo](#oh_avcencinfo) \*cencInfo, [OH_AVBuffer](#oh_avbuffer) \*buffer) | Sets the CENC information to an AVBuffer.| 69 70 71## Macro Description 72 73 74### DRM_KEY_ID_SIZE 75 76``` 77#define DRM_KEY_ID_SIZE 16 78``` 79 80**Description** 81 82The length of the key ID is 16 bytes. 83 84**Since**: 12 85 86 87### DRM_KEY_IV_SIZE 88 89``` 90#define DRM_KEY_IV_SIZE 16 91``` 92 93**Description** 94 95The length of the Initialization Vector (IV) is 16 bytes. 96 97**Since**: 12 98 99 100### DRM_KEY_MAX_SUB_SAMPLE_NUM 101 102``` 103#define DRM_KEY_MAX_SUB_SAMPLE_NUM 64 104``` 105 106**Description** 107 108The maximum number of subsamples is 64. 109 110**Since**: 12 111 112 113## Type Description 114 115 116### DrmCencAlgorithm 117 118``` 119typedef enum DrmCencAlgorithm DrmCencAlgorithm 120``` 121 122**Description** 123 124Defines an enum for the DRM CENC algorithm types. 125 126**Since**: 12 127 128 129### DrmCencInfoMode 130 131``` 132typedef enum DrmCencInfoMode DrmCencInfoMode 133``` 134 135**Description** 136 137Defines an enum for the modes for setting the key ID, IV, and subsample information in the CENC information. 138 139**Since**: 12 140 141 142### DrmSubsample 143 144``` 145typedef struct DrmSubsample DrmSubsample 146``` 147 148**Description** 149 150Defines a struct for the subsample type. 151 152**Since**: 12 153 154 155### OH_AVBuffer 156 157``` 158typedef struct OH_AVBuffer OH_AVBuffer 159``` 160 161**Description** 162 163Defines a struct for the audio/video buffer. 164 165**Since**: 12 166 167 168### OH_AVCencInfo 169 170``` 171typedef struct OH_AVCencInfo OH_AVCencInfo 172``` 173 174**Description** 175 176Defines a struct for the audio/video Common Encryption Scheme (CENC) information. 177 178**Since**: 12 179 180 181## Enum Description 182 183 184### DrmCencAlgorithm 185 186``` 187enum DrmCencAlgorithm 188``` 189 190**Description** 191 192Enumerates the DRM CENC algorithm types. 193 194**Since**: 12 195 196| Value| Description| 197| -------- | -------- | 198| DRM_ALG_CENC_UNENCRYPTED | No encryption algorithm is used.| 199| DRM_ALG_CENC_AES_CTR | AES CTR algorithm.| 200| DRM_ALG_CENC_AES_WV | AES WV algorithm.| 201| DRM_ALG_CENC_AES_CBC | AES CBC algorithm.| 202| DRM_ALG_CENC_SM4_CBC | SM4 CBC algorithm.| 203| DRM_ALG_CENC_SM4_CTR | SM4 CTR algorithm.| 204 205 206### DrmCencInfoMode 207 208``` 209enum DrmCencInfoMode 210``` 211 212**Description** 213 214Enumerates the modes for setting the key ID, IV, and subsample information in the CENC information. 215 216**Since**: 12 217 218| Value| Description| 219| -------- | -------- | 220| DRM_CENC_INFO_KEY_IV_SUBSAMPLES_SET | The key ID, IV, and subsample information is set.| 221| DRM_CENC_INFO_KEY_IV_SUBSAMPLES_NOT_SET | The key ID, IV, and subsample information is not set.| 222 223 224## Function Description 225 226 227### OH_AVCencInfo_Create() 228 229``` 230OH_AVCencInfo* OH_AVCencInfo_Create () 231``` 232 233**Description** 234 235Creates an **OH_AVCencInfo** instance for setting the CENC information. 236 237**System capability**: SystemCapability.Multimedia.Media.Spliter 238 239**Since**: 12 240 241**Returns** 242 243Returns the pointer to the **OH_AVCencInfo** instance created if the operation is successful; returns a null pointer otherwise. 244 245The possible causes of an operation failure are as follows: The application address space is full, or the data in the object fails to be initialized. 246 247 248### OH_AVCencInfo_Destroy() 249 250``` 251OH_AVErrCode OH_AVCencInfo_Destroy (OH_AVCencInfo * cencInfo) 252``` 253 254**Description** 255 256Destroys an **OH_AVCencInfo** instance and clears internal resources. 257 258An instance can be destroyed only once. Do not use the instance until it is created again. You are advised to set the instance pointer to a null pointer once the instance is destroyed. 259 260**System capability**: SystemCapability.Multimedia.Media.Spliter 261 262**Since**: 12 263 264**Parameters** 265 266| Name| Description| 267| -------- | -------- | 268| cencInfo | Pointer to an **OH_AVCencInfo** instance.| 269 270**Returns** 271 272Returns a result code defined in [OH_AVErrCode](_core.md#oh_averrcode). The following result codes are possible: 273 274**AV_ERR_OK** (value: 0): The operation is successful. 275 276**AV_ERR_INVALID_VAL** (value: 3): The cencInfo struct is empty. 277 278 279### OH_AVCencInfo_SetAlgorithm() 280 281``` 282OH_AVErrCode OH_AVCencInfo_SetAlgorithm (OH_AVCencInfo * cencInfo, enum DrmCencAlgorithm algo ) 283``` 284 285**Description** 286 287Sets an encryption algorithm of the CENC information. 288 289**System capability**: SystemCapability.Multimedia.Media.Spliter 290 291**Since**: 12 292 293**Parameters** 294 295| Name| Description| 296| -------- | -------- | 297| cencInfo | Pointer to an **OH_AVCencInfo** instance.| 298| algo | Encryption algorithm.| 299 300**Returns** 301 302Returns a result code defined in [OH_AVErrCode](_core.md#oh_averrcode). The following result codes are possible: 303 304**AV_ERR_OK** (value: 0): The operation is successful. 305 306**AV_ERR_INVALID_VAL** (value: 3): The cencInfo struct is empty. 307 308 309### OH_AVCencInfo_SetAVBuffer() 310 311``` 312OH_AVErrCode OH_AVCencInfo_SetAVBuffer (OH_AVCencInfo * cencInfo, OH_AVBuffer * buffer ) 313``` 314 315**Description** 316 317Sets the CENC information to an AVBuffer. 318 319**System capability**: SystemCapability.Multimedia.Media.Spliter 320 321**Since**: 12 322 323**Parameters** 324 325| Name| Description| 326| -------- | -------- | 327| cencInfo | Pointer to an **OH_AVCencInfo** instance.| 328| buffer | Pointer to the frame buffer that carries data.| 329 330**Returns** 331 332Returns a result code defined in [OH_AVErrCode](_core.md#oh_averrcode). The following result codes are possible: 333 334**AV_ERR_OK** (value: 0): The operation is successful. 335 336**AV_ERR_INVALID_VAL** (value: 3): **cencInfo**, **buffer**, **buffer->buffer_**, or **buffer->buffer_->meta_** is null. 337 338 339### OH_AVCencInfo_SetKeyIdAndIv() 340 341``` 342OH_AVErrCode OH_AVCencInfo_SetKeyIdAndIv (OH_AVCencInfo * cencInfo, uint8_t * keyId, uint32_t keyIdLen, uint8_t * iv, uint32_t ivLen ) 343``` 344 345**Description** 346 347Sets the key ID and IV in the CENC information. 348 349**System capability**: SystemCapability.Multimedia.Media.Spliter 350 351**Since**: 12 352 353**Parameters** 354 355| Name| Description| 356| -------- | -------- | 357| cencInfo | Pointer to an **OH_AVCencInfo** instance.| 358| keyId | Pointer to the key ID.| 359| keyIdLen | Length of the key ID.| 360| iv | Pointer to the IV.| 361| ivLen | Length of the IV.| 362 363**Returns** 364 365Returns a result code defined in [OH_AVErrCode](_core.md#oh_averrcode). The following result codes are possible: 366 367**AV_ERR_OK** (value: 0): The operation is successful. 368 369**AV_ERR_INVALID_VAL** (value: 3): **cencInfo**, **keyId**, or **iv** is null, **keyIdLen** is not equal to **DRM_KEY_ID_SIZE**, **ivLen** is not equal to **DRM_KEY_IV_SIZE**, the key ID or IV fails to be copied. 370 371 372### OH_AVCencInfo_SetMode() 373 374``` 375OH_AVErrCode OH_AVCencInfo_SetMode (OH_AVCencInfo * cencInfo, enum DrmCencInfoMode mode ) 376``` 377 378**Description** 379 380Sets the CENC information mode. 381 382**System capability**: SystemCapability.Multimedia.Media.Spliter 383 384**Since**: 12 385 386**Parameters** 387 388| Name| Description| 389| -------- | -------- | 390| cencInfo | Pointer to an **OH_AVCencInfo** instance.| 391| mode | CENC information mode, indicating whether the key ID, IV, and subsample information is set.| 392 393**Returns** 394 395Returns a result code defined in [OH_AVErrCode](_core.md#oh_averrcode). The following result codes are possible: 396 397**AV_ERR_OK** (value: 0): The operation is successful. 398 399**AV_ERR_INVALID_VAL** (value: 3): The cencInfo struct is empty. 400 401 402### OH_AVCencInfo_SetSubsampleInfo() 403 404``` 405OH_AVErrCode OH_AVCencInfo_SetSubsampleInfo (OH_AVCencInfo * cencInfo, uint32_t encryptedBlockCount, uint32_t skippedBlockCount, uint32_t firstEncryptedOffset, uint32_t subsampleCount, DrmSubsample * subsamples ) 406``` 407 408**Description** 409 410Sets the subsample information in the CENC information. 411 412**System capability**: SystemCapability.Multimedia.Media.Spliter 413 414**Since**: 12 415 416**Parameters** 417 418| Name| Description| 419| -------- | -------- | 420| cencInfo | Pointer to an **OH_AVCencInfo** instance.| 421| encryptedBlockCount | Number of encrypted blocks.| 422| skippedBlockCount | Number of non-encrypted blocks.| 423| firstEncryptedOffset | Offset of the first encrypted payload.| 424| subsampleCount | Number of subsamples.| 425| subsamples | Pointer to the subsamples.| 426 427**Returns** 428 429Returns a result code defined in [OH_AVErrCode](_core.md#oh_averrcode). The following result codes are possible: 430 431**AV_ERR_OK** (value: 0): The operation is successful. 432 433**AV_ERR_INVALID_VAL** (value: 3): **cencInfo** is null, **subsampleCount** is greater than **DRM_KEY_MAX_SUB_SAMPLE_NUM**, or **subsamples** is null. 434