1 /* 2 * Copyright (C) 2024 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 MediaAssetManager 18 * @{ 19 * 20 * @brief Provides APIs of request capability for Media Source. 21 * 22 * The OH_MediaAssetManager structure and MediaLibrary_RequestId type are used to request media library resources. 23 * The request can be cancelled using the request ID. 24 * 25 * @since 12 26 */ 27 28 /** 29 * @file media_asset_base_capi.h 30 * 31 * @brief Defines the structure and enumeration for Media Asset Manager. 32 * 33 * OH_MediaAssetManager structure: This structure provides the ability to request resources from a media library. \n 34 * MediaLibrary_RequestId type: This type is returned when requesting a media library resource. 35 * The request ID is used to cancel the request. \n 36 * MediaLibrary_DeliveryMode enumeration: This enumeration defines the delivery mode of the requested resources. \n 37 * OH_MediaLibrary_OnDataPrepared function pointer: This function is called when the requested source is prepared. \n 38 * MediaLibrary_RequestOptions structure: This structure provides options for requesting media library resources. \n 39 * 40 * @kit MediaLibraryKit 41 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core 42 * @library libmedia_asset_manager.so 43 * @since 12 44 */ 45 46 #ifndef MULTIMEDIA_MEDIA_LIBRARY_NATIVE_MEDIA_ASSET_BASE_H 47 #define MULTIMEDIA_MEDIA_LIBRARY_NATIVE_MEDIA_ASSET_BASE_H 48 49 #include <stdint.h> 50 51 #include "image_source_native.h" 52 53 #ifdef __cplusplus 54 extern "C" { 55 #endif 56 57 /** 58 * @brief Define UUID max length 59 * 60 * This constant defines the maximum length of a UUID string. 61 * 62 * @since 12 63 */ 64 static const int32_t UUID_STR_MAX_LENGTH = 37; 65 66 /** 67 * @brief Define Media Asset Manager 68 * 69 * This structure provides the ability to request media library resources. 70 * Null pointer is returned if the creation fails. 71 * 72 * @since 12 73 */ 74 typedef struct OH_MediaAssetManager OH_MediaAssetManager; 75 76 /** 77 * @brief Define Media Asset Change Request 78 * 79 * This structure provides the ability to handle a media asset change request. 80 * 81 * @since 12 82 */ 83 typedef struct OH_MediaAssetChangeRequest OH_MediaAssetChangeRequest; 84 85 /** 86 * @brief Define Moving Photo 87 * 88 * This structure provides the ability to obtain information about moving photo. 89 * 90 * @since 13 91 */ 92 typedef struct OH_MovingPhoto OH_MovingPhoto; 93 94 /** 95 * @brief Define Media Asset 96 * 97 * This structure provides the ability to encapsulate file asset attributes. 98 * 99 * @since 12 100 */ 101 typedef struct OH_MediaAsset OH_MediaAsset; 102 103 /** 104 * @brief Define MediaLibrary_RequestId 105 * 106 * This type is returned when requesting a media library resource. 107 * The request id is used to cancel the request. 108 * The value is all zero like "00000000-0000-0000-0000-000000000000" if the request fails. 109 * 110 * @since 12 111 */ 112 typedef struct MediaLibrary_RequestId { 113 /*request id*/ 114 char requestId[UUID_STR_MAX_LENGTH]; 115 } MediaLibrary_RequestId; 116 117 /** 118 * @brief Enum for media library error code. 119 * 120 * @since 12 121 */ 122 typedef enum MediaLibrary_ErrorCode { 123 /** 124 * @error Media library result is ok. 125 */ 126 MEDIA_LIBRARY_OK = 0, 127 128 /** 129 * @error Permission is denied. 130 */ 131 MEDIA_LIBRARY_PERMISSION_DENIED = 201, 132 133 /** 134 * @error Mandatory parameters are left unspecified 135 * or incorrect parameter types or parameter verification failed. 136 */ 137 MEDIA_LIBRARY_PARAMETER_ERROR = 401, 138 139 /** 140 * @error File does not exist. 141 */ 142 MEDIA_LIBRARY_NO_SUCH_FILE = 23800101, 143 144 /** 145 * @error Invalid display name. 146 */ 147 MEDIA_LIBRARY_INVALID_DISPLAY_NAME = 23800102, 148 149 /** 150 * @error Invalid asset uri. 151 */ 152 MEDIA_LIBRARY_INVALID_ASSET_URI = 23800103, 153 154 /** 155 * @error Member is not a valid PhotoKey. 156 */ 157 MEDIA_LIBRARY_INVALID_PHOTO_KEY = 23800104, 158 159 /** 160 * @error Operation is not supported. 161 */ 162 MEDIA_LIBRARY_OPERATION_NOT_SUPPORTED = 23800201, 163 164 /** 165 * @error Internal system error. 166 * It is recommended to retry and check the logs. 167 * Possible causes: 168 * 1. Database corrupted. 169 * 2. The file system is abnormal. 170 * 3. The IPC request timed out. 171 */ 172 MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR = 23800301, 173 } MediaLibrary_ErrorCode; 174 175 /** 176 * @brief Delivery Mode 177 * 178 * This enumeration defines the delivery mode of the requested resources. 179 * The delivery mode can be set to fast mode, high quality mode, or balanced mode. 180 * 181 * @since 12 182 */ 183 typedef enum MediaLibrary_DeliveryMode { 184 /*delivery fast mode*/ 185 MEDIA_LIBRARY_FAST_MODE = 0, 186 /*delivery high quality mode*/ 187 MEDIA_LIBRARY_HIGH_QUALITY_MODE = 1, 188 /*delivery balanced mode*/ 189 MEDIA_LIBRARY_BALANCED_MODE = 2 190 } MediaLibrary_DeliveryMode; 191 192 /** 193 * @brief Request Options 194 * 195 * This structure provides options for requesting media library resources. 196 * 197 * @since 12 198 */ 199 typedef struct MediaLibrary_RequestOptions { 200 /*delivery mode*/ 201 MediaLibrary_DeliveryMode deliveryMode; 202 } MediaLibrary_RequestOptions; 203 204 /** 205 * @brief Enum for media type. 206 * 207 * @since 12 208 */ 209 typedef enum MediaLibrary_MediaType { 210 /*image asset*/ 211 MEDIA_LIBRARY_IMAGE = 1, 212 /*video asset*/ 213 MEDIA_LIBRARY_VIDEO = 2 214 } MediaLibrary_MediaType; 215 216 /** 217 * @brief Enum for media asset subtype. 218 * 219 * @since 12 220 */ 221 typedef enum MediaLibrary_MediaSubType { 222 /*default Photo Type*/ 223 MEDIA_LIBRARY_DEFAULT = 0, 224 /*moving Photo Type*/ 225 MEDIA_LIBRARY_MOVING_PHOTO = 3, 226 /*burst Photo Type*/ 227 MEDIA_LIBRARY_BURST = 4 228 } MediaLibrary_MediaSubType; 229 230 /** 231 * @brief Enum for resource types. 232 * 233 * @since 12 234 */ 235 typedef enum MediaLibrary_ResourceType { 236 /*image resource*/ 237 MEDIA_LIBRARY_IMAGE_RESOURCE = 1, 238 /*video resource*/ 239 MEDIA_LIBRARY_VIDEO_RESOURCE = 2 240 } MediaLibrary_ResourceType; 241 242 /** 243 * @brief Enum for image file Type. 244 * 245 * @since 12 246 */ 247 typedef enum MediaLibrary_ImageFileType { 248 /*JPEG type*/ 249 MEDIA_LIBRARY_IMAGE_JPEG = 1 250 } MediaLibrary_ImageFileType; 251 252 /** 253 * @brief Enum for media quality. 254 * 255 * @since 12 256 */ 257 typedef enum MediaLibrary_MediaQuality { 258 /*fast quality*/ 259 MEDIA_LIBRARY_QUALITY_FAST = 1, 260 /*full quality*/ 261 MEDIA_LIBRARY_QUALITY_FULL = 2 262 } MediaLibrary_MediaQuality; 263 264 /** 265 * @brief Enum for media content type. 266 * 267 * @since 12 268 */ 269 typedef enum MediaLibrary_MediaContentType { 270 /*compressed media content type*/ 271 MEDIA_LIBRARY_COMPRESSED = 1, 272 /*picture object media content type*/ 273 MEDIA_LIBRARY_PICTURE_OBJECT = 2 274 } MediaLibrary_MediaContentType; 275 276 /** 277 * @brief Called when a requested source is prepared. 278 * 279 * This function is called when the requested source is prepared. 280 * 281 * @param result Results of the processing of the requested resources. 282 * @param requestId Request ID. 283 * @since 12 284 */ 285 typedef void (*OH_MediaLibrary_OnDataPrepared)(int32_t result, MediaLibrary_RequestId requestId); 286 287 /** 288 * @brief Called when a requested image source is prepared. 289 * 290 * This function is called when the requested image source is prepared. 291 * 292 * @param result results {@link MediaLibrary_ErrorCode} of the processing of the requested resources. 293 * @param requestId indicates the {@link MediaLibrary_RequestId} of the request. 294 * @param mediaQuality the {@link MediaLibrary_MediaQuality} of the requested source. 295 * @param type the {@link MediaLibrary_MediaContentType} of the requested source. 296 * @param imageSourceNative it used to obtain {@link OH_ImageSourceNative} information when image source is prepared. 297 * @since 12 298 */ 299 typedef void (*OH_MediaLibrary_OnImageDataPrepared)(MediaLibrary_ErrorCode result, 300 MediaLibrary_RequestId requestId, MediaLibrary_MediaQuality mediaQuality, MediaLibrary_MediaContentType type, 301 OH_ImageSourceNative* imageSourceNative); 302 303 /** 304 * @brief Called when a requested moving photo is prepared. 305 * 306 * This function is called when the requested moving photo is prepared. 307 * 308 * @param result results {@link MediaLibrary_ErrorCode} of the processing of the requested resources. 309 * @param requestId indicates the {@link MediaLibrary_RequestId} of the request. 310 * @param mediaQuality the {@link MediaLibrary_MediaQuality} of the requested source. 311 * @param type the {@link MediaLibrary_MediaContentType} of the requested source. 312 * @param movingPhoto it used to obtain {@link OH_MovingPhoto} information when the data is prepared. 313 * @since 13 314 */ 315 typedef void (*OH_MediaLibrary_OnMovingPhotoDataPrepared)(MediaLibrary_ErrorCode result, 316 MediaLibrary_RequestId requestId, MediaLibrary_MediaQuality mediaQuality, MediaLibrary_MediaContentType type, 317 OH_MovingPhoto* movingPhoto); 318 319 #ifdef __cplusplus 320 } 321 #endif 322 323 #endif // MULTIMEDIA_MEDIA_LIBRARY_NATIVE_MEDIA_ASSET_BASE_H 324 /** @} */