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
  28 /**
  29  * @addtogroup CAPI_CONTENT_MEDIA_PLAYLIST_MODULE
  30  * @{
  31  */
  32
  33 /**
  34  * @brief Gets the number of playlist for the passed @a filter from the media database.
  35  *
  36  * @param[in] filter The handle to filter.
  37  * @param[out] playlist_count The count of media playlist
  38  * @return 0 on success, otherwise a negative error value.
  39  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  40  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  41  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
  42  * @pre This function requires opened connection to content service by media_content_connect().
  43  * @see media_content_connect()
  44  *
  45  */
  46 int media_playlist_get_playlist_count_from_db(filter_h filter, int *playlist_count);
  47
  48 /**
  49  * @brief Iterates through the media playlist with optional @a filter from the media database.
  50  * @details This function gets all media playlist handles meeting the given filter.
  51  * The callback function will be invoked for every retrieved media playlist.
  52  * If NULL is passed to the filter, no filtering is applied.
  53  *
  54  * @param [in] filter The handle to audio filter
  55  * @param [in] callback The callback function to invoke
  56  * @param [in] user_data User data to be passed to the callback function
  57  * @return 0 on success, otherwise a negative error value.
  58  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  59  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  60  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
  61  * @pre This function requires opened connection to content service by media_content_connect().
  62  * @post This function invokes media_playlist_cb().
  63  * @see #media_playlist_cb
  64  * @see media_content_connect()
  65  * @see media_filter_create()
  66  *
  67  */
  68 int media_playlist_foreach_playlist_from_db(filter_h filter, media_playlist_cb callback, void *user_data);
  69
  70 /**
  71  * @brief Gets number of media info for the given playlist present in the media database.
  72  *
  73  * @param [in] playlist_id The ID of media playlist
  74  * @param [in] filter The handle to media filter
  75  * @param [out] media_count The number of media items
  76  * @return 0 on success, otherwise a negative error value.
  77  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  78  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  79  * @pre This function requires opened connection to content service by media_content_connect().
  80  * @see media_content_connect()
  81  *
  82  */
  83 int media_playlist_get_media_count_from_db(int playlist_id, filter_h filter, int *media_count);
  84
  85 /**
  86  * @brief Iterates through the media files with optional @a filter in the given @a audio @a playlist from the media database.
  87  * @details This function gets all media files associated with the given media playlist and
  88  * meeting desired filter option and calls registered callback function for
  89  * every retrieved media info. If NULL is passed to the @a filter, no filtering is applied.
  90  *
  91  * @param [in] playlist_id The ID of media playlist
  92  * @param [in] filter The handle to audio filter
  93  * @param [in] callback The callback function to invoke
  94  * @param [in] user_data The user data to be passed to the callback function
  95  * @return 0 on success, otherwise a negative error value.
  96  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  97  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  98  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
  99  * @pre This function requires opened connection to content service by media_content_connect().
 100  * @post This function invokes media_info_cb().
 101  * @see #media_info_cb
 102  * @see media_content_connect()
 103  * @see media_filter_create()
 104  *
 105  */
 106 int media_playlist_foreach_media_from_db(int playlist_id, filter_h filter, playlist_member_cb callback, void *user_data);
 107
 108 /**
 109  * @brief Inserts a new playlist with given name in the media database.
 110  *
 111  * @remark The created handle must be released with media_playlist_destroy() by you.
 112  * @param [in] name The name of the inserted playlist
 113  * @param [out] playlist A created handle to media playlist
 114  * @return 0 on success, otherwise a negative error value.
 115  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 116  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 117  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 118  * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid Operation
 119  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
 120  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation BUSY
 121  * @retval #MEDIA_CONTENT_ERROR_NETWORK Network Fail
 122  * @pre This function requires opened connection to content service by media_content_connect().
 123  * @see media_content_connect()
 124  * @see media_playlist_delete_from_db()
 125  *
 126  */
 127 int media_playlist_insert_to_db(const char *name, media_playlist_h *playlist);
 128
 129 /**
 130  * @brief Deletes the given playlist from the media database.
 131  *
 132  * @param [in] playlist The handle to media playlist
 133  * @return 0 on success, otherwise a negative error value.
 134  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 135  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 136  * @pre This function requires opened connection to content service by media_content_connect().
 137  * @see media_content_connect()
 138  * @see media_playlist_insert_to_db()
 139  *
 140  */
 141 int media_playlist_delete_from_db(int playlist_id);
 142
 143 /**
 144  * @brief Gets the media playlist from the media database.
 145  *
 146  * @details This function creates a new media playlist handle from the media database by the given playlist_id.
 147  * media playlist will be created, which is filled with playlist information.
 148  *
 149  * @remarks @a playlist must be released with media_playlist_destroy() by you.
 150  *
 151  * @param[in] playlist_id The ID of media playlist
 152  * @param[out] playlist The media playlist handle associated with the playlist ID
 153  * @return 0 on success, otherwise a negative error value.
 154  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 155  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 156  * @pre This function requires opened connection to content service by media_content_connect().
 157  * @see media_content_connect()
 158  * @see media_playlist_destroy()
 159  *
 160  */
 161 int media_playlist_get_playlist_from_db(int playlist_id, media_playlist_h *playlist);
 162
 163 /**
 164  * @brief Destroys a playlist handle.
 165  * @details Function frees all resources related to playlist handle. This
 166  * handle no longer can be used to perform any operation. New handle has to
 167  * be created before next usage.
 168  *
 169  * @param [in] playlist The handle to media playlist
 170  * @return 0 on success, otherwise a negative error value.
 171  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 172  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 173  * @see media_playlist_clone()
 174  * @pre Get copy of playlist handle by calling media_playlist_clone() or media_playlist_insert_to_db()
 175  * @see media_playlist_clone()
 176  *
 177  */
 178 int media_playlist_destroy(media_playlist_h playlist);
 179
 180 /**
 181  * @brief Clones playlist handle.
 182  * @details This function copies the media playlist handle from a source to
 183  * destination. There is no media_playlist_create() function. The media_playlist_h is created internally and available through
 184  * media playlist foreach function such as media_playlist_foreach_playlist_from_db(). To use this handle outside of these foreach functions,
 185  * use this function.
 186  *
 187  * @remark The destination handle must be released with media_playlist_destroy() by you.
 188  *
 189  * @param [in] src The source handle to media playlist
 190  * @param [out] dst A destination handle to media playlist
 191  * @return 0 on success, otherwise a negative error value.
 192  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 193  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 194  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 195  * @see media_playlist_destroy()
 196  * @see media_playlist_foreach_playlist_from_db()
 197  */
 198 int media_playlist_clone(media_playlist_h *dst, media_playlist_h src);
 199
 200 /**
 201  * @brief Gets media playlist's ID.
 202  *
 203  * @param [in] playlist The handle to media playlist
 204  * @param [out] playlist_id The ID of media playlist
 205  * @return 0 on success, otherwise a negative error value.
 206  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 207  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 208  */
 209 int media_playlist_get_playlist_id(media_playlist_h playlist, int *playlist_id);
 210
 211 /**
 212  * @brief Gets a name of the playlist.
 213  *
 214  * @remarks @a playlist_name must be released with free() by you.
 215  *
 216  * @param [in] playlist The handle to media playlist
 217  * @param [out] playlist_name The playlist name
 218  * @return 0 on success, otherwise a negative error value.
 219  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 220  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 221  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 222  *
 223  */
 224 int media_playlist_get_name(media_playlist_h playlist, char **playlist_name);
 225
 226 /**
 227  * @brief Sets the playlist name.
 228  *
 229  * @param[in] playlist The handle to media playlist
 230  * @param[in] playlist_name The name of the media playlist
 231  * @return 0 on success, otherwise a negative error value.
 232  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 233  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 234  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 235  * @post media_playlist_update_to_db()
 236  *
 237  */
 238 int media_playlist_set_name(media_playlist_h playlist, const char *playlist_name);
 239
 240 /**
 241  * @brief Gets a thumbnail path of the playlist.
 242  *
 243  * @remarks @a path must be released with free() by you.
 244  *
 245  * @param [in] playlist The handle to media playlist
 246  * @param [out] path The path of thumbnail
 247  * @return 0 on success, otherwise a negative error value.
 248  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 249  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 250  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 251  *
 252  */
 253 int media_playlist_get_thumbnail_path(media_playlist_h playlist, char **path);
 254
 255 /**
 256  * @brief Sets the thumbnail path of the playlist.
 257  *
 258  * @param[in] playlist The handle to media playlist
 259  * @param[in] path The path of thumbnail
 260  * @return 0 on success, otherwise a negative error value.
 261  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 262  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 263  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 264  * @post media_playlist_update_to_db()
 265  *
 266  */
 267 int media_playlist_set_thumbnail_path(media_playlist_h playlist, const char *path);
 268
 269
 270 /**
 271  * @brief Sets the played order in the playlist.
 272  *
 273  * @param[in] playlist The handle to media playlist
 274  * @param[in] playlist_member_id The ID to member of playlist
 275  * @param[in] play_order The played order
 276  * @return 0 on success, otherwise a negative error value.
 277  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 278  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 279  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 280  * @post media_playlist_update_to_db()
 281  *
 282  */
 283 int media_playlist_set_play_order(media_playlist_h playlist, int playlist_member_id, int play_order);
 284
 285 /**
 286  * @brief Adds a new media info to the playlist.
 287  *
 288  * @param[in] playlist The handle to media playlist
 289  * @param[in] media_id The ID to media info which is added
 290  * @return 0 on success, otherwise a negative error value.
 291  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 292  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 293  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 294  * @pre This function requires opened connection to content service by media_content_connect().
 295  * @post media_playlist_update_to_db()
 296  * @see media_content_connect()
 297  * @see media_playlist_remove_media()
 298  *
 299  */
 300 int media_playlist_add_media(media_playlist_h playlist, const char *media_id);
 301
 302 /**
 303  * @brief Removes the playlist member related with media from the given playlist.
 304  *
 305  * @param[in] playlist The handle to media playlist
 306  * @param[in] playlist_member_id The ID to member of playlist
 307  * @return 0 on success, otherwise a negative error value.
 308  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 309  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 310  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 311  * @pre This function requires opened connection to content service by media_content_connect().
 312  * @post media_playlist_update_to_db()
 313  * @see media_content_connect()
 314  * @see media_playlist_add_media()
 315  *
 316  */
 317 int media_playlist_remove_media(media_playlist_h playlist, int playlist_member_id);
 318
 319 /**
 320  * @brief Gets the played order in the playlist.
 321  *
 322  * @param[in] playlist The handle to media playlist
 323  * @param[in] playlist_member_id The ID to member of playlist
 324  * @param [out] play_order The played order
 325  * @return 0 on success, otherwise a negative error value.
 326  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 327  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 328  */
 329 int media_playlist_get_play_order(media_playlist_h playlist, int playlist_member_id, int *play_order);
 330
 331 /**
 332  * @brief Updates the media playlist to the media database.
 333  *
 334  * @details The function updates the given media playlist in the media database. The function should be called after any change in playlist, to be updated to the media
 335  * database. For example, after using media_playlist_set_name() for setting the name of the playlist, media_playlist_update_to_db() function should be called so as to update
 336  * the given playlist attibutes in the media database.
 337  *
 338  * @param[in] playlist The handle to media playlist
 339  * @return 0 on success, otherwise a negative error value.
 340  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 341  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 342  * @pre This function requires opened connection to content service by media_content_connect().
 343  * @see media_content_connect()
 344  * @see media_playlist_destroy()
 345  * @see media_playlist_add_media()
 346  * @see media_playlist_remove_media()
 347  * @see media_playlist_set_name()
 348  * @see media_playlist_set_play_order()
 349  *
 350  */
 351 int media_playlist_update_to_db(media_playlist_h playlist);
 352
 353 /**
 354  * @}
 355  */
 356
 357 #ifdef __cplusplus
 358 }
 359 #endif /* __cplusplus */
 360 #endif /*__TIZEN_MEDIA_PLAYLIST_H__*/