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 "multimedia/image_framework/image/image_source_native.h"
52
53#ifdef __cplusplus
54extern "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 */
64static 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 */
74typedef 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 */
83typedef 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 */
92typedef 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 */
101typedef 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 */
112typedef 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 */
122typedef 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 */
183typedef 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 */
199typedef 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 */
209typedef 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 */
221typedef 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 */
235typedef 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 */
247typedef 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 */
257typedef 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 */
269typedef 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 */
285typedef 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 */
299typedef 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 */
315typedef 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/** @} */
325