1# native_cencinfo.h 2 3## Overview 4 5The file declares the native APIs used to set decryption parameters. 6 7**File to include**: <multimedia/player_framework/native_cencinfo.h> 8 9**Library**: libnative_media_avcencinfo.so 10 11**System capability**: SystemCapability.Multimedia.Media.Spliter 12 13**Since**: 12 14 15**Related module**: [Multimedia_Drm](capi-multimedia-drm.md) 16 17## Summary 18 19### Structs 20 21| Name| typedef Keyword| Description| 22| -- | -- | -- | 23| [DrmSubsample](capi-multimedia-drm-drmsubsample.md) | DrmSubsample | Describes the subsample type.| 24| [OH_AVBuffer](_core.md#oh_avbuffer) | OH_AVBuffer | Describes the audio/video buffer.| 25| [OH_AVCencInfo](capi-multimedia-drm-oh-avcencinfo.md) | OH_AVCencInfo | Describes the audio/video Common Encryption Scheme (CENC) information.| 26 27### Enums 28 29| Name| typedef Keyword| Description| 30| -- | -- | -- | 31| [DrmCencAlgorithm](#drmcencalgorithm) | DrmCencAlgorithm | Enumerates the DRM CENC algorithm types.| 32| [DrmCencInfoMode](#drmcencinfomode) | DrmCencInfoMode | Enumerates the modes for setting the key ID, IV, and subsample in the CENC information.| 33 34### Functions 35 36| Name| Description| 37| -- | -- | 38| [OH_AVCencInfo *OH_AVCencInfo_Create()](#oh_avcencinfo_create) | Creates an OH_AVCencInfo instance for setting the CENC information.| 39| [OH_AVErrCode OH_AVCencInfo_Destroy(OH_AVCencInfo *cencInfo)](#oh_avcencinfo_destroy) | Destroys an OH_AVCencInfo instance and clears internal resources. An 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 nullptr once the instance is destroyed.| 40| [OH_AVErrCode OH_AVCencInfo_SetAlgorithm(OH_AVCencInfo *cencInfo, enum DrmCencAlgorithm algo)](#oh_avcencinfo_setalgorithm) | Sets an encryption algorithm of the CENC information.| 41| [OH_AVErrCode OH_AVCencInfo_SetKeyIdAndIv(OH_AVCencInfo *cencInfo, uint8_t *keyId,uint32_t keyIdLen, uint8_t *iv, uint32_t ivLen)](#oh_avcencinfo_setkeyidandiv) | Sets the key ID and IV in the CENC information.| 42| [OH_AVErrCode OH_AVCencInfo_SetSubsampleInfo(OH_AVCencInfo *cencInfo, uint32_t encryptedBlockCount,uint32_t skippedBlockCount, uint32_t firstEncryptedOffset, uint32_t subsampleCount, DrmSubsample *subsamples)](#oh_avcencinfo_setsubsampleinfo) | Sets the subsample information in the CENC information.| 43| [OH_AVErrCode OH_AVCencInfo_SetMode(OH_AVCencInfo *cencInfo, enum DrmCencInfoMode mode)](#oh_avcencinfo_setmode) | Sets the CENC information mode.| 44| [OH_AVErrCode OH_AVCencInfo_SetAVBuffer(OH_AVCencInfo *cencInfo, OH_AVBuffer *buffer)](#oh_avcencinfo_setavbuffer) | Sets the CENC information to an AVBuffer.| 45 46### Macros 47 48| Name| Description| 49| -------- | -------- | 50| DRM_KEY_ID_SIZE 16 | The length of the key ID is 16 bytes.<br>**Since**: 12| 51| DRM_KEY_IV_SIZE 16 | The length of the Initialization Vector (IV) is 16 bytes.<br>**Since**: 12| 52| DRM_KEY_MAX_SUB_SAMPLE_NUM 64 | The maximum number of subsamples is 64.<br>**Since**: 12 53 | 54 55## Enum Description 56 57### DrmCencAlgorithm 58 59``` 60enum DrmCencAlgorithm 61``` 62 63**Description** 64 65Enumerates the DRM CENC algorithm types. 66 67**Since**: 12 68 69| Value| Description| 70| -- | -- | 71| DRM_ALG_CENC_UNENCRYPTED = 0x0 | No encryption algorithm is used.| 72| DRM_ALG_CENC_AES_CTR = 0x1 | AES CTR algorithm.| 73| DRM_ALG_CENC_AES_WV = 0x2 | AES WV algorithm.| 74| DRM_ALG_CENC_AES_CBC = 0x3 | AES CBC algorithm.| 75| DRM_ALG_CENC_SM4_CBC = 0x4 | SM4 CBC algorithm.| 76| DRM_ALG_CENC_SM4_CTR = 0x5 | SM4 CTR algorithm.| 77 78### DrmCencInfoMode 79 80``` 81enum DrmCencInfoMode 82``` 83 84**Description** 85 86Enumerates the modes for setting the key ID, IV, and subsample in the CENC information. 87 88**Since**: 12 89 90| Value| Description| 91| -- | -- | 92| DRM_CENC_INFO_KEY_IV_SUBSAMPLES_SET = 0x0 | The key ID, IV, and subsample are set.| 93| DRM_CENC_INFO_KEY_IV_SUBSAMPLES_NOT_SET = 0x1 | The key ID, IV, and subsample are not set.| 94 95 96## Function Description 97 98### OH_AVCencInfo_Create() 99 100``` 101OH_AVCencInfo *OH_AVCencInfo_Create() 102``` 103 104**Description** 105 106Creates an OH_AVCencInfo instance for setting the CENC information. 107 108**System capability**: SystemCapability.Multimedia.Media.Spliter 109 110**Since**: 12 111 112**Returns** 113 114| Type| Description| 115| -- | -- | 116| [OH_AVCencInfo](capi-multimedia-drm-oh-avcencinfo.md) * | Pointer to the OH_AVCencInfo instance created. If the operation fails, nullptr is returned.<br>The 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.| 117 118### OH_AVCencInfo_Destroy() 119 120``` 121OH_AVErrCode OH_AVCencInfo_Destroy(OH_AVCencInfo *cencInfo) 122``` 123 124**Description** 125 126Destroys an OH_AVCencInfo instance and clears internal resources.<br>An 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 nullptr once the instance is destroyed. 127 128**System capability**: SystemCapability.Multimedia.Media.Spliter 129 130**Since**: 12 131 132 133**Parameters** 134 135| Name| Description| 136| -- | -- | 137| [OH_AVCencInfo](capi-multimedia-drm-oh-avcencinfo.md) *cencInfo | Pointer to an OH_AVCencInfo instance.| 138 139**Returns** 140 141| Type| Description| 142| -- | -- | 143| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The value of **cencInfo** is null.| 144 145### OH_AVCencInfo_SetAlgorithm() 146 147``` 148OH_AVErrCode OH_AVCencInfo_SetAlgorithm(OH_AVCencInfo *cencInfo, enum DrmCencAlgorithm algo) 149``` 150 151**Description** 152 153Sets an encryption algorithm of the CENC information. 154 155**System capability**: SystemCapability.Multimedia.Media.Spliter 156 157**Since**: 12 158 159 160**Parameters** 161 162| Name| Description| 163| -- | -- | 164| [OH_AVCencInfo](capi-multimedia-drm-oh-avcencinfo.md) *cencInfo | Pointer to an OH_AVCencInfo instance.| 165| [enum DrmCencAlgorithm](#drmcencalgorithm) algo | Encryption algorithm.| 166 167**Returns** 168 169| Type| Description| 170| -- | -- | 171| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The value of **cencInfo** is null.| 172 173### OH_AVCencInfo_SetKeyIdAndIv() 174 175``` 176OH_AVErrCode OH_AVCencInfo_SetKeyIdAndIv(OH_AVCencInfo *cencInfo, uint8_t *keyId,uint32_t keyIdLen, uint8_t *iv, uint32_t ivLen) 177``` 178 179**Description** 180 181Sets the key ID and IV in the CENC information. 182 183**System capability**: SystemCapability.Multimedia.Media.Spliter 184 185**Since**: 12 186 187 188**Parameters** 189 190| Name| Description| 191| -- | -- | 192| [OH_AVCencInfo](capi-multimedia-drm-oh-avcencinfo.md) *cencInfo | Pointer to an OH_AVCencInfo instance.| 193| uint8_t *keyId | Pointer to the key ID.| 194| uint32_t keyIdLen | Length of the key ID.| 195| uint8_t *iv | Pointer to the IV.| 196| uint32_t ivLen | Length of the IV.| 197 198**Returns** 199 200| Type| Description| 201| -- | -- | 202| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The value of **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.| 203 204### OH_AVCencInfo_SetSubsampleInfo() 205 206``` 207OH_AVErrCode OH_AVCencInfo_SetSubsampleInfo(OH_AVCencInfo *cencInfo, uint32_t encryptedBlockCount,uint32_t skippedBlockCount, uint32_t firstEncryptedOffset, uint32_t subsampleCount, DrmSubsample *subsamples) 208``` 209 210**Description** 211 212Sets the subsample information in the CENC information. 213 214**System capability**: SystemCapability.Multimedia.Media.Spliter 215 216**Since**: 12 217 218 219**Parameters** 220 221| Name| Description| 222| -- | -- | 223| [OH_AVCencInfo](capi-multimedia-drm-oh-avcencinfo.md) *cencInfo | Pointer to an OH_AVCencInfo instance.| 224| uint32_t encryptedBlockCount | Number of encrypted blocks.| 225| uint32_t skippedBlockCount | Number of non-encrypted blocks.| 226| uint32_t firstEncryptedOffset | Offset of the first encrypted payload.| 227| uint32_t subsampleCount | Number of subsamples.| 228| [DrmSubsample](capi-multimedia-drm-drmsubsample.md) *subsamples | Pointer to the subsamples.| 229 230**Returns** 231 232| Type| Description| 233| -- | -- | 234| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The value of **cencInfo** is null, **subsampleCount** is greater than **DRM_KEY_MAX_SUB_SAMPLE_NUM**, or **subsamples** is null.| 235 236### OH_AVCencInfo_SetMode() 237 238``` 239OH_AVErrCode OH_AVCencInfo_SetMode(OH_AVCencInfo *cencInfo, enum DrmCencInfoMode mode) 240``` 241 242**Description** 243 244Sets the CENC information mode. 245 246**System capability**: SystemCapability.Multimedia.Media.Spliter 247 248**Since**: 12 249 250 251**Parameters** 252 253| Name| Description| 254| -- | -- | 255| [OH_AVCencInfo](capi-multimedia-drm-oh-avcencinfo.md) *cencInfo | Pointer to an OH_AVCencInfo instance.| 256| [enum DrmCencInfoMode](#drmcencinfomode) mode | CENC information mode, indicating whether the key ID, IV, and subsample are set.| 257 258**Returns** 259 260| Type| Description| 261| -- | -- | 262| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The value of **cencInfo** is null.| 263 264### OH_AVCencInfo_SetAVBuffer() 265 266``` 267OH_AVErrCode OH_AVCencInfo_SetAVBuffer(OH_AVCencInfo *cencInfo, OH_AVBuffer *buffer) 268``` 269 270**Description** 271 272Sets the CENC information to an AVBuffer. 273 274**System capability**: SystemCapability.Multimedia.Media.Spliter 275 276**Since**: 12 277 278 279**Parameters** 280 281| Name| Description| 282| -- | -- | 283| [OH_AVCencInfo](capi-multimedia-drm-oh-avcencinfo.md) *cencInfo | Pointer to an OH_AVCencInfo instance.| 284| [OH_AVBuffer](_core.md#oh_avbuffer) *buffer | Pointer to the frame buffer that carries data.| 285 286**Returns** 287 288| Type| Description| 289| -- | -- | 290| [OH_AVErrCode](_core.md#oh_averrcode-1) | **AV_ERR_OK**: The operation is successful.<br>**AV_ERR_INVALID_VAL**: The value of **cencInfo**, **buffer**, **buffer->buffer_**, or **buffer->buffer_->meta_** is null.| 291