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 the album artist name of the given audio metadata.
 146  * @details If the value is an empty string, the method returns "Unknown".
 147  *
 148  * @since_tizen 2.3
 149  *
 150  * @remarks You must release @a album_artist_name using free().
 151  *
 152  * @param[in]  audio             The audio metadata handle
 153  * @param[out] album_artist_name The name of the album artist
 154  *
 155  * @return @c 0 on success,
 156  *         otherwise a negative error value
 157  *
 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
 162  */
 163 int audio_meta_get_album_artist(audio_meta_h audio, char **album_artist_name);
 164
 165 /**
 166  * @brief Gets the genre name of the given audio metadata.
 167  * @details If the value is an empty string, the method returns "Unknown".
 168  *
 169  * @since_tizen 2.3
 170  *
 171  * @remarks You must release @a genre_name using free().
 172  *
 173  * @param[in]  audio      The audio metadata handle
 174  * @param[out] genre_name The name of the genre
 175  *
 176  * @return @c 0 on success,
 177  *         otherwise a negative error value
 178  *
 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
 183  */
 184 int audio_meta_get_genre(audio_meta_h audio, char **genre_name);
 185
 186 /**
 187  * @brief Gets the composer name of the given audio metadata.
 188  * @details If the value is an empty string, the method returns "Unknown".
 189  *
 190  * @since_tizen 2.3
 191  *
 192  * @remarks You must release @a author_name using free().
 193  *
 194  * @param[in]  audio       The audio metadata handle
 195  * @param[out] composer_name The name of the author of the audio
 196  *
 197  * @return @c 0 on success,
 198  *         otherwise a negative error value
 199  *
 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
 204  */
 205 int audio_meta_get_composer(audio_meta_h audio, char **composer_name);
 206
 207 /**
 208  * @brief Gets the year of the given audio metadata.
 209  * @details If the value is an empty string, the method returns "Unknown".
 210  *
 211  * @since_tizen 2.3
 212  *
 213  * @remarks You must release @a year using free().
 214  *
 215  * @param[in]  audio The audio metadata handle
 216  * @param[out] year  The year of the audio file
 217  *
 218  * @return @c 0 on success,
 219  *         otherwise a negative error value
 220  *
 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
 225  */
 226 int audio_meta_get_year(audio_meta_h audio, char **year);
 227
 228 /**
 229  * @brief Gets the recorded date of the given audio metadata.
 230  * @since_tizen 2.3
 231  *
 232  * @remarks You must release @a recorded_date using free().
 233  *
 234  * @param[in]  audio         The audio metadata handle
 235  * @param[out] recorded_date The recorded date of the audio file
 236  *
 237  * @return @c 0 on success,
 238  *         otherwise a negative error value
 239  *
 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
 244  */
 245 int audio_meta_get_recorded_date(audio_meta_h audio, char **recorded_date);
 246
 247 /**
 248  * @brief Gets the copyright notice of the given audio metadata.
 249  * @since_tizen 2.3
 250  *
 251  * @remarks You must release @a copyright using free().
 252  *
 253  * @param[in]  audio     The audio metadata handle
 254  * @param[out] copyright The audio copyright notice
 255  *
 256  * @return @c 0 on success,
 257  *         otherwise a negative error value
 258  *
 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
 263  */
 264 int audio_meta_get_copyright(audio_meta_h audio, char **copyright);
 265
 266 /**
 267  * @brief Gets the track number of the given audio metadata.
 268  * @details If the value is an empty string, the method returns "Unknown".
 269  *
 270  * @since_tizen 2.3
 271  *
 272  * @param[in]  audio     The audio metadata handle
 273  * @param[out] track_num The audio track number
 274  *
 275  * @return @c 0 on success,
 276  *         otherwise a negative error value
 277  *
 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
 281  */
 282 int audio_meta_get_track_num(audio_meta_h audio, char **track_num);
 283
 284 /**
 285  * @brief Gets the bitrate of the given audio metadata in bitrate per second.
 286  * @since_tizen 2.3
 287  *
 288  * @param[in]  audio    The audio metadata handle
 289  * @param[out] bit_rate The audio bitrate in bit per second [bps]
 290  *
 291  * @return @c 0 on success,
 292  *         otherwise a negative error value
 293  *
 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
 297  */
 298 int audio_meta_get_bit_rate(audio_meta_h audio, int *bit_rate);
 299
 300 /**
 301  * @brief Gets bit per sample of the given audio metadata.
 302  * @since_tizen 2.3
 303  *
 304  * @param [in]  audio        The handle to the audio metadata
 305  * @param [out] bitpersample The audio bit per sample
 306  *
 307  * @return @c 0 on success,
 308  *         otherwise a negative error value
 309  *
 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
 313  */
 314
 315 int audio_meta_get_bitpersample(audio_meta_h audio, int *bitpersample);
 316
 317 /**
 318  * @brief Gets the sample rate of the given audio metadata.
 319  * @since_tizen 2.3
 320  *
 321  * @param[in]  audio       The audio metadata handle
 322  * @param[out] sample_rate The audio sample rate[hz]
 323  *
 324  * @return @c 0 on success,
 325  *         otherwise a negative error value
 326  *
 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
 330  */
 331 int audio_meta_get_sample_rate(audio_meta_h audio, int *sample_rate);
 332
 333 /**
 334  * @brief Gets the channel of the given audio metadata.
 335  * @since_tizen 2.3
 336  *
 337  * @param[in]  audio   The audio metadata handle
 338  * @param[out] channel The channel of the audio
 339  *
 340  * @return @c 0 on success,
 341  *         otherwise a negative error value
 342  *
 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
 346  */
 347 int audio_meta_get_channel(audio_meta_h audio, int *channel);
 348
 349 /**
 350  * @brief Gets the track duration of the given audio metadata.
 351  * @since_tizen 2.3
 352  *
 353  * @param[in]  audio    The audio metadata handle
 354  * @param[out] duration The audio file duration
 355  *
 356  * @return @c 0 on success,
 357  *         otherwise a negative error value
 358  *
 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
 362  */
 363 int audio_meta_get_duration(audio_meta_h audio, int *duration);
 364
 365 /**
 366  * @deprecated Deprecated since 2.4. [Use media_info_get_played_count() instead]
 367  * @brief Gets the number of times the given audio has been played.
 368  * @since_tizen 2.3
 369  *
 370  * @param[in]  audio        The audio metadata handle
 371  * @param[out] played_count The counter of the audio played
 372  *
 373  * @return @c 0 on success,
 374  *         otherwise a negative error value
 375  *
 376  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 377  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 378  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 379  */
 380 int audio_meta_get_played_count(audio_meta_h audio, int *played_count);
 381
 382 /**
 383  * @deprecated Deprecated since 2.4. [Use media_info_get_played_time() instead]
 384  * @brief Gets the played time parameter of an audio.
 385  * @details This function returns audio's elapsed playback time parameter as a period
 386  *          starting from the beginning of the track.
 387  *
 388  * @since_tizen 2.3
 389  *
 390  * @param[in]  audio       The audio metadata handle
 391  * @param[out] played_time The elapsed time of the audio
 392  *
 393  * @return @c 0 on success,
 394  *         otherwise a negative error value
 395  *
 396  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 397  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 398  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 399  */
 400 int audio_meta_get_played_time(audio_meta_h audio, time_t *played_time);
 401
 402 /**
 403  * @deprecated Deprecated since 2.4.
 404  * @brief Gets the played position parameter of an audio.
 405  * @details This function returns audio's elapsed playback position parameter as a period
 406  *          starting from the beginning of the track.
 407  *
 408  * @since_tizen 2.3
 409  *
 410  * @param[in]  audio           The audio metadata handle
 411  * @param[out] played_position The elapsed time of the audio
 412  *
 413  * @return @c 0 on success,
 414  *         otherwise a negative error value
 415  *
 416  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 417  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 418  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 419  */
 420 int audio_meta_get_played_position(audio_meta_h audio, int *played_position);
 421
 422 /**
 423  * @deprecated Deprecated since 2.4. [Use media_info_increase_played_count() instead]
 424  * @brief Sets the played count to an audio meta handle.
 425  * @since_tizen 2.3
 426  *
 427  * @param[in] audio        The audio metadata handle
 428  * @param[in] played_count The played count of the audio
 429  *
 430  * @return @c 0 on success,
 431  *         otherwise a negative error value
 432  *
 433  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 434  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 435  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 436  *
 437  * @post audio_meta_update_to_db().
 438  */
 439 int audio_meta_set_played_count(audio_meta_h audio, int played_count);
 440
 441 /**
 442  * @deprecated Deprecated since 2.4. [Use media_info_set_played_time() instead]
 443  * @brief Sets the played time to an audio meta handle.
 444  * @since_tizen 2.3
 445  *
 446  * @param[in] audio       The audio metadata handle
 447  * @param[in] played_time The played time of the audio
 448  *
 449  * @return @c 0 on success,
 450  *         otherwise a negative error value
 451  *
 452  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 453  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 454  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 455  *
 456  * @post audio_meta_update_to_db().
 457  */
 458 int audio_meta_set_played_time(audio_meta_h audio, time_t played_time);
 459
 460 /**
 461  * @deprecated Deprecated since 2.4.
 462  * @brief Sets the played position to an audio meta handle.
 463  * @since_tizen 2.3
 464  *
 465  * @remarks  It is NOT recommended to use this attribute for your application-specific purpose because this attribute can be overwritten by other applications (even 0).
 466  *
 467  * @param[in] audio           The audio metadata handle
 468  * @param[in] played_position The played position of the audio
 469  *
 470  * @return @c 0 on success,
 471  *         otherwise a negative error value
 472  *
 473  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 474  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 475  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 476  *
 477  * @post audio_meta_update_to_db().
 478  */
 479 int audio_meta_set_played_position(audio_meta_h audio, int played_position);
 480
 481 /**
 482  * @brief Updates an audio metadata with modified attributes in the media database.
 483  * @details The function updates the given audio meta in the media database.
 484  *
 485  * @since_tizen 2.3
 486  * @privlevel public
 487  * @privilege %http://tizen.org/privilege/content.write
 488  *
 489  * @remarks The function should be called after any change in the attributes, to update the media database.
 490  *          For example, after using audio_meta_set_played_count() for changing the count of the played, the
 491  *          audio_meta_update_to_db() function should be called to update the given attributes in the media database. \n
 492  *          Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
 493  *
 494  * @param[in] audio The audio metadata handle
 495  *
 496  * @return @c 0 on success,
 497  *         otherwise a negative error value
 498  *
 499  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 500  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 501  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 502  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
 503  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 504  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 505  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
 506  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 507  *
 508  * @pre This function requires opened connection to content service by media_content_connect().
 509  *
 510  * @see media_content_connect()
 511  * @see audio_meta_set_played_count()
 512  * @see audio_meta_set_played_time()
 513  * @see audio_meta_set_played_position()
 514  */
 515 int audio_meta_update_to_db(audio_meta_h audio);
 516
 517 /**
 518  * @}
 519  */
 520
 521
 522 #ifdef __cplusplus
 523 }
 524 #endif
 525
 526 #endif /*__TIZEN_AUDIO_META_H__*/