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  * @pre This function requires opened connection to content service by media_content_connect().
 119  * @see media_content_connect()
 120  * @see media_playlist_delete_from_db()
 121  *
 122  */
 123 int media_playlist_insert_to_db(const char *name, media_playlist_h *playlist);
 124
 125 /**
 126  * @brief Deletes the given playlist from the media database.
 127  *
 128  * @param [in] playlist The handle to media playlist
 129  * @return 0 on success, otherwise a negative error value.
 130  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 131  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 132  * @pre This function requires opened connection to content service by media_content_connect().
 133  * @see media_content_connect()
 134  * @see media_playlist_insert_to_db()
 135  *
 136  */
 137 int media_playlist_delete_from_db(int playlist_id);
 138
 139 /**
 140  * @brief Gets the media playlist from the media database.
 141  *
 142  * @details This function creates a new media playlist handle from the media database by the given playlist_id.
 143  * media playlist will be created, which is filled with playlist information.
 144  *
 145  * @remarks @a playlist must be released with media_playlist_destroy() by you.
 146  *
 147  * @param[in] playlist_id The ID of media playlist
 148  * @param [in] filter The handle to audio filter
 149  * @param[out] playlist The media playlist handle associated with the playlist ID
 150  * @return 0 on success, otherwise a negative error value.
 151  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 152  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 153  * @pre This function requires opened connection to content service by media_content_connect().
 154  * @see media_content_connect()
 155  * @see media_playlist_destroy()
 156  *
 157  */
 158 int media_playlist_get_playlist_from_db(int playlist_id, filter_h filter, media_playlist_h *playlist);
 159
 160 /**
 161  * @brief Destroys a playlist handle.
 162  * @details Function frees all resources related to playlist handle. This
 163  * handle no longer can be used to perform any operation. New handle has to
 164  * be created before next usage.
 165  *
 166  * @param [in] playlist The handle to media playlist
 167  * @return 0 on success, otherwise a negative error value.
 168  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 169  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 170  * @see media_playlist_clone()
 171  * @pre Get copy of playlist handle by calling media_playlist_clone() or media_playlist_insert_to_db()
 172  * @see media_playlist_clone()
 173  *
 174  */
 175 int media_playlist_destroy(media_playlist_h playlist);
 176
 177 /**
 178  * @brief Clones playlist handle.
 179  * @details This function copies the media playlist handle from a source to
 180  * destination. There is no media_playlist_create() function. The media_playlist_h is created internally and available through
 181  * media playlist foreach function such as media_playlist_foreach_playlist_from_db(). To use this handle outside of these foreach functions,
 182  * use this function.
 183  *
 184  * @remark The destination handle must be released with media_playlist_destroy() by you.
 185  *
 186  * @param [in] src The source handle to media playlist
 187  * @param [out] dst A destination handle to media playlist
 188  * @return 0 on success, otherwise a negative error value.
 189  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 190  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 191  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 192  * @see media_playlist_destroy()
 193  * @see media_playlist_foreach_playlist_from_db()
 194  */
 195 int media_playlist_clone(media_playlist_h *dst, media_playlist_h src);
 196
 197 /**
 198  * @brief Gets media playlist's ID.
 199  *
 200  * @param [in] playlist The handle to media playlist
 201  * @param [out] playlist_id The ID of media playlist
 202  * @return 0 on success, otherwise a negative error value.
 203  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 204  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 205  */
 206 int media_playlist_get_playlist_id(media_playlist_h playlist, int *playlist_id);
 207
 208 /**
 209  * @brief Gets a name of the playlist.
 210  *
 211  * @remarks @a playlist_name must be released with free() by you.
 212  *
 213  * @param [in] playlist The handle to media playlist
 214  * @param [out] playlist_name The playlist name
 215  * @return 0 on success, otherwise a negative error value.
 216  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 217  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 218  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 219  *
 220  */
 221 int media_playlist_get_name(media_playlist_h playlist, char **playlist_name);
 222
 223 /**
 224  * @brief Sets the playlist name.
 225  *
 226  * @param[in] playlist The handle to media playlist
 227  * @param[in] playlist_name The name of the media playlist
 228  * @return 0 on success, otherwise a negative error value.
 229  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 230  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 231  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 232  * @post media_playlist_update_to_db()
 233  *
 234  */
 235 int media_playlist_set_name(media_playlist_h playlist, const char *playlist_name);
 236
 237 /**
 238  * @brief Sets the played order in the playlist.
 239  *
 240  * @param[in] playlist The handle to media playlist
 241  * @param[in] playlist_member_id The ID to member of playlist
 242  * @param[in] play_order The played order
 243  * @return 0 on success, otherwise a negative error value.
 244  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 245  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 246  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 247  * @post media_playlist_update_to_db()
 248  *
 249  */
 250 int media_playlist_set_play_order(media_playlist_h playlist, int playlist_member_id, int play_order);
 251
 252 /**
 253  * @brief Adds a new media info to the playlist.
 254  *
 255  * @param[in] playlist The handle to media playlist
 256  * @param[in] media_id The ID to media info which is added
 257  * @return 0 on success, otherwise a negative error value.
 258  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 259  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 260  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 261  * @pre This function requires opened connection to content service by media_content_connect().
 262  * @post media_playlist_update_to_db()
 263  * @see media_content_connect()
 264  * @see media_playlist_remove_media()
 265  *
 266  */
 267 int media_playlist_add_media(media_playlist_h playlist, const char *media_id);
 268
 269 /**
 270  * @brief Removes the playlist member related with media from the given playlist.
 271  *
 272  * @param[in] playlist The handle to media playlist
 273  * @param[in] playlist_member_id The ID to member of playlist
 274  * @return 0 on success, otherwise a negative error value.
 275  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 276  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 277  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 278  * @pre This function requires opened connection to content service by media_content_connect().
 279  * @post media_playlist_update_to_db()
 280  * @see media_content_connect()
 281  * @see media_playlist_add_media()
 282  *
 283  */
 284 int media_playlist_remove_media(media_playlist_h playlist, int playlist_member_id);
 285
 286 /**
 287  * @brief Gets the played order in the playlist.
 288  *
 289  * @param[in] playlist The handle to media playlist
 290  * @param[in] playlist_member_id The ID to member of playlist
 291  * @param [out] play_order The played order
 292  * @return 0 on success, otherwise a negative error value.
 293  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 294  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 295  */
 296 int media_playlist_get_play_order(media_playlist_h playlist, int playlist_member_id, int *play_order);
 297
 298 /**
 299  * @brief Updates the media playlist to the media database.
 300  *
 301  * @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
 302  * 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
 303  * the given playlist attibutes in the media database.
 304  *
 305  * @param[in] playlist The handle to media playlist
 306  * @return 0 on success, otherwise a negative error value.
 307  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 308  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 309  * @pre This function requires opened connection to content service by media_content_connect().
 310  * @see media_content_connect()
 311  * @see media_playlist_destroy()
 312  * @see media_playlist_add_media()
 313  * @see media_playlist_remove_media()
 314  * @see media_playlist_set_name()
 315  * @see media_playlist_set_play_order()
 316  *
 317  */
 318 int media_playlist_update_to_db(media_playlist_h playlist);
 319
 320 /**
 321  * @}
 322  */
 323
 324 #ifdef __cplusplus
 325 }
 326 #endif /* __cplusplus */
 327 #endif /*__TIZEN_MEDIA_PLAYLIST_H__*/