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 49 extern "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 */ 62 typedef 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 */ 76 typedef 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 */ 89 Drm_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 */ 103 Drm_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 */ 112 bool 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 */ 121 bool 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 */ 131 bool 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 */ 148 Drm_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 */ 160 Drm_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 */ 175 Drm_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 */ 190 Drm_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 */ 205 Drm_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 */ 218 Drm_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 */ 229 Drm_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 */ 240 Drm_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 */ 259 Drm_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 */ 276 Drm_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 */ 290 Drm_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 */ 304 Drm_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 */ 319 Drm_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 */ 333 Drm_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 */ 346 Drm_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 */ 358 Drm_ErrCode OH_MediaKeySystem_Destroy(MediaKeySystem *mediaKeySystem); 359 360 #ifdef __cplusplus 361 } 362 #endif 363 364 #endif // OHOS_DRM_NATIVE_MEDIA_KEY_SYSTEM_H 365