2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
18 #ifndef __TIZEN_AUDIO_META_H__
19 #define __TIZEN_AUDIO_META_H__
21 #include <media_content_type.h>
30 * @brief This file contains the audio metadata API and related structure and enumeration. \n
31 * Description of the audio content involves: album, artist, album_artist, author, genre and description tags. \n
32 * Parameters of the recording are also supported such as format, bitrate, duration, size etc.
36 * @addtogroup CAPI_CONTENT_MEDIA_AUDIO_META_MODULE
42 * @brief Destroys the audio metadata.
45 * @param[in] audio The audio metadata handle
47 * @return @c 0 on success,
48 * otherwise a negative error value
50 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
51 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
52 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
54 * @pre Get a copy of audio metadata handle handle by calling audio_meta_clone().
56 * @see audio_meta_clone()
58 int audio_meta_destroy(audio_meta_h audio);
61 * @brief Clones the audio metadata.
62 * @details This function copies the audio metadata handle from source to destination.
66 * @remarks The destination handle must be released using audio_meta_destroy().
68 * @param[out] dst The destination handle to audio metadata
69 * @param[in] src The source handle to the audio metadata
71 * @return @c 0 on success,
72 * otherwise a negative error value
74 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
75 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
76 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
77 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
79 * @see audio_meta_destroy()
81 int audio_meta_clone(audio_meta_h *dst, audio_meta_h src);
84 * @brief Gets the audio ID of the given audio metadata.
87 * @remarks You must release @a media_id using free().
89 * @param[in] audio The audio metadata handle
90 * @param[out] media_id The ID of the audio
92 * @return @c 0 on success,
93 * otherwise a negative error value
95 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
96 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
97 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
98 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
100 int audio_meta_get_media_id(audio_meta_h audio, char **media_id);
103 * @brief Gets the album name of the given audio metadata.
104 * @details If the value is an empty string, the method returns "Unknown".
108 * @remarks You must release @a album_name using free().
110 * @param[in] audio The audio metadata handle
111 * @param[out] album_name The name of the album
113 * @return @c 0 on success,
114 * otherwise a negative error value
116 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
117 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
118 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
119 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
121 int audio_meta_get_album(audio_meta_h audio, char **album_name);
124 * @brief Gets the artist name of the given audio metadata.
125 * @details If the value is an empty string, the method returns "Unknown".
129 * @remarks You must release @a artist_name using free().
131 * @param[in] audio The audio metadata handle
132 * @param[out] artist_name The name of the artist
134 * @return @c 0 on success,
135 * otherwise a negative error value
137 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
138 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
139 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
140 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
142 int audio_meta_get_artist(audio_meta_h audio, char **artist_name);
145 * @brief Gets the album artist name of the given audio metadata.
146 * @details If the value is an empty string, the method returns "Unknown".
150 * @remarks You must release @a album_artist_name using free().
152 * @param[in] audio The audio metadata handle
153 * @param[out] album_artist_name The name of the album artist
155 * @return @c 0 on success,
156 * otherwise a negative error value
158 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
159 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
160 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
161 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
163 int audio_meta_get_album_artist(audio_meta_h audio, char **album_artist_name);
166 * @brief Gets the genre name of the given audio metadata.
167 * @details If the value is an empty string, the method returns "Unknown".
171 * @remarks You must release @a genre_name using free().
173 * @param[in] audio The audio metadata handle
174 * @param[out] genre_name The name of the genre
176 * @return @c 0 on success,
177 * otherwise a negative error value
179 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
180 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
181 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
182 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
184 int audio_meta_get_genre(audio_meta_h audio, char **genre_name);
187 * @brief Gets the composer name of the given audio metadata.
188 * @details If the value is an empty string, the method returns "Unknown".
192 * @remarks You must release @a author_name using free().
194 * @param[in] audio The audio metadata handle
195 * @param[out] composer_name The name of the author of the audio
197 * @return @c 0 on success,
198 * otherwise a negative error value
200 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
201 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
202 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
203 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
205 int audio_meta_get_composer(audio_meta_h audio, char **composer_name);
208 * @brief Gets the year of the given audio metadata.
209 * @details If the value is an empty string, the method returns "Unknown".
213 * @remarks You must release @a year using free().
215 * @param[in] audio The audio metadata handle
216 * @param[out] year The year of the audio file
218 * @return @c 0 on success,
219 * otherwise a negative error value
221 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
222 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
223 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
224 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
226 int audio_meta_get_year(audio_meta_h audio, char **year);
229 * @brief Gets the recorded date of the given audio metadata.
232 * @remarks You must release @a recorded_date using free().
234 * @param[in] audio The audio metadata handle
235 * @param[out] recorded_date The recorded date of the audio file
237 * @return @c 0 on success,
238 * otherwise a negative error value
240 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
241 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
242 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
243 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
245 int audio_meta_get_recorded_date(audio_meta_h audio, char **recorded_date);
248 * @brief Gets the copyright notice of the given audio metadata.
251 * @remarks You must release @a copyright using free().
253 * @param[in] audio The audio metadata handle
254 * @param[out] copyright The audio copyright notice
256 * @return @c 0 on success,
257 * otherwise a negative error value
259 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
260 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
261 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
262 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
264 int audio_meta_get_copyright(audio_meta_h audio, char **copyright);
267 * @brief Gets the track number of the given audio metadata.
268 * @details If the value is an empty string, the method returns "Unknown".
272 * @param[in] audio The audio metadata handle
273 * @param[out] track_num The audio track number
275 * @return @c 0 on success,
276 * otherwise a negative error value
278 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
279 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
280 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
282 int audio_meta_get_track_num(audio_meta_h audio, char **track_num);
285 * @brief Gets the bitrate of the given audio metadata in bitrate per second.
288 * @param[in] audio The audio metadata handle
289 * @param[out] bit_rate The audio bitrate in bit per second [bps]
291 * @return @c 0 on success,
292 * otherwise a negative error value
294 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
295 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
296 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
298 int audio_meta_get_bit_rate(audio_meta_h audio, int *bit_rate);
301 * @brief Gets bit per sample of the given audio metadata.
304 * @param [in] audio The handle to the audio metadata
305 * @param [out] bitpersample The audio bit per sample
307 * @return @c 0 on success,
308 * otherwise a negative error value
310 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
311 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
312 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
315 int audio_meta_get_bitpersample(audio_meta_h audio, int *bitpersample);
318 * @brief Gets the sample rate of the given audio metadata.
321 * @param[in] audio The audio metadata handle
322 * @param[out] sample_rate The audio sample rate[hz]
324 * @return @c 0 on success,
325 * otherwise a negative error value
327 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
328 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
329 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
331 int audio_meta_get_sample_rate(audio_meta_h audio, int *sample_rate);
334 * @brief Gets the channel of the given audio metadata.
337 * @param[in] audio The audio metadata handle
338 * @param[out] channel The channel of the audio
340 * @return @c 0 on success,
341 * otherwise a negative error value
343 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
344 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
345 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
347 int audio_meta_get_channel(audio_meta_h audio, int *channel);
350 * @brief Gets the track duration of the given audio metadata.
353 * @param[in] audio The audio metadata handle
354 * @param[out] duration The audio file duration
356 * @return @c 0 on success,
357 * otherwise a negative error value
359 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
360 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
361 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
363 int audio_meta_get_duration(audio_meta_h audio, int *duration);
366 * @brief Gets the number of times the given audio has been played.
369 * @param[in] audio The audio metadata handle
370 * @param[out] played_count The counter of the audio played
372 * @return @c 0 on success,
373 * otherwise a negative error value
375 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
376 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
377 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
379 int audio_meta_get_played_count(audio_meta_h audio, int *played_count);
382 * @brief Gets the played time parameter of an audio.
383 * @details This function returns audio's elapsed playback time parameter as a period
384 * starting from the beginning of the track.
388 * @param[in] audio The audio metadata handle
389 * @param[out] played_time The elapsed time of the audio
391 * @return @c 0 on success,
392 * otherwise a negative error value
394 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
395 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
396 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
398 int audio_meta_get_played_time(audio_meta_h audio, time_t *played_time);
401 * @brief Gets the played position parameter of an audio.
402 * @details This function returns audio's elapsed playback position parameter as a period
403 * starting from the beginning of the track.
407 * @param[in] audio The audio metadata handle
408 * @param[out] played_position The elapsed time of the audio
410 * @return @c 0 on success,
411 * otherwise a negative error value
413 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
414 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
415 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
417 int audio_meta_get_played_position(audio_meta_h audio, int *played_position);
420 * @brief Sets the played count to an audio meta handle.
423 * @param[in] audio The audio metadata handle
424 * @param[in] played_count The played count of the audio
426 * @return @c 0 on success,
427 * otherwise a negative error value
429 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
430 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
431 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
433 * @post audio_meta_update_to_db().
435 int audio_meta_set_played_count(audio_meta_h audio, int played_count);
438 * @brief Sets the played time to an audio meta handle.
441 * @param[in] audio The audio metadata handle
442 * @param[in] played_time The played time of the audio
444 * @return @c 0 on success,
445 * otherwise a negative error value
447 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
448 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
449 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
451 * @post audio_meta_update_to_db().
453 int audio_meta_set_played_time(audio_meta_h audio, time_t played_time);
456 * @brief Sets the played position to an audio meta handle.
459 * @param[in] audio The audio metadata handle
460 * @param[in] played_position The played position of the audio
462 * @return @c 0 on success,
463 * otherwise a negative error value
465 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
466 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
467 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
469 * @post audio_meta_update_to_db().
471 int audio_meta_set_played_position(audio_meta_h audio, int played_position);
474 * @brief Updates an audio metadata with modified attributes in the media database.
475 * @details The function updates the given audio meta in the media database.
479 * @privilege %http://tizen.org/privilege/content.write
481 * @remarks The function should be called after any change in the attributes, to update the media database.
482 * For example, after using audio_meta_set_played_count() for changing the count of the played, the
483 * audio_meta_update_to_db() function should be called to update the given attributes in the media database. \n
484 * Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
486 * @param[in] audio The audio metadata handle
488 * @return @c 0 on success,
489 * otherwise a negative error value
491 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
492 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
493 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
494 * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
495 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
496 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
497 * @retval #MEDIA_CONTENT_ERROR_NETWORK Network fail
498 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
500 * @pre This function requires opened connection to content service by media_content_connect().
502 * @see media_content_connect()
503 * @see audio_meta_set_played_count()
504 * @see audio_meta_set_played_time()
505 * @see audio_meta_set_played_position()
507 int audio_meta_update_to_db(audio_meta_h audio);
518 #endif /*__TIZEN_AUDIO_META_H__*/