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