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_capi.h
27 *
28 * @brief Defines APIs related to media asset.
29 *
30 * Provides the ability to obtain image or video information.
31 *
32 * @kit MediaLibraryKit
33 * @syscap SystemCapability.FileManagement.PhotoAccessHelper.Core
34 * @library libmedia_asset_manager.so
35 * @since 12
36 */
37
38#ifndef MULTIMEDIA_MEDIA_LIBRARY_NATIVE_MEDIA_ASSET_H
39#define MULTIMEDIA_MEDIA_LIBRARY_NATIVE_MEDIA_ASSET_H
40
41#include "media_asset_base_capi.h"
42
43#ifdef __cplusplus
44extern "C" {
45#endif
46
47/**
48 * @brief Get the uri of the media asset.
49 *
50 * @param mediaAsset the {@link OH_MediaAsset} instance.
51 * @param uri the uri of the media asset.
52 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
53 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
54 *                                                1. Mandatory parameters are left unspecified.
55 *                                                2. Incorrect parameter types.
56 *                                                3. Parameter verification failed.
57 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
58 * @since 12
59*/
60MediaLibrary_ErrorCode OH_MediaAsset_GetUri(OH_MediaAsset* mediaAsset, const char** uri);
61
62/**
63 * @brief Get the media file type of the media asset.
64 *
65 * @param mediaAsset the {@link OH_MediaAsset} instance.
66 * @param mediaType the media file type of the media asset.
67 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
68 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
69 *                                                1. Mandatory parameters are left unspecified.
70 *                                                2. Incorrect parameter types.
71 *                                                3. Parameter verification failed.
72 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
73 * @since 13
74*/
75MediaLibrary_ErrorCode OH_MediaAsset_GetMediaType(OH_MediaAsset* mediaAsset, MediaLibrary_MediaType* mediaType);
76
77/**
78 * @brief Get the subtype of the media asset.
79 *
80 * @param mediaAsset the {@link OH_MediaAsset} instance.
81 * @param mediaSubType the subtype of the media asset.
82 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
83 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
84 *                                                1. Mandatory parameters are left unspecified.
85 *                                                2. Incorrect parameter types.
86 *                                                3. Parameter verification failed.
87 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
88 * @since 13
89*/
90MediaLibrary_ErrorCode OH_MediaAsset_GetMediaSubType(OH_MediaAsset* mediaAsset,
91    MediaLibrary_MediaSubType* mediaSubType);
92
93/**
94 * @brief Get the display name of the media asset.
95 *
96 * @param mediaAsset the {@link OH_MediaAsset} instance.
97 * @param displayName the display name of the media asset.
98 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
99 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
100 *                                                1. Mandatory parameters are left unspecified.
101 *                                                2. Incorrect parameter types.
102 *                                                3. Parameter verification failed.
103 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
104 * @since 12
105*/
106MediaLibrary_ErrorCode OH_MediaAsset_GetDisplayName(OH_MediaAsset* mediaAsset, const char** displayName);
107
108/**
109 * @brief Get the file size of the media asset
110 *
111 * @param mediaAsset the {@link OH_MediaAsset} instance.
112 * @param size the file size(in bytes) of the media asset.
113 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
114 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
115 *                                                1. Mandatory parameters are left unspecified.
116 *                                                2. Incorrect parameter types.
117 *                                                3. Parameter verification failed.
118 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
119 * @since 12
120*/
121MediaLibrary_ErrorCode OH_MediaAsset_GetSize(OH_MediaAsset* mediaAsset, uint32_t* size);
122
123/**
124 * @brief Get the date of asset creation.
125 *
126 * @param mediaAsset the {@link OH_MediaAsset} instance.
127 * @param dateAdded the creation date of the asset.
128 *        The value is the number of seconds elapsed since the Epoch time (00:00:00 UTC on January 1, 1970).
129 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
130 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
131 *                                                1. Mandatory parameters are left unspecified.
132 *                                                2. Incorrect parameter types.
133 *                                                3. Parameter verification failed.
134 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
135 * @since 13
136*/
137MediaLibrary_ErrorCode OH_MediaAsset_GetDateAdded(OH_MediaAsset* mediaAsset, uint32_t* dateAdded);
138
139/**
140 * @brief Get the modified date of the asset.
141 *
142 * @param mediaAsset the {@link OH_MediaAsset} instance.
143 * @param dateModified the modified date of the asset.
144 *        The value is the number of seconds elapsed since the Epoch time.
145 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
146 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
147 *                                                1. Mandatory parameters are left unspecified.
148 *                                                2. Incorrect parameter types.
149 *                                                3. Parameter verification failed.
150 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
151 * @since 13
152*/
153MediaLibrary_ErrorCode OH_MediaAsset_GetDateModified(OH_MediaAsset* mediaAsset, uint32_t* dateModified);
154
155/**
156 * @brief Get the date taken of the asset.
157 *
158 * @param mediaAsset the {@link OH_MediaAsset} instance.
159 * @param dateTaken the date taken of the asset.
160 *        The value is the number of seconds elapsed since the Epoch time.
161 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
162 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
163 *                                                1. Mandatory parameters are left unspecified.
164 *                                                2. Incorrect parameter types.
165 *                                                3. Parameter verification failed.
166 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
167 * @since 13
168*/
169MediaLibrary_ErrorCode OH_MediaAsset_GetDateTaken(OH_MediaAsset* mediaAsset, uint32_t* dateTaken);
170
171/**
172 * @brief Get the creation time of the asset in milliseconds.
173 *
174 * @param mediaAsset the {@link OH_MediaAsset} instance.
175 * @param dateAddedMs the creation time of the asset in milliseconds.
176 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
177 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
178 *                                                1. Mandatory parameters are left unspecified.
179 *                                                2. Incorrect parameter types.
180 *                                                3. Parameter verification failed.
181 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
182 * @since 13
183*/
184MediaLibrary_ErrorCode OH_MediaAsset_GetDateAddedMs(OH_MediaAsset* mediaAsset, uint32_t* dateAddedMs);
185
186/**
187 * @brief Get the modified time of the asset in milliseconds.
188 *
189 * @param mediaAsset the {@link OH_MediaAsset} instance.
190 * @param dateModifiedMs the modified time of the asset in milliseconds.
191 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
192 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
193 *                                                1. Mandatory parameters are left unspecified.
194 *                                                2. Incorrect parameter types.
195 *                                                3. Parameter verification failed.
196 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
197 * @since 12
198*/
199MediaLibrary_ErrorCode OH_MediaAsset_GetDateModifiedMs(OH_MediaAsset* mediaAsset, uint32_t* dateModifiedMs);
200
201/**
202 * @brief Get the duration of the media asset in milliseconds.
203 *
204 * @param mediaAsset the {@link OH_MediaAsset} instance.
205 * @param duration the duration of the media asset in milliseconds.
206 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
207 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
208 *                                                1. Mandatory parameters are left unspecified.
209 *                                                2. Incorrect parameter types.
210 *                                                3. Parameter verification failed.
211 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
212 * @since 13
213*/
214MediaLibrary_ErrorCode OH_MediaAsset_GetDuration(OH_MediaAsset* mediaAsset, uint32_t* duration);
215
216/**
217 * @brief Get the image width(in pixels) of the media asset.
218 *
219 * @param mediaAsset the {@link OH_MediaAsset} instance.
220 * @param width the image width(in pixels) of the media asset.
221 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
222 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
223 *                                                1. Mandatory parameters are left unspecified.
224 *                                                2. Incorrect parameter types.
225 *                                                3. Parameter verification failed.
226 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
227 * @since 12
228*/
229MediaLibrary_ErrorCode OH_MediaAsset_GetWidth(OH_MediaAsset* mediaAsset, uint32_t* width);
230
231/**
232 * @brief Get the image height(in pixels) of the media asset.
233 *
234 * @param mediaAsset the {@link OH_MediaAsset} instance.
235 * @param height the image height(in pixels) of the media asset.
236 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
237 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
238 *                                                1. Mandatory parameters are left unspecified.
239 *                                                2. Incorrect parameter types.
240 *                                                3. Parameter verification failed.
241 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
242 * @since 12
243*/
244MediaLibrary_ErrorCode OH_MediaAsset_GetHeight(OH_MediaAsset* mediaAsset, uint32_t* height);
245
246/**
247 * @brief Get the orientation of the image.
248 *
249 * @param mediaAsset the {@link OH_MediaAsset} instance.
250 * @param orientation the orientation of the image.
251 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
252 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
253 *                                                1. Mandatory parameters are left unspecified.
254 *                                                2. Incorrect parameter types.
255 *                                                3. Parameter verification failed.
256 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
257 * @since 12
258*/
259MediaLibrary_ErrorCode OH_MediaAsset_GetOrientation(OH_MediaAsset* mediaAsset, uint32_t* orientation);
260
261/**
262 * @brief Get the favorite state of the asset.
263 *
264 * @param mediaAsset the {@link OH_MediaAsset} instance.
265 * @param favorite the favorite state of the media asset.
266 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
267 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
268 *                                                1. Mandatory parameters are left unspecified.
269 *                                                2. Incorrect parameter types.
270 *                                                3. Parameter verification failed.
271 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
272 * @since 13
273*/
274MediaLibrary_ErrorCode OH_MediaAsset_IsFavorite(OH_MediaAsset* mediaAsset, uint32_t* favorite);
275
276/**
277 * @brief Get the title of the media asset.
278 *
279 * @param mediaAsset the {@link OH_MediaAsset} instance.
280 * @param title the title of the media asset.
281 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
282 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
283 *                                                1. Mandatory parameters are left unspecified.
284 *                                                2. Incorrect parameter types.
285 *                                                3. Parameter verification failed.
286 *         {@link #MEDIA_LIBRARY_INTERNAL_SYSTEM_ERROR} if internal system error.
287 * @since 13
288*/
289MediaLibrary_ErrorCode OH_MediaAsset_GetTitle(OH_MediaAsset* mediaAsset, const char** title);
290
291/**
292 * @brief Release the media asset
293 *
294 * @param mediaAsset the {@link OH_MediaAsset} instance.
295 * @return {@link #MEDIA_LIBRARY_OK} if the method call succeeds.
296 *         {@link #MEDIA_LIBRARY_PARAMETER_ERROR} Parameter error. Possible causes:
297 *                                                1. Mandatory parameters are left unspecified.
298 *                                                2. Incorrect parameter types.
299 *                                                3. Parameter verification failed.
300 * @since 12
301*/
302MediaLibrary_ErrorCode OH_MediaAsset_Release(OH_MediaAsset* mediaAsset);
303
304#ifdef __cplusplus
305}
306#endif
307
308#endif // MULTIMEDIA_MEDIA_LIBRARY_NATIVE_MEDIA_ASSET_H
309/** @} */