include/media_playlist.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 #ifndef __TIZEN_MEDIA_PLAYLIST_H__
  18 #define __TIZEN_MEDIA_PLAYLIST_H__
  19
  20 #include <media_content_type.h>
  21
  22 #ifdef __cplusplus
  23 extern "C" {
  24 #endif /* __cplusplus */
  25
  26 /**
  27  * @file
  28  * @brief This file contains the playlist API and functions related with handling playlists. \n
  29  *        Functions include operations to get the number of playlists, the number of media-info for the playlist  \n
  30  *        and all media files in the playlist, to clone, destroy, insert and delete playlist from DB,  \n
  31  *        to handle with name, ID, thumbnail, played order and media info of the playlist.
  32  */
  33
  34 /**
  35  * @addtogroup CAPI_CONTENT_MEDIA_PLAYLIST_MODULE
  36  * @{
  37  */
  38
  39
  40 /**
  41  * @brief Gets the number of playlists for the passed @a filter from the media database.
  42  * @since_tizen 2.3
  43  *
  44  * @param[in]  filter         The handle to the filter
  45  * @param[out] playlist_count The count of the media playlist
  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_DB_FAILED         DB operation failed
  53  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
  54  *
  55  * @pre This function requires opened connection to content service by media_content_connect().
  56  *
  57  * @see media_content_connect()
  58  */
  59 int media_playlist_get_playlist_count_from_db(filter_h filter, int *playlist_count);
  60
  61 /**
  62  * @brief Iterates through the media playlists with an optional @a filter from the media database.
  63  * @details This function gets all media playlists meeting the given filter.
  64  *          The callback function will be invoked for every retrieved media playlist.
  65  *          If @c NULL is passed to the filter, no filtering is applied.
  66  *
  67  * @since_tizen 2.3
  68  *
  69  * @param[in] filter    The handle to the audio filter
  70  * @param[in] callback  The callback function to be invoked
  71  * @param[in] user_data The user data to be passed to the callback function
  72  *
  73  * @return @c 0 on success,
  74  *         otherwise a negative error value
  75  *
  76  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  77  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  78  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
  79  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
  80  *
  81  * @pre  This function requires opened connection to content service by media_content_connect().
  82  * @post This function invokes media_playlist_cb().
  83  *
  84  * @see media_playlist_cb()
  85  * @see media_content_connect()
  86  * @see media_filter_create()
  87  */
  88 int media_playlist_foreach_playlist_from_db(filter_h filter, media_playlist_cb callback, void *user_data);
  89
  90 /**
  91  * @brief Gets the number of the media info for the given playlist present in the media database.
  92  * @since_tizen 2.3
  93  *
  94  * @param[in]  playlist_id  The ID of the media playlist
  95  * @param[in]  filter       The media filter handle
  96  * @param[out] media_count  The number of media items
  97  *
  98  * @return @c 0 on success,
  99  *         otherwise a negative error value
 100  *
 101  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 102  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 103  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 104  *
 105  * @pre This function requires opened connection to content service by media_content_connect().
 106  *
 107  * @see media_content_connect()
 108  */
 109 int media_playlist_get_media_count_from_db(int playlist_id, filter_h filter, int *media_count);
 110
 111 /**
 112  * @brief Iterates through the media files with an optional @a filter in the given audio playlist from the media database.
 113  * @details This function gets all media files associated with the given media playlist and
 114  *          meeting desired filter option and calls registered callback function for
 115  *          every retrieved media info. If @c NULL is passed to the @a filter, no filtering is applied.
 116  *
 117  * @since_tizen 2.3
 118  *
 119  * @param[in] playlist_id The ID of the media playlist
 120  * @param[in] filter      The audio filter handle
 121  * @param[in] callback    The callback function to be invoked
 122  * @param[in] user_data   The user data to be passed to the callback function
 123  *
 124  * @return @c 0 on success,
 125  *         otherwise a negative error value
 126  *
 127  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 128  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 129  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 130  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 131  *
 132  * @pre  This function requires opened connection to content service by media_content_connect().
 133  * @post This function invokes media_info_cb().
 134  *
 135  * @see media_info_cb()
 136  * @see media_content_connect()
 137  * @see media_filter_create()
 138  */
 139 int media_playlist_foreach_media_from_db(int playlist_id, filter_h filter, playlist_member_cb callback, void *user_data);
 140
 141 /**
 142  * @brief Inserts a new playlist with the given name into the media database.
 143  * @since_tizen 2.3
 144  *
 145  * @privlevel public
 146  * @privilege %http://tizen.org/privilege/content.write
 147  *
 148  * @remarks You must release the created handle using media_playlist_destroy().
 149  *
 150  * @param[in]  name     The name of the inserted playlist
 151  * @param[out] playlist A created handle to media playlist
 152  *
 153  * @return @c 0 on success,
 154  *         otherwise a negative error value
 155  *
 156  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 157  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 158  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 159  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
 160  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 161  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 162  * @retval #MEDIA_CONTENT_ERROR_NETWORK           Network fail
 163  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 164  *
 165  * @pre This function requires opened connection to content service by media_content_connect().
 166  *
 167  * @see media_content_connect()
 168  * @see media_playlist_delete_from_db()
 169  */
 170 int media_playlist_insert_to_db(const char *name, media_playlist_h *playlist);
 171
 172 /**
 173  * @brief Deletes the given playlist from the media database.
 174  * @since_tizen 2.3
 175  *
 176  * @privlevel public
 177  * @privilege %http://tizen.org/privilege/content.write
 178  *
 179  * @param[in] playlist_id The ID of media playlist
 180  *
 181  * @return @c 0 on success,
 182  *         otherwise a negative error value
 183  *
 184  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 185  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 186  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 187  *
 188  * @pre This function requires opened connection to content service by media_content_connect().
 189  *
 190  * @see media_content_connect()
 191  * @see media_playlist_insert_to_db()
 192  */
 193 int media_playlist_delete_from_db(int playlist_id);
 194
 195 /**
 196  * @brief Gets the media playlist from the media database.
 197  *
 198  * @details This function creates a new media playlist handle from the media database by the given @a playlist_id.
 199  *          The media playlist will be created and will be filled with the playlist information.
 200  *
 201  * @since_tizen 2.3
 202  *
 203  * @remarks You must release @a playlist using media_playlist_destroy().
 204  *
 205  * @param[in]  playlist_id The ID of the media playlist
 206  * @param[out] playlist    The media playlist handle associated with the playlist ID
 207  *
 208  * @return @c 0 on success,
 209  *         otherwise a negative error value
 210  *
 211  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 212  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 213  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 214  *
 215  * @pre This function requires opened connection to content service by media_content_connect().
 216  *
 217  * @see media_content_connect()
 218  * @see media_playlist_destroy()
 219  */
 220 int media_playlist_get_playlist_from_db(int playlist_id, media_playlist_h *playlist);
 221
 222 /**
 223  * @brief Destroys a playlist handle.
 224  * @details This function frees all resources related to the playlist handle. This
 225  *          handle no longer can be used to perform any operation. A new handle has to
 226  *          be created before next usage.
 227  *
 228  * @since_tizen 2.3
 229  *
 230  * @param[in] playlist The media playlist handle
 231  *
 232  * @return @c 0 on success,
 233  *         otherwise a negative error value
 234  *
 235  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 236  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 237  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 238  *
 239  * @pre Get a copy of playlist handle by calling media_playlist_clone() or media_playlist_insert_to_db().
 240  *
 241  * @see media_playlist_clone()
 242  */
 243 int media_playlist_destroy(media_playlist_h playlist);
 244
 245 /**
 246  * @brief Clones a playlist handle.
 247  * @details This function copies the media playlist handle from a source to
 248  *          destination. There is no media_playlist_create() function. The media_playlist_h is created internally and available through
 249  *          media playlist foreach function such as media_playlist_foreach_playlist_from_db().
 250  *          To use this handle outside of these foreach functions, use this function.
 251  *
 252  * @since_tizen 2.3
 253  *
 254  * @remarks The destination handle must be released using media_playlist_destroy().
 255  *
 256  * @param[in]  src  The source handle of a media playlist
 257  * @param[out] dst  The destination handle to a media playlist
 258  *
 259  * @return @c 0 on success,
 260  *         otherwise a negative error value
 261  *
 262  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 263  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 264  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 265  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 266  *
 267  * @see media_playlist_destroy()
 268  * @see media_playlist_foreach_playlist_from_db()
 269  */
 270 int media_playlist_clone(media_playlist_h *dst, media_playlist_h src);
 271
 272 /**
 273  * @brief Gets the media playlist ID.
 274  * @since_tizen 2.3
 275  *
 276  * @param[in]  playlist    The media playlist handle
 277  * @param[out] playlist_id The ID of the media playlist
 278  *
 279  * @return @c 0 on success,
 280  *         otherwise a negative error value
 281  *
 282  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 283  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 284  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 285  */
 286 int media_playlist_get_playlist_id(media_playlist_h playlist, int *playlist_id);
 287
 288 /**
 289  * @brief Gets a name of the playlist.
 290  * @since_tizen 2.3
 291  *
 292  * @remarks You must release @a playlist_name using free().
 293  *
 294  * @param[in]  playlist      The media playlist handle
 295  * @param[out] playlist_name The playlist name
 296  *
 297  * @return @c 0 on success,
 298  *         otherwise a negative error value
 299  *
 300  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 301  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 302  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 303  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 304  */
 305 int media_playlist_get_name(media_playlist_h playlist, char **playlist_name);
 306
 307 /**
 308  * @brief Sets the name of the playlist.
 309  * @since_tizen 2.3
 310  *
 311  * @param[in] playlist      The media playlist handle
 312  * @param[in] playlist_name The name of the media playlist
 313  *
 314  * @return @c 0 on success,
 315  *         otherwise a negative error value
 316  *
 317  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 318  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 319  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 320  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 321  *
 322  * @post media_playlist_update_to_db()
 323  *
 324  */
 325 int media_playlist_set_name(media_playlist_h playlist, const char *playlist_name);
 326
 327 /**
 328  * @brief Gets a thumbnail path of the playlist.
 329  * @since_tizen 2.3
 330  *
 331  * @remarks You must release @a path using free().
 332  *
 333  * @param[in]  playlist The media playlist handle
 334  * @param[out] path     The path of the thumbnail
 335  *
 336  * @return @c 0 on success,
 337  *         otherwise a negative error value
 338  *
 339  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 340  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 341  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 342  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 343  */
 344 int media_playlist_get_thumbnail_path(media_playlist_h playlist, char **path);
 345
 346 /**
 347  * @brief Sets the thumbnail path of the playlist.
 348  * @since_tizen 2.3
 349  *
 350  * @param[in] playlist The media playlist handle
 351  * @param[in] path     The path of the thumbnail
 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  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 359  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 360  *
 361  * @post media_playlist_update_to_db()
 362  */
 363 int media_playlist_set_thumbnail_path(media_playlist_h playlist, const char *path);
 364
 365
 366 /**
 367  * @brief Sets the playing order in the playlist.
 368  * @since_tizen 2.3
 369  *
 370  * @param[in] playlist           The media playlist handle
 371  * @param[in] playlist_member_id The playlist member ID
 372  * @param[in] play_order         The playing order
 373  *
 374  * @return @c 0 on success,
 375  *         otherwise a negative error value
 376  *
 377  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 378  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 379  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 380  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 381  *
 382  * @post media_playlist_update_to_db()
 383  */
 384 int media_playlist_set_play_order(media_playlist_h playlist, int playlist_member_id, int play_order);
 385
 386 /**
 387  * @brief Adds a new media info to the playlist.
 388  * @since_tizen 2.3
 389  *
 390  * @param[in] playlist The media playlist handle
 391  * @param[in] media_id The ID to the media info which is added
 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_OUT_OF_MEMORY     Out of memory
 399  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 400  *
 401  * @pre  This function requires opened connection to content service by media_content_connect().
 402  * @post media_playlist_update_to_db()
 403  *
 404  * @see media_content_connect()
 405  * @see media_playlist_remove_media()
 406  */
 407 int media_playlist_add_media(media_playlist_h playlist, const char *media_id);
 408
 409 /**
 410  * @brief Removes the playlist members related with the media from the given playlist.
 411  * @since_tizen 2.3
 412  *
 413  * @param[in] playlist           The media playlist handle
 414  * @param[in] playlist_member_id The playlist member ID
 415  *
 416  * @return @c 0 on success,
 417  *         otherwise a negative error value
 418  *
 419  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 420  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 421  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 422  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 423  *
 424  * @pre  This function requires opened connection to content service by media_content_connect().
 425  * @post media_playlist_update_to_db()
 426  *
 427  * @see media_content_connect()
 428  * @see media_playlist_add_media()
 429  */
 430 int media_playlist_remove_media(media_playlist_h playlist, int playlist_member_id);
 431
 432 /**
 433  * @brief Gets the played order of the playlist.
 434  * @since_tizen 2.3
 435  *
 436  * @param[in] playlist           The media playlist handle
 437  * @param[in] playlist_member_id The playlist member ID
 438  * @param[out] play_order        The played order
 439  *
 440  * @return @c 0 on success,
 441  *         otherwise a negative error value
 442  *
 443  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 444  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 445  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 446  */
 447 int media_playlist_get_play_order(media_playlist_h playlist, int playlist_member_id, int *play_order);
 448
 449 /**
 450  * @brief Updates the media playlist to the media database.
 451  *
 452  * @details The function updates the given media playlist in the media database.
 453  *          The function should be called after any change in the playlist, to be updated to the media database.
 454  *          For example, after using media_playlist_set_name() for setting the name of the playlist, the
 455  *          media_playlist_update_to_db() function should be called so as to update
 456  *          the given playlist attributes in the media database.
 457  *
 458  * @since_tizen 2.3
 459  *
 460  * @privlevel public
 461  * @privilege %http://tizen.org/privilege/content.write
 462  *
 463  * @param[in] playlist The media playlist handle
 464  *
 465  * @return @c 0 on success,
 466  *         otherwise a negative error value
 467  *
 468  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 469  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 470  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 471  *
 472  * @pre This function requires opened connection to content service by media_content_connect().
 473  *
 474  * @see media_content_connect()
 475  * @see media_playlist_destroy()
 476  * @see media_playlist_add_media()
 477  * @see media_playlist_remove_media()
 478  * @see media_playlist_set_name()
 479  * @see media_playlist_set_play_order()
 480  */
 481 int media_playlist_update_to_db(media_playlist_h playlist);
 482
 483 /**
 484  * @}
 485  */
 486
 487 #ifdef __cplusplus
 488 }
 489 #endif /* __cplusplus */
 490 #endif /*__TIZEN_MEDIA_PLAYLIST_H__*/