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
46 extern "C" {
47 #endif
48 
49 /**
50  * @brief AVMetadata error code
51  *
52  * @since 13
53  * @version 1.0
54  */
55 typedef 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  */
78 typedef 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  */
101 typedef 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  */
115 typedef 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  */
124 typedef 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  */
136 AVMetadata_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  */
147 AVMetadata_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  */
161 AVMetadata_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  */
175 AVMetadata_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  */
189 AVMetadata_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  */
203 AVMetadata_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  */
217 AVMetadata_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  */
231 AVMetadata_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  */
245 AVMetadata_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  */
257 AVMetadata_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  */
271 AVMetadata_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  */
285 AVMetadata_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  */
299 AVMetadata_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  */
313 AVMetadata_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  */
327 AVMetadata_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  */
340 AVMetadata_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  */
355 AVMetadata_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  */
367 AVMetadata_Result OH_AVMetadata_Destroy(OH_AVMetadata* avMetadata);
368 
369 #ifdef __cplusplus
370 }
371 #endif
372 
373 #endif // NATIVE_AVMETADATA_H
374 /** @} */