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 OHAVSession
18 * @{
19 *
20 * @brief Provide the definition of the C interface for the avsession module.
21 *
22 * @syscap SystemCapability.Multimedia.AVSession.Core
23 *
24 * @since 13
25 * @version 1.0
26 */
27
28/**
29 * @file native_avmetadata.h
30 *
31 * @brief Declare avmetadata builder related interfaces.
32 *
33 * @library libohavsession.so
34 * @syscap SystemCapability.Multimedia.AVSession.Core
35 * @kit AVSessionKit
36 * @since 13
37 * @version 1.0
38 */
39
40#ifndef NATIVE_AVMETADATA_H
41#define NATIVE_AVMETADATA_H
42
43#include <stdint.h>
44
45#ifdef __cplusplus
46extern "C" {
47#endif
48
49/**
50 * @brief AVMetadata error code
51 *
52 * @since 13
53 * @version 1.0
54 */
55typedef enum {
56    /**
57     * @error The call was successful.
58     */
59    AVMETADATA_SUCCESS = 0,
60
61    /**
62     * @error This means that the function was executed with an invalid input parameter.
63     */
64    AVMETADATA_ERROR_INVALID_PARAM = 1,
65
66    /**
67     * @error This means there is no memory left.
68     */
69    AVMETADATA_ERROR_NO_MEMORY = 2,
70} AVMetadata_Result;
71
72/**
73 * @brief Defines the skip interval when fastforward or rewind.
74 *
75 * @since 13
76 * @version 1.0
77 */
78typedef enum {
79    /**
80     * @brief 10 seconds
81     */
82    SECONDS_10 = 10,
83
84    /**
85     * @brief 15 seconds
86     */
87    SECONDS_15 = 15,
88
89    /**
90     * @brief 30 seconds
91     */
92    SECONDS_30 = 30,
93} AVMetadata_SkipIntervals;
94
95/**
96 * @brief Display tag
97 *
98 * @since 13
99 * @version 1.0
100 */
101typedef enum {
102    /**
103     * @brief Indicate the audio vivid property.
104     */
105    AVSESSION_DISPLAYTAG_AUDIO_VIVID = 1,
106} AVMetadata_DisplayTag;
107
108/**
109 * @brief Declaring the avmetadata builder.
110 * The instance of builder is used for creating avmetadata.
111 *
112 * @since 13
113 * @version 1.0
114 */
115typedef struct OH_AVMetadataBuilderStruct OH_AVMetadataBuilder;
116
117/**
118 * @brief Declaring the avmetadata.
119 * The instance of avmetadata set by application for current resource.
120 *
121 * @since 13
122 * @version 1.0
123 */
124typedef struct OH_AVMetadataStruct OH_AVMetadata;
125
126/**
127 * @brief Creates an AVMetadataBuilder instance.
128 *
129 * @param builder The builder reference to the created result.
130 * @return Function result code:
131 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
132 *         {@link AVMETADATA_ERROR_INVALID_PARAM} The param of builder is nullptr.
133 *         {@link AVMETADATA_ERROR_NO_MEMORY} No memory to allocate a new instance.
134 * @since 13
135 */
136AVMetadata_Result OH_AVMetadataBuilder_Create(OH_AVMetadataBuilder** builder);
137
138/**
139 * @brief Destroy a bulder.
140 *
141 * @param builder The metadata builder instance pointer
142 * @return Function result code:
143 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
144 *         {@link AVMETADATA_ERROR_INVALID_PARAM} The param of builder is nullptr.
145 * @since 13
146 */
147AVMetadata_Result OH_AVMetadataBuilder_Destroy(OH_AVMetadataBuilder* builder);
148
149/**
150 * @brief Set current asset id of the resource
151 *
152 * @param builder The metadata builder instance pointer
153 * @param assetId The current assetId of resource.
154 * @return Function result code:
155 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
156 *         {@link AVMETADATA_ERROR_INVALID_PARAM}:
157 *                                                 1.The param of builder is nullptr;
158 *                                                 2.The param of assetId is nullptr.
159 * @since 13
160 */
161AVMetadata_Result OH_AVMetadataBuilder_SetAssetId(OH_AVMetadataBuilder* builder, const char* assetId);
162
163/**
164 * @brief Set the title of the resource
165 *
166 * @param builder The metadata builder instance pointer
167 * @param title The title of resource.
168 * @return Function result code:
169 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
170 *         {@link AVMETADATA_ERROR_INVALID_PARAM}:
171 *                                                 1.The param of builder is nullptr;
172 *                                                 2.The param of title is nullptr.
173 * @since 13
174 */
175AVMetadata_Result OH_AVMetadataBuilder_SetTitle(OH_AVMetadataBuilder* builder, const char* title);
176
177/**
178 * @brief Set the artist of the resource
179 *
180 * @param builder The metadata builder instance pointer
181 * @param artist The artist of resource.
182 * @return Function result code:
183 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
184 *         {@link AVMETADATA_ERROR_INVALID_PARAM}:
185 *                                                 1.The param of builder is nullptr;
186 *                                                 2.The param of artist is nullptr.
187 * @since 13
188 */
189AVMetadata_Result OH_AVMetadataBuilder_SetArtist(OH_AVMetadataBuilder* builder, const char* artist);
190
191/**
192 * @brief Set the author of the resource
193 *
194 * @param builder The metadata builder instance pointer
195 * @param author The author of resource.
196 * @return Function result code:
197 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
198 *         {@link AVMETADATA_ERROR_INVALID_PARAM}:
199 *                                                 1.The param of builder is nullptr;
200 *                                                 2.The param of author is nullptr.
201 * @since 13
202 */
203AVMetadata_Result OH_AVMetadataBuilder_SetAuthor(OH_AVMetadataBuilder* builder, const char* author);
204
205/**
206 * @brief Set the album information
207 *
208 * @param builder The metadata builder instance pointer
209 * @param album The album name
210 * @return Return code:
211 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
212 *         {@link AVMETADATA_ERROR_INVALID_PARAM}:
213 *                                                 1. The param of builder is nullptr.
214 *                                                 2. The param of album is nullptr.
215 * @since 13
216 */
217AVMetadata_Result OH_AVMetadataBuilder_SetAlbum(OH_AVMetadataBuilder* builder, const char* album);
218
219/**
220 * @brief Set the writer of the resource
221 *
222 * @param builder The metadata builder instance pointer
223 * @param writer The writer of resource.
224 * @return Function result code:
225 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
226 *         {@link AVMETADATA_ERROR_INVALID_PARAM}:
227 *                                                 1. The param of builder is nullptr.
228 *                                                 2. The param of writer is nullptr.
229 * @since 13
230 */
231AVMetadata_Result OH_AVMetadataBuilder_SetWriter(OH_AVMetadataBuilder* builder, const char* writer);
232
233/**
234 * @brief Set the composer of the resource
235 *
236 * @param builder The metadata builder instance pointer
237 * @param composer The composer of resource.
238 * @return Function result code:
239 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
240 *         {@link AVMETADATA_ERROR_INVALID_PARAM}:
241 *                                                 1. The param of builder is nullptr.
242 *                                                 2. The param of composer is nullptr.
243 * @since 13
244 */
245AVMetadata_Result OH_AVMetadataBuilder_SetComposer(OH_AVMetadataBuilder* builder, const char* composer);
246
247/**
248 * @brief Set the duration of the resource
249 *
250 * @param builder The metadata builder instance pointer
251 * @param duration The duration of resource, in miliseconds
252 * @return Function result code:
253 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
254 *         {@link AVMETADATA_ERROR_INVALID_PARAM} The param of builder is nullptr.
255 * @since 13
256 */
257AVMetadata_Result OH_AVMetadataBuilder_SetDuration(OH_AVMetadataBuilder* builder, int64_t duration);
258
259/**
260 * @brief Set the media image uri of the resource
261 *
262 * @param builder The metadata builder instance pointer
263 * @param mediaImageUri The mediaImageUri of resource.
264 * @return Function result code:
265 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
266 *         {@link AVMETADATA_ERROR_INVALID_PARAM}:
267 *                                                 1.The param of builder is nullptr;
268 *                                                 2.The param of mediaImageUri nullptr.
269 * @since 13
270 */
271AVMetadata_Result OH_AVMetadataBuilder_SetMediaImageUri(OH_AVMetadataBuilder* builder, const char* mediaImageUri);
272
273/**
274 * @brief Set the subtitle of the resource
275 *
276 * @param builder The metadata builder instance pointer
277 * @param subtitle The subtitle of resource.
278 * @return Function result code:
279 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
280 *         {@link AVMETADATA_ERROR_INVALID_PARAM}:
281 *                                                 1.The param of builder is nullptr;
282 *                                                 2.The param of subtitle nullptr.
283 * @since 13
284 */
285AVMetadata_Result OH_AVMetadataBuilder_SetSubtitle(OH_AVMetadataBuilder* builder, const char* subtitle);
286
287/**
288 * @brief Set the media description of the resource
289 *
290 * @param builder The metadata builder instance pointer
291 * @param description The description of resource.
292 * @return Function result code:
293 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
294 *         {@link AVMETADATA_ERROR_INVALID_PARAM}:
295 *                                                 1.The param of builder is nullptr;
296 *                                                 2.The param of description nullptr.
297 * @since 13
298 */
299AVMetadata_Result OH_AVMetadataBuilder_SetDescription(OH_AVMetadataBuilder* builder, const char* description);
300
301/**
302 * @brief Set the media lyric content of the resource
303 *
304 * @param builder The metadata builder instance pointer
305 * @param lyric The lyric of resource.
306 * @return Function result code:
307 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
308 *         {@link AVMETADATA_ERROR_INVALID_PARAM}:
309 *                                                 1.The param of builder is nullptr;
310 *                                                 2.The param of lyric nullptr.
311 * @since 13
312 */
313AVMetadata_Result OH_AVMetadataBuilder_SetLyric(OH_AVMetadataBuilder* builder, const char* lyric);
314
315/**
316 * @brief Set the skip intervals of the resource
317 *
318 * @param builder The metadata builder instance pointer
319 * @param intervals The intervals of resource, only can be set : 10, 15, 30
320 * @return Function result code:
321 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
322 *         {@link AVMETADATA_ERROR_INVALID_PARAM}:
323 *                                                 1.The param of builder is nullptr;
324 *                                                 2.The param of intervals is invalid.
325 * @since 13
326 */
327AVMetadata_Result OH_AVMetadataBuilder_SetSkipIntervals(OH_AVMetadataBuilder* builder,
328    AVMetadata_SkipIntervals intervals);
329
330/**
331 * @brief Set the display tags of the resource
332 *
333 * @param builder The metadata builder instance pointer
334 * @param tags The display tags of resource which are supported by this app to be displayed on the media center
335 * @return Function result code:
336 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
337 *         {@link AVMETADATA_ERROR_INVALID_PARAM} The param of builder is nullptr.
338 * @since 13
339 */
340AVMetadata_Result OH_AVMetadataBuilder_SetDisplayTags(OH_AVMetadataBuilder* builder, int32_t tags);
341
342/**
343 * @brief Create the avmetadta.
344 *
345 * @param builder The metadata builder instance pointer
346 * @param avMetadata Pointer to a viriable to receive the avMetadata object.
347 * @return Function result code:
348 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
349 *         {@link AVMETADATA_ERROR_NO_MEMORY} No memory to allocate a new instance.
350 *         {@link AVMETADATA_ERROR_INVALID_PARAM}:
351 *                                                 1.The param of builder is nullptr;
352 *                                                 2.The param of avMetadata is nullptr.
353 * @since 13
354 */
355AVMetadata_Result OH_AVMetadataBuilder_GenerateAVMetadata(OH_AVMetadataBuilder* builder,
356    OH_AVMetadata** avMetadata);
357
358/**
359 * @brief Request to release the avmetadta.
360 *
361 * @param avMetadata Pointer to a viriable to receive the avMetadata object.
362 * @return Function result code:
363 *         {@link AVMETADATA_SUCCESS} If the execution is successful.
364 *         {@link AVMETADATA_ERROR_INVALID_PARAM} The param of avMetadata is nullptr.
365 * @since 13
366 */
367AVMetadata_Result OH_AVMetadata_Destroy(OH_AVMetadata* avMetadata);
368
369#ifdef __cplusplus
370}
371#endif
372
373#endif // NATIVE_AVMETADATA_H
374/** @} */