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_mediakeysession.h 28 * @brief Defines the Drm MediaKeySession APIs. Provide following function: 29 * generate media key request, process media key response, event listening, 30 * get content protection level, check media key status, remove media key etc.. 31 * @library libnative_drm.z.so 32 * @syscap SystemCapability.Multimedia.Drm.Core 33 * @since 11 34 * @version 1.0 35 */ 36 37#ifndef OHOS_DRM_NATIVE_MEDIA_KEY_SESSION_H 38#define OHOS_DRM_NATIVE_MEDIA_KEY_SESSION_H 39 40#include <stdint.h> 41#include <stdbool.h> 42#include <stdio.h> 43#include "native_drm_err.h" 44#include "native_drm_common.h" 45 46#ifdef __cplusplus 47extern "C" 48{ 49#endif 50 51/** 52 * @brief Call back will be invoked when event triggers. 53 * @param eventType Event type. 54 * @param info Event info gotten from media key session. 55 * @param infoLen Event info len. 56 * @param extra Extra info gotten from media key session. 57 * @return Drm_ErrCode. 58 * @since 11 59 * @version 1.0 60 */ 61typedef Drm_ErrCode (*MediaKeySession_EventCallback)(DRM_EventType eventType, uint8_t *info, 62 int32_t infoLen, char *extra); 63 64/** 65 * @brief Call back will be invoked when key changes. 66 * @param keysInfo Key info gotten from media key system. 67 * @param newKeysAvailable Whether new keys available. 68 * @return DRM_ERR_INVALID_VAL when the params checked failure, return DRM_ERR_OK when function called successfully. 69 * @since 11 70 * @version 1.0 71 */ 72typedef Drm_ErrCode (*MediaKeySession_KeyChangeCallback)(DRM_KeysInfo *keysInfo, bool newKeysAvailable); 73 74/** 75 * @brief MediaKeySession_Callback struct, used to listen event like key expired and key change etc.. 76 * @since 11 77 * @version 1.0 78 */ 79typedef struct MediaKeySession_Callback { 80 /** 81 * Normal event callback like key expired etc.. 82 */ 83 MediaKeySession_EventCallback eventCallback; 84 /** 85 * Key change callback for keys change event. 86 */ 87 MediaKeySession_KeyChangeCallback keyChangeCallback; 88} MediaKeySession_Callback; 89 90/** 91 * @brief Call back will be invoked when event triggers. 92 * @param mediaKeySessoin MediaKeySession instance. 93 * @param eventType Event type. 94 * @param info Event info gotten from media key session. 95 * @param infoLen Event info len. 96 * @param extra Extra info gotten from media key session. 97 * @return Drm_ErrCode. 98 * @since 12 99 * @version 1.0 100 */ 101typedef Drm_ErrCode (*OH_MediaKeySession_EventCallback)(MediaKeySession *mediaKeySessoin, DRM_EventType eventType, 102 uint8_t *info, int32_t infoLen, char *extra); 103 104/** 105 * @brief Call back will be invoked when key changes. 106 * @param mediaKeySessoin MediaKeySession instance. 107 * @param keysInfo Key info gotten from media key system. 108 * @param newKeysAvailable Whether new keys available. 109 * @return DRM_ERR_INVALID_VAL when the params checked failure, return DRM_ERR_OK when function called successfully. 110 * @since 12 111 * @version 1.0 112 */ 113typedef Drm_ErrCode (*OH_MediaKeySession_KeyChangeCallback)(MediaKeySession *mediaKeySessoin, DRM_KeysInfo *keysInfo, 114 bool newKeysAvailable); 115 116/** 117 * @brief MediaKeySession_Callback struct, used to listen event like key expired and key change etc.. 118 * @since 12 119 * @version 1.0 120 */ 121typedef struct OH_MediaKeySession_Callback { 122 /** 123 * Normal event callback like key expired etc.. 124 */ 125 OH_MediaKeySession_EventCallback eventCallback; 126 /** 127 * Key change callback for keys change event. 128 */ 129 OH_MediaKeySession_KeyChangeCallback keyChangeCallback; 130} OH_MediaKeySession_Callback; 131 132/** 133 * @brief Generate media key request. 134 * @param mediaKeySession Media key session instance. 135 * @param info Media key request info. 136 * @param mediaKeyRequest Media key request. 137 * @return {@link DRM_ERR_OK} 0 - Success. 138 * {@link DRM_ERR_NO_MEMORY} 24700501 - Memory errors. 139 * {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid. 140 * {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs. 141 * @since 11 142 * @version 1.0 143 */ 144Drm_ErrCode OH_MediaKeySession_GenerateMediaKeyRequest(MediaKeySession *mediaKeySession, 145 DRM_MediaKeyRequestInfo *info, DRM_MediaKeyRequest *mediaKeyRequest); 146 147/** 148 * @brief Process media key response. 149 * @param mediaKeySession Media key session instance. 150 * @param response Media Key resposne. 151 * @param responseLen Media Key resposne len. 152 * @param offlineMediaKeyId Offline media key identifier. 153 * @param offlineMediaKeyIdLen Offline media key identifier len for in buffer and out data. 154 * @return {@link DRM_ERR_OK} 0 - Success. 155 * {@link DRM_ERR_NO_MEMORY} 24700501 - Memory errors. 156 * {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid. 157 * {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs. 158 * @since 11 159 * @version 1.0 160 */ 161Drm_ErrCode OH_MediaKeySession_ProcessMediaKeyResponse(MediaKeySession *mediaKeySession, 162 uint8_t *response, int32_t responseLen, uint8_t *offlineMediaKeyId, int32_t *offlineMediaKeyIdLen); 163 164/** 165 * @brief Check media key status. 166 * @param mediaKeySession Media key session instance. 167 * @param mediaKeyStatus Media key status. 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_MediaKeySession_CheckMediaKeyStatus(MediaKeySession *mediaKeySessoin, 176 DRM_MediaKeyStatus *mediaKeyStatus); 177 178/** 179 * @brief Clear media keys of the current session . 180 * @param mediaKeySession Media key session instance. 181 * @return {@link DRM_ERR_OK} 0 - Success. 182 * {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid. 183 * {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs. 184 * @since 11 185 * @version 1.0 186 */ 187Drm_ErrCode OH_MediaKeySession_ClearMediaKeys(MediaKeySession *mediaKeySessoin); 188 189/** 190 * @brief Generate offline media key release request. 191 * @param mediaKeySession Media key session instance. 192 * @param offlineMediaKeyId Offline media key identifier. 193 * @param offlineMediaKeyIdLen Offline media key identifier len. 194 * @param releaseRequest Media Key release request. 195 * @param releaseRequestLen Media Key release request len for in buffer and out data. 196 * @return {@link DRM_ERR_OK} 0 - Success. 197 * {@link DRM_ERR_NO_MEMORY} 24700501 - Memory errors. 198 * {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid. 199 * {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs. 200 * @since 11 201 * @version 1.0 202 */ 203Drm_ErrCode OH_MediaKeySession_GenerateOfflineReleaseRequest(MediaKeySession *mediaKeySessoin, 204 uint8_t *offlineMediaKeyId, int32_t offlineMediaKeyIdLen, uint8_t *releaseRequest, 205 int32_t *releaseRequestLen); 206 207/** 208 * @brief Process offline media key release response. 209 * @param mediaKeySession Media key session instance. 210 * @param offlineMediaKeyId Offline media key identifier. 211 * @param offlineMediaKeyIdLen Offline media key identifier len. 212 * @param releaseReponse Media Key resposne. 213 * @param releaseReponseLen Media Key resposne len. 214 * @return {@link DRM_ERR_OK} 0 - Success. 215 * {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid. 216 * {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs. 217 * @since 11 218 * @version 1.0 219 */ 220Drm_ErrCode OH_MediaKeySession_ProcessOfflineReleaseResponse(MediaKeySession *mediaKeySessoin, 221 uint8_t *offlineMediaKeyId, int32_t offlineMediaKeyIdLen, uint8_t *releaseReponse, 222 int32_t releaseReponseLen); 223 224/** 225 * @brief Restore offline media keys by ID. 226 * @param mediaKeySession Media key session instance. 227 * @param offlineMediaKeyId Offline media key identifier. 228 * @param offlineMediaKeyIdLen Offline media key identifier len. 229 * @return {@link DRM_ERR_OK} 0 - Success. 230 * {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid. 231 * {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs. 232 * @since 11 233 * @version 1.0 234 */ 235Drm_ErrCode OH_MediaKeySession_RestoreOfflineMediaKeys(MediaKeySession *mediaKeySessoin, 236 uint8_t *offlineMediaKeyId, int32_t offlineMediaKeyIdLen); 237 238/** 239 * @brief Get content protection level of the session. 240 * @param mediaKeySession Media key session instance. 241 * @param contentProtectionLevel Content protection level. 242 * @return {@link DRM_ERR_OK} 0 - Success. 243 * {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid. 244 * {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs. 245 * @since 11 246 * @version 1.0 247 */ 248Drm_ErrCode OH_MediaKeySession_GetContentProtectionLevel(MediaKeySession *mediaKeySessoin, 249 DRM_ContentProtectionLevel *contentProtectionLevel); 250 251/** 252 * @brief Whether the encrypted content require a secure decoder or not. 253 * @param mediaKeySession Media key session instance. 254 * @param mimeType The media type. 255 * @param status Whether secure decoder is required. 256 * @return {@link DRM_ERR_OK} 0 - Success. 257 * {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid. 258 * {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs. 259 * @since 11 260 * @version 1.0 261 */ 262Drm_ErrCode OH_MediaKeySession_RequireSecureDecoderModule(MediaKeySession *mediaKeySessoin, 263 const char *mimeType, bool *status); 264 265/** 266 * @brief Set media key session event callback. 267 * @param mediaKeySession Media key session instance. 268 * @param callback Callback to be set to the media key session. 269 * @return {@link DRM_ERR_OK} 0 - Success. 270 * {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid. 271 * @since 11 272 * @version 1.0 273 */ 274Drm_ErrCode OH_MediaKeySession_SetMediaKeySessionCallback(MediaKeySession *mediaKeySessoin, 275 MediaKeySession_Callback *callback); 276 277/** 278 * @brief Set media key session event callback. 279 * @param mediaKeySession Media key session instance. 280 * @param callback Callback to be set to the media key session. 281 * @return {@link DRM_ERR_OK} 0 - Success. 282 * {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid. 283 * @since 12 284 * @version 1.0 285 */ 286Drm_ErrCode OH_MediaKeySession_SetCallback(MediaKeySession *mediaKeySessoin, 287 OH_MediaKeySession_Callback *callback); 288 289/** 290 * @brief Release the resource before the session gonna be unused. 291 * @param mediaKeySession Media key session instance. 292 * @return {@link DRM_ERR_OK} 0 - Success. 293 * {@link DRM_ERR_INVALID_VAL} 24700503 - The parameter passed in is a null pointer or invalid. 294 * {@link DRM_ERR_UNKNOWN} 24700506 - Internal error occurred, it is recommended to check the logs. 295 * @since 11 296 * @version 1.0 297 */ 298Drm_ErrCode OH_MediaKeySession_Destroy(MediaKeySession *mediaKeySessoin); 299 300#ifdef __cplusplus 301} 302#endif 303 304#endif // OHOS_DRM_NATIVE_MEDIA_KEY_SYSTEM_H 305