include/media_audio.h

   1 /*
   2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3 *
   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
   7 *
   8 * http://www.apache.org/licenses/LICENSE-2.0
   9 *
  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.
  15 */
  16
  17
  18 #ifndef __TIZEN_AUDIO_META_H__
  19 #define __TIZEN_AUDIO_META_H__
  20
  21 #include <media_content_type.h>
  22
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * @file media_audio.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.
  33  */
  34
  35 /**
  36  * @addtogroup CAPI_CONTENT_MEDIA_AUDIO_META_MODULE
  37  * @{
  38  */
  39
  40
  41 /**
  42  * @brief Destroys the audio metadata.
  43  * @since_tizen 2.3
  44  *
  45  * @param[in] audio The audio metadata handle
  46  *
  47  * @return @c 0 on success,
  48  *         otherwise a negative error value
  49  *
  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
  53  *
  54  * @pre Get a copy of audio metadata handle handle by calling audio_meta_clone().
  55  *
  56  * @see audio_meta_clone()
  57  */
  58 int audio_meta_destroy(audio_meta_h audio);
  59
  60 /**
  61  * @brief Clones the audio metadata.
  62  * @details This function copies the audio metadata handle from source to destination.
  63  *
  64  * @since_tizen 2.3
  65  *
  66  * @remarks The destination handle must be released using audio_meta_destroy().
  67  *
  68  * @param[out] dst  The destination handle to audio metadata
  69  * @param[in]  src  The source handle to the audio metadata
  70  *
  71  * @return @c 0 on success,
  72  *         otherwise a negative error value
  73  *
  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
  78  *
  79  * @see audio_meta_destroy()
  80  */
  81 int audio_meta_clone(audio_meta_h *dst, audio_meta_h src);
  82
  83 /**
  84  * @brief Gets the audio ID of the given audio metadata.
  85  * @since_tizen 2.3
  86  *
  87  * @remarks You must release @a media_id using free().
  88  *
  89  * @param[in]  audio    The audio metadata handle
  90  * @param[out] media_id The ID of the audio
  91  *
  92  * @return @c 0 on success,
  93  *         otherwise a negative error value
  94  *
  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
  99  */
 100 int audio_meta_get_media_id(audio_meta_h audio, char **media_id);
 101
 102 /**
 103  * @brief Gets the album name of the given audio metadata.
 104  * @details If the value is an empty string, the method returns "Unknown".
 105  *
 106  * @since_tizen 2.3
 107  *
 108  * @remarks You must release @a album_name using free().
 109  *
 110  * @param[in]  audio      The audio metadata handle
 111  * @param[out] album_name The name of the album
 112  *
 113  * @return @c 0 on success,
 114  *         otherwise a negative error value
 115  *
 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
 120  */
 121 int audio_meta_get_album(audio_meta_h audio, char **album_name);
 122
 123 /**
 124  * @brief Gets the artist name of the given audio metadata.
 125  * @details If the value is an empty string, the method returns "Unknown".
 126  *
 127  * @since_tizen 2.3
 128  *
 129  * @remarks You must release @a artist_name using free().
 130  *
 131  * @param[in]  audio       The audio metadata handle
 132  * @param[out] artist_name The name of the artist
 133  *
 134  * @return @c 0 on success,
 135  *         otherwise a negative error value
 136  *
 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
 141  */
 142 int audio_meta_get_artist(audio_meta_h audio, char **artist_name);
 143
 144 /**
 145  * @brief Gets name of album_artist of given audio metadata.\n
 146  * If the value is an empty string, the method returns "Unknown".
 147  *
 148  * @remarks @a album_artist_name must be released with free() by you.
 149  *
 150  * @param [in] audio The handle to audio metadata
 151  * @param [out] album_artist_name The name of the album_artist
 152  * @return 0 on success, otherwise a negative error value.
 153  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 154  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 155  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 156  */
 157 int audio_meta_get_album_artist(audio_meta_h audio, char **album_artist_name);
 158
 159 /**
 160  * @brief Gets the genre name of the given audio metadata.
 161  * @details If the value is an empty string, the method returns "Unknown".
 162  *
 163  * @since_tizen 2.3
 164  *
 165  * @remarks You must release @a genre_name using free().
 166  *
 167  * @param[in]  audio      The audio metadata handle
 168  * @param[out] genre_name The name of the genre
 169  *
 170  * @return @c 0 on success,
 171  *         otherwise a negative error value
 172  *
 173  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 174  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 175  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 176  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 177  */
 178 int audio_meta_get_genre(audio_meta_h audio, char **genre_name);
 179
 180 /**
 181  * @brief Gets the composer name of the given audio metadata.
 182  * @details If the value is an empty string, the method returns "Unknown".
 183  *
 184  * @since_tizen 2.3
 185  *
 186  * @remarks You must release @a author_name using free().
 187  *
 188  * @param[in]  audio       The audio metadata handle
 189  * @param[out] composer_name The name of the author of the audio
 190  *
 191  * @return @c 0 on success,
 192  *         otherwise a negative error value
 193  *
 194  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 195  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 196  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 197  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 198  */
 199 int audio_meta_get_composer(audio_meta_h audio, char **composer_name);
 200
 201 /**
 202  * @brief Gets the year of the given audio metadata.
 203  * @details If the value is an empty string, the method returns "Unknown".
 204  *
 205  * @since_tizen 2.3
 206  *
 207  * @remarks You must release @a year using free().
 208  *
 209  * @param[in]  audio The audio metadata handle
 210  * @param[out] year  The year of the audio file
 211  *
 212  * @return @c 0 on success,
 213  *         otherwise a negative error value
 214  *
 215  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 216  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 217  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 218  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 219  */
 220 int audio_meta_get_year(audio_meta_h audio, char **year);
 221
 222 /**
 223  * @brief Gets the recorded date of the given audio metadata.
 224  * @since_tizen 2.3
 225  *
 226  * @remarks You must release @a recorded_date using free().
 227  *
 228  * @param[in]  audio         The audio metadata handle
 229  * @param[out] recorded_date The recorded date of the audio file
 230  *
 231  * @return @c 0 on success,
 232  *         otherwise a negative error value
 233  *
 234  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 235  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 236  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 237  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 238  */
 239 int audio_meta_get_recorded_date(audio_meta_h audio, char **recorded_date);
 240
 241 /**
 242  * @brief Gets the copyright notice of the given audio metadata.
 243  * @since_tizen 2.3
 244  *
 245  * @remarks You must release @a copyright using free().
 246  *
 247  * @param[in]  audio     The audio metadata handle
 248  * @param[out] copyright The audio copyright notice
 249  *
 250  * @return @c 0 on success,
 251  *         otherwise a negative error value
 252  *
 253  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 254  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 255  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 256  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 257  */
 258 int audio_meta_get_copyright(audio_meta_h audio, char **copyright);
 259
 260 /**
 261  * @brief Gets the track number of the given audio metadata.
 262  * @details If the value is an empty string, the method returns "Unknown".
 263  *
 264  * @since_tizen 2.3
 265  *
 266  * @param[in]  audio     The audio metadata handle
 267  * @param[out] track_num The audio track number
 268  *
 269  * @return @c 0 on success,
 270  *         otherwise a negative error value
 271  *
 272  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 273  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 274  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 275  */
 276 int audio_meta_get_track_num(audio_meta_h audio, char **track_num);
 277
 278 /**
 279  * @brief Gets the bitrate of the given audio metadata in bitrate per second.
 280  * @since_tizen 2.3
 281  *
 282  * @param[in]  audio    The audio metadata handle
 283  * @param[out] bit_rate The audio bitrate in bit per second [bps]
 284  *
 285  * @return @c 0 on success,
 286  *         otherwise a negative error value
 287  *
 288  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 289  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 290  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 291  */
 292 int audio_meta_get_bit_rate(audio_meta_h audio, int *bit_rate);
 293
 294 /**
 295  * @brief Gets bit per sample of the given audio metadata.
 296  * @since_tizen 2.3
 297  *
 298  * @param [in]  audio        The handle to the audio metadata
 299  * @param [out] bitpersample The audio bit per sample
 300  *
 301  * @return @c 0 on success,
 302  *         otherwise a negative error value
 303  *
 304  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 305  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 306  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 307  */
 308
 309 int audio_meta_get_bitpersample(audio_meta_h audio, int *bitpersample);
 310
 311 /**
 312  * @brief Gets the sample rate of the given audio metadata.
 313  * @since_tizen 2.3
 314  *
 315  * @param[in]  audio       The audio metadata handle
 316  * @param[out] sample_rate The audio sample rate[hz]
 317  *
 318  * @return @c 0 on success,
 319  *         otherwise a negative error value
 320  *
 321  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 322  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 323  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 324  */
 325 int audio_meta_get_sample_rate(audio_meta_h audio, int *sample_rate);
 326
 327 /**
 328  * @brief Gets the channel of the given audio metadata.
 329  * @since_tizen 2.3
 330  *
 331  * @param[in]  audio   The audio metadata handle
 332  * @param[out] channel The channel of the audio
 333  *
 334  * @return @c 0 on success,
 335  *         otherwise a negative error value
 336  *
 337  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 338  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 339  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 340  */
 341 int audio_meta_get_channel(audio_meta_h audio, int *channel);
 342
 343 /**
 344  * @brief Gets the track duration of the given audio metadata.
 345  * @since_tizen 2.3
 346  *
 347  * @param[in]  audio    The audio metadata handle
 348  * @param[out] duration The audio file duration
 349  *
 350  * @return @c 0 on success,
 351  *         otherwise a negative error value
 352  *
 353  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 354  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 355  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 356  */
 357 int audio_meta_get_duration(audio_meta_h audio, int *duration);
 358
 359 /**
 360  * @brief Gets the number of times the given audio has been played.
 361  * @since_tizen 2.3
 362  *
 363  * @param[in]  audio        The audio metadata handle
 364  * @param[out] played_count The counter of the audio played
 365  *
 366  * @return @c 0 on success,
 367  *         otherwise a negative error value
 368  *
 369  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 370  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 371  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 372  */
 373 int audio_meta_get_played_count(audio_meta_h audio, int *played_count);
 374
 375 /**
 376  * @brief Gets the played time parameter of an audio.
 377  * @details This function returns audio's elapsed playback time parameter as a period
 378  *          starting from the beginning of the track.
 379  *
 380  * @since_tizen 2.3
 381  *
 382  * @param[in]  audio       The audio metadata handle
 383  * @param[out] played_time The elapsed time of the audio
 384  *
 385  * @return @c 0 on success,
 386  *         otherwise a negative error value
 387  *
 388  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 389  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 390  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 391  */
 392 int audio_meta_get_played_time(audio_meta_h audio, time_t *played_time);
 393
 394 /**
 395  * @brief Gets the played position parameter of an audio.
 396  * @details This function returns audio's elapsed playback position parameter as a period
 397  *          starting from the beginning of the track.
 398  *
 399  * @since_tizen 2.3
 400  *
 401  * @param[in]  audio           The audio metadata handle
 402  * @param[out] played_position The elapsed time of the audio
 403  *
 404  * @return @c 0 on success,
 405  *         otherwise a negative error value
 406  *
 407  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 408  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 409  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 410  */
 411 int audio_meta_get_played_position(audio_meta_h audio, int *played_position);
 412
 413 /**
 414  * @brief Sets the played count to an audio meta handle.
 415  * @since_tizen 2.3
 416  *
 417  * @param[in] audio        The audio metadata handle
 418  * @param[in] played_count The played count of the audio
 419  *
 420  * @return @c 0 on success,
 421  *         otherwise a negative error value
 422  *
 423  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 424  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 425  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 426  *
 427  * @post audio_meta_update_to_db().
 428  */
 429 int audio_meta_set_played_count(audio_meta_h audio, int played_count);
 430
 431 /**
 432  * @brief Sets the played time to an audio meta handle.
 433  * @since_tizen 2.3
 434  *
 435  * @param[in] audio       The audio metadata handle
 436  * @param[in] played_time The played time of the audio
 437  *
 438  * @return @c 0 on success,
 439  *         otherwise a negative error value
 440  *
 441  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 442  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 443  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 444  *
 445  * @post audio_meta_update_to_db().
 446  */
 447 int audio_meta_set_played_time(audio_meta_h audio, time_t played_time);
 448
 449 /**
 450  * @brief Sets the played position to an audio meta handle.
 451  * @since_tizen 2.3
 452  *
 453  * @param[in] audio           The audio metadata handle
 454  * @param[in] played_position The played position of the audio
 455  *
 456  * @return @c 0 on success,
 457  *         otherwise a negative error value
 458  *
 459  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 460  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 461  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 462  *
 463  * @post audio_meta_update_to_db().
 464  */
 465 int audio_meta_set_played_position(audio_meta_h audio, int played_position);
 466
 467 /**
 468  * @brief Updates an audio metadata with modified attributes in the media database.
 469  * @details The function updates the given audio meta in the media database.
 470  *
 471  * @since_tizen 2.3
 472  * @privlevel public
 473  * @privilege %http://tizen.org/privilege/content.write
 474  *
 475  * @remarks The function should be called after any change in the attributes, to update the media database.
 476  *          For example, after using audio_meta_set_played_count() for changing the count of the played, the
 477  *          audio_meta_update_to_db() function should be called to update the given attributes in the media database. \n
 478  *          Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
 479  *
 480  * @param[in] audio The audio metadata handle
 481  *
 482  * @return @c 0 on success,
 483  *         otherwise a negative error value
 484  *
 485  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 486  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 487  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 488  *
 489  * @pre This function requires opened connection to content service by media_content_connect().
 490  *
 491  * @see media_content_connect()
 492  * @see audio_meta_set_played_count()
 493  * @see audio_meta_set_played_time()
 494  * @see audio_meta_set_played_position()
 495  */
 496 int audio_meta_update_to_db(audio_meta_h audio);
 497
 498 /**
 499  * @}
 500  */
 501
 502
 503 #ifdef __cplusplus
 504 }
 505 #endif
 506
 507 #endif /*__TIZEN_AUDIO_META_H__*/