include_product/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 #ifdef __cplusplus
  24 extern "C" {
  25 #endif /* __cplusplus */
  26
  27 /**
  28  * @file media_audio.h
  29  * @brief This file contains the audio metadata API and related functions to proceed with audio metadata. \n
  30  *        Description of the audio content involves: album, artist, album_artist, author, genre and description tags. \n
  31  *        Parameters of the recording are also supported such as format, bitrate, duration, size etc.
  32  */
  33
  34 /**
  35  * @addtogroup CAPI_CONTENT_MEDIA_AUDIO_META_MODULE
  36  * @{
  37  */
  38
  39 /**
  40  * @brief Clones the audio metadata.
  41  * @details This function copies the audio metadata handle from a source to destination.
  42  *
  43  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  44  *
  45  * @remarks You must release the destination handle using audio_meta_destroy().
  46  *
  47  * @param[out] dst The destination handle to the audio metadata
  48  * @param[in]  src The source handle to the audio metadata
  49  *
  50  * @return @c 0 on success,
  51  *         otherwise a negative error value
  52  *
  53  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  54  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  55  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
  56  *
  57  * @see audio_meta_destroy()
  58  */
  59 int audio_meta_clone(audio_meta_h *dst, audio_meta_h src);
  60
  61 /**
  62  * @brief Destroys the audio metadata.
  63  * @details This function frees all resources related to the audio metadata handle. This handle
  64  *          no longer can be used to perform any operation. A new handle has to
  65  *          be created before the next use.
  66  *
  67  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  68  *
  69  * @param[in] audio The audio metadata handle
  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  *
  77  * @pre Get a copy of audio metadata handle handle by calling audio_meta_clone().
  78  *
  79  * @see audio_meta_clone()
  80  */
  81 int audio_meta_destroy(audio_meta_h audio);
  82
  83 /**
  84  * @brief Gets the ID of the media of the given audio metadata.
  85  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  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  */
  99 int audio_meta_get_media_id(audio_meta_h audio, char **media_id);
 100
 101 /**
 102  * @brief Gets the album of the given audio metadata.
 103  * @details If the value is an empty string, the method returns "Unknown". \n
 104  *                Since 3.0, if the media content has no album info, the method returns empty string.
 105  *
 106  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 107  *
 108  * @remarks You must release @a album using free().
 109  *
 110  * @param[in]  audio The audio metadata handle
 111  * @param[out] album The album of the audio metadata
 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  */
 120 int audio_meta_get_album(audio_meta_h audio, char **album);
 121
 122 /**
 123  * @brief Gets the artist of the given audio metadata.
 124  * @details If the value is an empty string, the method returns "Unknown". \n
 125  *                Since 3.0, if the media content has no artist info, the method returns empty string.
 126  *
 127  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 128  *
 129  * @remarks You must release @a artist using free().
 130  *
 131  * @param[in]  audio  The audio metadata handle
 132  * @param[out] artist The artist of the audio metadata
 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  */
 141 int audio_meta_get_artist(audio_meta_h audio, char **artist);
 142
 143 /**
 144  * @brief Gets the album artist of the given audio metadata.
 145  * @details If the value is an empty string, the method returns "Unknown". \n
 146  *                Since 3.0, if the media content has no album artist info, the method returns empty string.
 147  *
 148  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 149  *
 150  * @remarks You must release @a album_artist using free().
 151  *
 152  * @param[in]  audio        The audio metadata handle
 153  * @param[out] album_artist The album artist of the audio metadata
 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  */
 162 int audio_meta_get_album_artist(audio_meta_h audio, char **album_artist);
 163
 164 /**
 165  * @brief Gets the genre of the given audio metadata.
 166  * @details If the value is an empty string, the method returns "Unknown". \n
 167  *                Since 3.0, if the media content has no genre info, the method returns empty string.
 168  *
 169  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 170  *
 171  * @remarks You must release @a genre using free().
 172  *
 173  * @param[in]  audio The audio metadata handle
 174  * @param[out] genre The genre of the audio metadata
 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  */
 183 int audio_meta_get_genre(audio_meta_h audio, char **genre);
 184
 185 /**
 186  * @brief Gets the composer of the given audio metadata.
 187  * @details If the value is an empty string, the method returns "Unknown". \n
 188  *                Since 3.0, if the media content has no composer info, the method returns empty string.
 189  *
 190  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 191  *
 192  * @remarks You must release @a composer using free().
 193  *
 194  * @param[in]  audio    The audio metadata handle
 195  * @param[out] composer The composer of the audio metadata
 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  */
 204 int audio_meta_get_composer(audio_meta_h audio, char **composer);
 205
 206 /**
 207  * @brief Gets the year of the given audio metadata.
 208  * @details If the value is an empty string, the method returns "Unknown". \n
 209  *                Since 3.0, if the media content has no year info, the method returns empty string.
 210  *
 211  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 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 metadata
 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  */
 225 int audio_meta_get_year(audio_meta_h audio, char **year);
 226
 227 /**
 228  * @brief Gets the recorded date of the given audio metadata.
 229  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 230  *
 231  * @remarks You must release @a recorded_date using free().
 232  *
 233  * @param[in]  audio         The audio metadata handle
 234  * @param[out] recorded_date The recorded date of the audio metadata
 235  *
 236  * @return @c 0 on success,
 237  *         otherwise a negative error value
 238  *
 239  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 240  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 241  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 242  */
 243 int audio_meta_get_recorded_date(audio_meta_h audio, char **recorded_date);
 244
 245 /**
 246  * @brief Gets the copyright notice of the given audio metadata.
 247  * @details If the media content has no copyright info, the method returns empty string.
 248  *
 249  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 250  *
 251  * @remarks You must release @a copyright using free().
 252  *
 253  * @param[in]  audio     The audio metadata handle
 254  * @param[out] copyright The copyright of the audio metadata
 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  */
 263 int audio_meta_get_copyright(audio_meta_h audio, char **copyright);
 264
 265 /**
 266  * @brief Gets the track number of the given audio metadata.
 267  * @details If the value is an empty string, the method returns "Unknown". \n
 268  *                Since 3.0, if the media content has no track info, the method returns empty string.
 269  *
 270  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 271  *
 272  * @remarks You must release @a track_num using free().
 273  *
 274  * @param[in]  audio     The audio metadata handle
 275  * @param[out] track_num The audio track number of the audio metadata
 276  *
 277  * @return @c 0 on success,
 278  *         otherwise a negative error value
 279  *
 280  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 281  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 282  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 283  */
 284 int audio_meta_get_track_num(audio_meta_h audio, char **track_num);
 285
 286 /**
 287  * @brief Gets the bitrate of the given audio metadata in bitrate per second.
 288  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 289  *
 290  * @param[in]  audio    The audio metadata handle
 291  * @param[out] bit_rate The audio bitrate in bit per second [bps]
 292  *
 293  * @return @c 0 on success,
 294  *         otherwise a negative error value
 295  *
 296  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 297  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 298  */
 299 int audio_meta_get_bit_rate(audio_meta_h audio, int *bit_rate);
 300
 301 /**
 302  * @brief Gets bit per sample of the given audio metadata.
 303  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 304  *
 305  * @param [in]  audio        The handle to the audio metadata
 306  * @param [out] bitpersample The audio bit per sample
 307  *
 308  * @return @c 0 on success,
 309  *         otherwise a negative error value
 310  *
 311  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 312  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 313  */
 314 int audio_meta_get_bitpersample(audio_meta_h audio, int *bitpersample);
 315
 316 /**
 317  * @brief Gets the sample rate of the given audio metadata.
 318  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 319  *
 320  * @param[in]  audio       The audio metadata handle
 321  * @param[out] sample_rate The audio sample rate[hz]
 322  *
 323  * @return @c 0 on success,
 324  *         otherwise a negative error value
 325  *
 326  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 327  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 328  */
 329 int audio_meta_get_sample_rate(audio_meta_h audio, int *sample_rate);
 330
 331 /**
 332  * @brief Gets the channel of the given audio metadata.
 333  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 334  *
 335  * @param[in]  audio   The audio metadata handle
 336  * @param[out] channel The channel of the audio
 337  *
 338  * @return @c 0 on success,
 339  *         otherwise a negative error value
 340  *
 341  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 342  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 343  */
 344 int audio_meta_get_channel(audio_meta_h audio, int *channel);
 345
 346 /**
 347  * @brief Gets the track duration of the given audio metadata.
 348  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 349  *
 350  * @param[in]  audio    The audio metadata handle
 351  * @param[out] duration The audio file duration
 352  *
 353  * @return @c 0 on success,
 354  *         otherwise a negative error value
 355  *
 356  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 357  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 358  */
 359 int audio_meta_get_duration(audio_meta_h audio, int *duration);
 360
 361 /**
 362  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. \n
 363  *        This function does not guarantee independence of the played count value between applications. It is recommended that the value is managed by the application.
 364  * @brief Gets the number of times the given audio has been played.
 365  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 366  *
 367  * @param[in]  audio        The audio metadata handle
 368  * @param[out] played_count The counter of the audio played
 369  *
 370  * @return @c 0 on success,
 371  *         otherwise a negative error value
 372  *
 373  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 374  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 375  */
 376 int audio_meta_get_played_count(audio_meta_h audio, int *played_count) TIZEN_DEPRECATED_API;
 377
 378 /**
 379  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. \n
 380  *        This function does not guarantee independence of the played time value between applications. It is recommended that the value is managed by the application.
 381  * @brief Gets the last played time parameter of the audio.
 382  *
 383  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 384  *
 385  * @param[in]  audio       The audio metadata handle
 386  * @param[out] played_time The last played time of the audio
 387  *
 388  * @return @c 0 on success,
 389  *         otherwise a negative error value
 390  *
 391  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 392  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 393  */
 394 int audio_meta_get_played_time(audio_meta_h audio, time_t *played_time) TIZEN_DEPRECATED_API;
 395
 396 /**
 397  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. \n
 398  *        This function does not guarantee independence of the played position value between applications. It is recommended that the value is managed by the application.
 399  * @brief Gets the played position parameter of the audio.
 400  * @details This function returns the elapsed playback position parameter of the audio as a period
 401  *          starting from the beginning of the track.
 402  *
 403  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 404  *
 405  * @param[in]  audio           The audio metadata handle
 406  * @param[out] played_position The elapsed time of the audio
 407  *
 408  * @return @c 0 on success,
 409  *         otherwise a negative error value
 410  *
 411  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 412  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 413  */
 414 int audio_meta_get_played_position(audio_meta_h audio, int *played_position) TIZEN_DEPRECATED_API;
 415
 416 /**
 417  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. \n
 418  *        This function does not guarantee independence of the played count value between applications. It is recommended that the value is managed by the application.
 419  * @brief Sets the played count of the audio.
 420  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 421  *
 422  * @param[in] audio        The audio metadata handle
 423  * @param[in] played_count The played count of the audio
 424  *
 425  * @return @c 0 on success,
 426  *         otherwise a negative error value
 427  *
 428  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 429  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 430  */
 431 int audio_meta_set_played_count(audio_meta_h audio, int played_count) TIZEN_DEPRECATED_API;
 432
 433 /**
 434  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. \n
 435  *        This function does not guarantee independence of the played time value between applications. It is recommended that the value is managed by the application.
 436  * @brief Sets the last played time of the audio.
 437  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 438  *
 439  * @param[in] audio       The audio metadata handle
 440  * @param[in] played_time The last played time of the audio
 441  *
 442  * @return @c 0 on success,
 443  *         otherwise a negative error value
 444  *
 445  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 446  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 447  */
 448 int audio_meta_set_played_time(audio_meta_h audio, time_t played_time) TIZEN_DEPRECATED_API;
 449
 450 /**
 451  * @deprecated Deprecated since @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif. \n
 452  *        This function does not guarantee independence of the played position value between applications. It is recommended that the value is managed by the application.
 453  * @brief Sets the played position of the audio.
 454  *
 455  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 456  *
 457  * @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).
 458  *
 459  * @param[in] audio           The audio metadata handle
 460  * @param[in] played_position The played position of the audio
 461  *
 462  * @return @c 0 on success,
 463  *         otherwise a negative error value
 464  *
 465  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 466  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 467  */
 468 int audio_meta_set_played_position(audio_meta_h audio, int played_position) TIZEN_DEPRECATED_API;
 469
 470 /**
 471  * @deprecated Deprecated since 4.0. Related setter functions are deprecated, therefore this function is not needed anymore.
 472  * @brief Updates an audio metadata with modified attributes in the media database.
 473  * @details The function updates the given audio meta in the media database. The function should be called after any change in audio attributes, to be updated to the media
 474  *          database.
 475  *
 476  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 477  *
 478  * @privlevel public
 479  * @privilege %http://tizen.org/privilege/content.write
 480  *
 481  * @remarks Do not call this function in callback function of foreach function like media_info_foreach_media_from_db().
 482  *
 483  * @param[in] audio The audio metadata handle
 484  *
 485  * @return @c 0 on success,
 486  *         otherwise a negative error value
 487  *
 488  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 489  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 490  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 491  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
 492  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 493  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 494  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
 495  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 496  *
 497  * @pre This function requires opened connection to content service by media_content_connect().
 498  *
 499  * @see media_content_connect()
 500  */
 501 int audio_meta_update_to_db(audio_meta_h audio) TIZEN_DEPRECATED_API;
 502
 503 /**
 504  *@}
 505  */
 506
 507 #ifdef __cplusplus
 508 }
 509 #endif /* __cplusplus */
 510
 511 #endif /*__TIZEN_AUDIO_META_H__*/