1/*
2 * Copyright (C) 2023 Huawei Device Co., Ltd.
3 * Licensed under the Apache License, Version 2.0 (the "License");
4 * you may not use this file except in compliance with the License.
5 * You may obtain a copy of the License at
6 *
7 *     http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software
10 * distributed under the License is distributed on an "AS IS" BASIS,
11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 * See the License for the specific language governing permissions and
13 * limitations under the License.
14 */
15
16/**
17 * @addtogroup Drm
18 * @{
19 *
20 * @brief Provides APIs of Drm.
21 * @kit DrmKit.
22 * @since 11
23 * @version 1.0
24 */
25
26/**
27 * @file native_mediakeysystem.h
28 * @brief Defines the Drm MediaKeySystem APIs. Provide following function:
29 * query if specific drm supported or not, create media key session,
30 * get and set configurations, get statistics, get content protection level,
31 * generate provision request, process provision response, event listening,
32 * get content protection level, manage offline media key etc..
33 * @library libnative_drm.z.so
34 * @syscap SystemCapability.Multimedia.Drm.Core
35 * @since 11
36 * @version 1.0
37 */
38
39#ifndef OHOS_DRM_NATIVE_MEDIA_KEY_SYSTEM_H
40#define OHOS_DRM_NATIVE_MEDIA_KEY_SYSTEM_H
41
42#include <stdint.h>
43#include <stdbool.h>
44#include <stdio.h>
45#include "native_drm_err.h"
46#include "native_drm_common.h"
47
48#ifdef __cplusplus
49extern "C" {
50#endif
51
52/**
53 * @brief Call back will be invoked when event triggers.
54 * @param eventType Event type.
55 * @param info Event info gotten from media key system.
56 * @param infoLen Event info len.
57 * @param extra Extra info gotten from media key system.
58 * @return DRM_ERR_INVALID_VAL when the params checked failure, return DRM_ERR_OK when function called successfully.
59 * @since 11
60 * @version 1.0
61 */
62typedef  Drm_ErrCode (*MediaKeySystem_Callback)(DRM_EventType eventType, uint8_t *info,
63    int32_t infoLen, char *extra);
64
65/**
66 * @brief Call back will be invoked when event triggers.
67 * @param mediaKeySystem MediaKeySystem instance.
68 * @param eventType Event type.
69 * @param info Event info gotten from media key system.
70 * @param infoLen Event info len.
71 * @param extra Extra info gotten from media key system.
72 * @return DRM_ERR_INVALID_VAL when the params checked failure, return DRM_ERR_OK when function called successfully.
73 * @since 12
74 * @version 1.0
75 */
76typedef Drm_ErrCode (*OH_MediaKeySystem_Callback)(MediaKeySystem *mediaKeySystem, DRM_EventType eventType,
77    uint8_t *info, int32_t infoLen, char *extra);
78
79/**
80 * @brief Set media key system event callback.
81 * @param mediaKeySystem Media key system instance.
82 * @param callback Callback to be set to the media key system.
83 * @return {@link DRM_ERR_OK} 0 - Success.
84 *         {@link DRM_ERR_INVALID_VAL} 24700503 - If the mediaKeySystem instance is nullptr or invalid,
85 *         or the mediaKeySession is nullptr or invalid.
86 * @since 12
87 * @version 1.0
88 */
89Drm_ErrCode OH_MediaKeySystem_SetCallback(MediaKeySystem *mediaKeySystem, OH_MediaKeySystem_Callback callback);
90
91/**
92 * @brief Acquire supported media key systems' name and uuid.
93 * @param descs Array used to save media key systems' name and uuid.
94 * @param count Used to indicate count of struct DRM_MediaKeySystemDescription.
95 * @return {@link DRM_ERR_OK} 0 - Success.
96 *         {@link DRM_ERR_INVALID_VAL} 24700503 - Probably caused by:
97 *         1.the description or the count is nullptr.
98 *         2. the size of the description array is smaller than the actual number obtained.
99 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
100 * @since 12
101 * @version 1.0
102 */
103Drm_ErrCode  OH_MediaKeySystem_GetMediaKeySystems(DRM_MediaKeySystemDescription *descs, uint32_t *count);
104
105/**
106 * @brief Query if media key system is supported.
107 * @param name Used to point a Digital Right Management solution.
108 * @return Supported or not in boolean.
109 * @since 11
110 * @version 1.0
111 */
112bool OH_MediaKeySystem_IsSupported(const char *name);
113/**
114 * @brief Query if media key system is supported.
115 * @param name Used to point a Digital Right Management solution.
116 * @param mimeType Used to specifies the media type.
117 * @return Supported or not in boolean.
118 * @since 11
119 * @version 1.0
120 */
121bool OH_MediaKeySystem_IsSupported2(const char *name, const char *mimeType);
122/**
123 * @brief Query if media key system is supported.
124 * @param name Used to point a Digital Right Management solution.
125 * @param mimeType Used to specifies the media type.
126 * @param contentProtectionLevel Used to specifies the ContentProtectionLevel.
127 * @return Supported or not in boolean.
128 * @since 11
129 * @version 1.0
130 */
131bool OH_MediaKeySystem_IsSupported3(const char *name, const char *mimeType,
132    DRM_ContentProtectionLevel contentProtectionLevel);
133
134/**
135 * @brief Creates a media key system instance from the name.
136 * @param name Secifies which drm system will be created by name.
137 * @param mediaKeySystem Media key system instance.
138 * @return {@link DRM_ERR_OK} 0 - Success.
139 *         {@link DRM_ERR_INVALID_VAL} 24700503 - Probably caused by:
140 *         1. the name is nullptr or the length of name is zero.
141 *         2. the mediaKeySystem is nullptr.
142 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
143 *         {@link DRM_ERR_SERVICE_DIED} 24700507 - Service died.
144 *         {@link DRM_ERR_MAX_SYSTEM_NUM_REACHED} 24700510 - The maximum number of media key systems is reached.
145 * @since 11
146 * @version 1.0
147 */
148Drm_ErrCode OH_MediaKeySystem_Create(const char *name, MediaKeySystem **mediaKeySystem);
149/**
150 * @brief Set media key system configuration value by name.
151 * @param mediaKeySystem Media key system instance.
152 * @param configName Configuration name string.
153 * @param value Configuration vaule string to be set.
154 * @return {@link DRM_ERR_OK} 0 - Success.
155 *         {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid.
156 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
157 * @since 11
158 * @version 1.0
159 */
160Drm_ErrCode OH_MediaKeySystem_SetConfigurationString(MediaKeySystem *mediaKeySystem,
161    const char *configName, const char *value);
162/**
163 * @brief Get media key system configuration value by name.
164 * @param mediaKeySystem Media key system instance.
165 * @param configName Configuration name string.
166 * @param value Configuration vaule string to be get.
167 * @param valueLen Configuration vaule string len for in buffer.
168 * @return {@link DRM_ERR_OK} 0 - Success.
169 *         {@link DRM_ERR_NO_MEMORY} 24700501 - Memory errors.
170 *         {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid.
171 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
172 * @since 11
173 * @version 1.0
174 */
175Drm_ErrCode OH_MediaKeySystem_GetConfigurationString(MediaKeySystem *mediaKeySystem,
176    const char *configName, char *value, int32_t valueLen);
177/**
178 * @brief Set media key system configuration value by name.
179 * @param mediaKeySystem Media key system instance.
180 * @param configName Configuration name string.
181 * @param value Configuration vaule in byte array to be set.
182 * @param valueLen Value array len.
183 * @return {@link DRM_ERR_OK} 0 - Success.
184 *         {@link DRM_ERR_NO_MEMORY} 24700501 - Memory errors.
185 *         {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid.
186 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
187 * @since 11
188 * @version 1.0
189 */
190Drm_ErrCode OH_MediaKeySystem_SetConfigurationByteArray(MediaKeySystem *mediaKeySystem,
191    const char *configName, uint8_t *value, int32_t valueLen);
192/**
193 * @brief Get media key system configuration value by name.
194 * @param mediaKeySystem Media key system instance.
195 * @param configName Configuration name string.
196 * @param value Configuration vaule in byte array to be get.
197 * @param valueLen Configuration vaule len for in buffer and out data.
198 * @return {@link DRM_ERR_OK} 0 - Success.
199 *         {@link DRM_ERR_NO_MEMORY} 24700501 - Memory errors.
200 *         {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid.
201 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
202 * @since 11
203 * @version 1.0
204 */
205Drm_ErrCode OH_MediaKeySystem_GetConfigurationByteArray(MediaKeySystem *mediaKeySystem,
206    const char *configName, uint8_t *value, int32_t *valueLen);
207/**
208 * @brief Get media key system statistics info.
209 * @param mediaKeySystem Media key system instance.
210 * @param statistics Statistic info gotten.
211 * @return {@link DRM_ERR_OK} 0 - Success.
212 *         {@link DRM_ERR_NO_MEMORY} 24700501 - Memory errors.
213 *         {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid.
214 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
215 * @since 11
216 * @version 1.0
217 */
218Drm_ErrCode OH_MediaKeySystem_GetStatistics(MediaKeySystem *mediaKeySystem, DRM_Statistics *statistics);
219/**
220 * @brief Get the max content protection level media key system supported.
221 * @param mediaKeySystem Media key system instance.
222 * @param contentProtectionLevel Content protection level.
223 * @return {@link DRM_ERR_OK} 0 - Success.
224 *         {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid.
225 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
226 * @since 11
227 * @version 1.0
228 */
229Drm_ErrCode OH_MediaKeySystem_GetMaxContentProtectionLevel(MediaKeySystem *mediaKeySystem,
230    DRM_ContentProtectionLevel *contentProtectionLevel);
231/**
232 * @brief Set media key system event callback.
233 * @param mediaKeySystem Media key system instance.
234 * @param callback Callback to be set to the media key system.
235 * @return {@link DRM_ERR_OK} 0 - Success.
236 *         {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid.
237 * @since 11
238 * @version 1.0
239 */
240Drm_ErrCode OH_MediaKeySystem_SetMediaKeySystemCallback(MediaKeySystem *mediaKeySystem,
241    MediaKeySystem_Callback callback);
242
243/**
244 * @brief Create a media key session instance.
245 * @param mediaKeySystem Media key system instance which will create the media key session.
246 * @param level Specifies the content protection level.
247 * @param mediaKeySession Media key session instance.
248 * @return {@link DRM_ERR_OK} 0 - Success.
249 *         {@link DRM_ERR_NO_MEMORY} 24700501 - Memory errors.
250 *         {@link DRM_ERR_INVALID_VAL} 24700503 - Probably caused by:
251 *         1. The parameter passed in is a null pointer or invalid.
252 *         2. the level is beyond reasonable range.
253 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
254 *         {@link DRM_ERR_SERVICE_DIED} 24700507 - Service died.
255 *         {@link DRM_ERR_MAX_SESSION_NUM_REACHED} 24700511 - The maximum number of media key sessions is reached.
256 * @since 11
257 * @version 1.0
258 */
259Drm_ErrCode OH_MediaKeySystem_CreateMediaKeySession(MediaKeySystem *mediaKeySystem,
260    DRM_ContentProtectionLevel *level, MediaKeySession **mediaKeySession);
261
262/**
263 * @brief Generate a media key system provision request.
264 * @param mediaKeySystem Media key system instance.
265 * @param request Provision request data sent to provision server.
266 * @param requestLen Provision request data len for in buffer and out data.
267 * @param defaultUrl Provision server URL.
268 * @param defaultUrlLen Provision server URL len for in buffer.
269 * @return {@link DRM_ERR_OK} 0 - Success.
270 *         {@link DRM_ERR_NO_MEMORY} 24700501 - Memory errors.
271 *         {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid.
272 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
273 * @since 11
274 * @version 1.0
275 */
276Drm_ErrCode OH_MediaKeySystem_GenerateKeySystemRequest(MediaKeySystem *mediaKeySystem, uint8_t *request,
277    int32_t *requestLen, char *defaultUrl, int32_t defaultUrlLen);
278
279/**
280 * @brief Process a media key system provision response.
281 * @param mediaKeySystem Media key system instance.
282 * @param response The provision reponse will be processed.
283 * @param responseLen The response len.
284 * @return {@link DRM_ERR_OK} 0 - Success.
285 *         {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid.
286 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
287 * @since 11
288 * @version 1.0
289 */
290Drm_ErrCode OH_MediaKeySystem_ProcessKeySystemResponse(MediaKeySystem *mediaKeySystem,
291    uint8_t *response, int32_t responseLen);
292
293/**
294 * @brief Get offline media key ids .
295 * @param mediaKeySystem Media key system instance.
296 * @param offlineMediaKeyIds Media key ids of all offline media keys.
297 * @return {@link DRM_ERR_OK} 0 - Success.
298 *         {@link DRM_ERR_NO_MEMORY} 24700501 - Memory errors.
299 *         {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid.
300 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
301 * @since 11
302 * @version 1.0
303 */
304Drm_ErrCode OH_MediaKeySystem_GetOfflineMediaKeyIds(MediaKeySystem *mediaKeySystem,
305    DRM_OfflineMediakeyIdArray *offlineMediaKeyIds);
306
307/**
308 * @brief Get offline media key status.
309 * @param mediaKeySystem Media key system instance.
310 * @param offlineMediaKeyId Offline media key identifier.
311 * @param offlineMediaKeyIdLen Offline media key identifier len.
312 * @param status The media key status gotten.
313 * @return {@link DRM_ERR_OK} 0 - Success.
314 *         {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid.
315 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
316 * @since 11
317 * @version 1.0
318 */
319Drm_ErrCode OH_MediaKeySystem_GetOfflineMediaKeyStatus(MediaKeySystem *mediaKeySystem,
320    uint8_t *offlineMediaKeyId, int32_t offlineMediaKeyIdLen, DRM_OfflineMediaKeyStatus *status);
321
322/**
323 * @brief Clear an offline media key by id.
324 * @param mediaKeySystem Media key system instance.
325 * @param offlineMediaKeyId Offline media key identifier.
326 * @param offlineMediaKeyIdLen Offline media key identifier len.
327 * @return {@link DRM_ERR_OK} 0 - Success.
328 *         {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid.
329 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
330 * @since 11
331 * @version 1.0
332 */
333Drm_ErrCode OH_MediaKeySystem_ClearOfflineMediaKeys(MediaKeySystem *mediaKeySystem,
334    uint8_t *offlineMediaKeyId, int32_t offlineMediaKeyIdLen);
335
336/**
337 * @brief Get certificate status of media key system.
338 * @param mediaKeySystem Media key system instance.
339 * @param certStatus Status will be gotten.
340 * @return {@link DRM_ERR_OK} 0 - Success.
341 *         {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid.
342 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
343 * @since 11
344 * @version 1.0
345 */
346Drm_ErrCode OH_MediaKeySystem_GetCertificateStatus(MediaKeySystem *mediaKeySystem,
347    DRM_CertificateStatus *certStatus);
348
349/**
350 * @brief Destroy a media key system instance.
351 * @param mediaKeySystem Secifies which media key system instance will be destroyed.
352 * @return {@link DRM_ERR_OK} 0 - Success.
353 *         {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid.
354 *         {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs.
355 * @since 11
356 * @version 1.0
357 */
358Drm_ErrCode OH_MediaKeySystem_Destroy(MediaKeySystem *mediaKeySystem);
359
360#ifdef __cplusplus
361}
362#endif
363
364#endif // OHOS_DRM_NATIVE_MEDIA_KEY_SYSTEM_H
365