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 * @since 12
23 */
24
25/**
26 * @file media_asset_manager_capi.h
27 *
28 * @brief Defines the media asset manager APIs.
29 *
30 * Uses the Native APIs provided by Media Asset Manager
31 * to reqeust media source.
32 *
33 * @kit MediaLibraryKit
34 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core
35 * @library libmedia_asset_manager.so
36 * @since 12
37 */
38
39#ifndef MULTIMEDIA_MEDIA_LIBRARY_NATIVE_MEDIA_ASSET_MANAGER_H
40#define MULTIMEDIA_MEDIA_LIBRARY_NATIVE_MEDIA_ASSET_MANAGER_H
41
42#include <stdbool.h>
43
44#include "media_asset_base_capi.h"
45
46#ifdef __cplusplus
47extern "C" {
48#endif
49
50/**
51 * @brief Create a media asset manager.
52 *
53 * @return Returns a pointer to an OH_MediaAssetManager instance.
54 * @since 12
55*/
56OH_MediaAssetManager* OH_MediaAssetManager_Create(void);
57
58/**
59 * @brief Request image source with dest path.
60 *
61 * @permission ohos.permission.READ_IMAGEVIDEO
62 * @param manager Pointer to an OH_MediaAssetManager instance.
63 * @param uri The uri of the requested image resource.
64 * @param requestOptions Options model for requesting resource.
65 * @param destPath Destination address of the requested resource.
66 * @param callback Called when a requested source is prepared.
67 * @return Return Request id.
68 * @since 12
69*/
70MediaLibrary_RequestId OH_MediaAssetManager_RequestImageForPath(OH_MediaAssetManager* manager, const char* uri,
71    MediaLibrary_RequestOptions requestOptions, const char* destPath, OH_MediaLibrary_OnDataPrepared callback);
72
73/**
74 * @brief Request video source with dest path.
75 *
76 * @permission ohos.permission.READ_IMAGEVIDEO
77 * @param manager Pointer to an OH_MediaAssetManager instance.
78 * @param uri The uri of the requested video resource.
79 * @param requestOptions Options model for requesting resource.
80 * @param destPath Destination address of the requested resource.
81 * @param callback Called when a requested source is prepared.
82 * @return Return Request id.
83 * @since 12
84*/
85MediaLibrary_RequestId OH_MediaAssetManager_RequestVideoForPath(OH_MediaAssetManager* manager, const char* uri,
86    MediaLibrary_RequestOptions requestOptions, const char* destPath, OH_MediaLibrary_OnDataPrepared callback);
87
88/**
89 * @brief Cancel request by request id.
90 *
91 * @permission ohos.permission.READ_IMAGEVIDEO
92 * @param manager Pointer to an OH_MediaAssetManager instance.
93 * @param requestId The request id to be canceled.
94 * @return Returns true if the request is canceled successfully; returns false otherwise.
95 * @since 12
96*/
97bool OH_MediaAssetManager_CancelRequest(OH_MediaAssetManager* manager, const MediaLibrary_RequestId requestId);
98
99/**
100 * @brief Request moving photo object.
101 *
102 * @permission ohos.permission.READ_IMAGEVIDEO
103 * @param manager the pointer to {@link OH_MediaAssetManager} instance.
104 * @param mediaAsset the {@link OH_MediaAsset} instance of media file object to be requested.
105 * @param requestOptions the {@link MediaLibrary_RequestOptions} for image request strategy mode.
106 * @param requestId indicates the {@link MediaLibrary_RequestId} of the request, which is an output parameter.
107 * @param callback the {@link OH_MediaLibrary_OnMovingPhotoDataPrepared} that will be called
108 *                 when the requested source is prepared.
109 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
110 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
111 *                                                1. Mandatory parameters are left unspecified.
112 *                                                2. Incorrect parameter types.
113 *                                                3. Parameter verification failed.
114 *         {@link #MEDIA_LIBRARY_OPERATION_NOT_SUPPORTED} if operation is not supported.
115 *         {@link #MEDIA_LIBRARY_PERMISSION_DENIED} if permission is denied.
116 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
117 * @since 13
118*/
119MediaLibrary_ErrorCode OH_MediaAssetManager_RequestMovingPhoto(OH_MediaAssetManager* manager,
120    OH_MediaAsset* mediaAsset, MediaLibrary_RequestOptions requestOptions, MediaLibrary_RequestId* requestId,
121    OH_MediaLibrary_OnMovingPhotoDataPrepared callback);
122
123/**
124 * @brief Request image resources based on different strategy modes.
125 *
126 * @permission ohos.permission.READ_IMAGEVIDEO
127 * @param manager the pointer to {@link OH_MediaAssetManager} instance.
128 * @param mediaAsset the {@link OH_MediaAsset} instance of media file object to be requested.
129 * @param requestOptions the {@link MediaLibrary_RequestOptions} for image request strategy mode.
130 * @param requestId indicates the {@link MediaLibrary_RequestId} of the request, which is an output parameter.
131 * @param callback the {@link OH_MediaLibrary_OnImageDataPrepared} that will be called
132 *                 when the requested source is prepared.
133 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
134 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
135 *                                                1. Mandatory parameters are left unspecified.
136 *                                                2. Incorrect parameter types.
137 *                                                3. Parameter verification failed.
138 *         {@link #MEDIA_LIBRARY_OPERATION_NOT_SUPPORTED} if operation is not supported.
139 *         {@link #MEDIA_LIBRARY_PERMISSION_DENIED} if permission is denied.
140 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
141 * @since 12
142*/
143MediaLibrary_ErrorCode OH_MediaAssetManager_RequestImage(OH_MediaAssetManager* manager, OH_MediaAsset* mediaAsset,
144    MediaLibrary_RequestOptions requestOptions, MediaLibrary_RequestId* requestId,
145    OH_MediaLibrary_OnImageDataPrepared callback);
146
147/**
148 * @brief Release the {@link OH_MediaAssetManager} instance.
149 *
150 * @param manager the {@link OH_MediaAssetManager} instance.
151 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
152 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
153 *                                                1. Mandatory parameters are left unspecified.
154 *                                                2. Incorrect parameter types.
155 *                                                3. Parameter verification failed.
156 * @since 13
157*/
158MediaLibrary_ErrorCode OH_MediaAssetManager_Release(OH_MediaAssetManager* manager);
159
160#ifdef __cplusplus
161}
162#endif
163
164#endif // MULTIMEDIA_MEDIA_LIBRARY_NATIVE_MEDIA_ASSET_MANAGER_H
165/** @} */
166