include/media_group.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_GROUP_H__
  18 #define __TIZEN_MEDIA_GROUP_H__
  19
  20
  21 #include <media_content_type.h>
  22
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif /* __cplusplus */
  27
  28 /**
  29  * @addtogroup CAPI_CONTENT_MEDIA_ALBUM_MODULE
  30  * @{
  31  */
  32
  33 /**
  34  * @brief Gets the number of album for the passed @a filter from the media database.
  35  *
  36  * @param[in] filter The handle to media filter.
  37  * @param[out] album_count The count of media album
  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_album_get_album_count_from_db(filter_h filter, int *album_count);
  47
  48 /**
  49  * @brief Iterates through the media album with optional @a filter from the media database.
  50  * @details This function gets all media album handles meeting the given filter.
  51  * The callback function will be invoked for every retrieved media album.
  52  * If NULL is passed to the filter, no filtering is applied.
  53  *
  54  * @param [in] filter The handle to media filter
  55  * @param [in] callback The callback function to invoke
  56  * @param [in] user_data The 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_album_cb().
  63  * @see #media_album_cb
  64  * @see media_content_connect()
  65  * @see media_filter_create()
  66  *
  67  */
  68 int media_album_foreach_album_from_db(filter_h filter, media_album_cb callback, void *user_data);
  69
  70 /**
  71  * @brief Gets number of media info for the given album present in the media database.
  72  *
  73  * @param [in] album_id The ID of media album
  74  * @param [in] filter The handle to media filter
  75  * @param [out] media_count A count of album
  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 int media_album_get_media_count_from_db (int album_id, filter_h filter, int *media_count);
  83
  84 /**
  85  * @brief Iterates through the media files with optional @a filter in the given @a media @a album from the media database.
  86  * @details This function gets all media files associated with the given media album and
  87  * meeting desired filter option and calls registered callback function for
  88  * every retrieved media info. If NULL is passed to the @a filter, no filtering is applied.
  89  *
  90  * @param [in] album_id The ID of media album
  91  * @param [in] filter The handle to media filter
  92  * @param [in] callback The callback function to invoke
  93  * @param [in] user_data The user data to be passed to the callback function
  94  * @return 0 on success, otherwise a negative error value.
  95  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  96  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  97  * @pre This function requires opened connection to content service by media_content_connect().
  98  * @post This function invokes media_info_cb().
  99  * @see #media_info_cb
 100  * @see media_content_connect()
 101  * @see media_filter_create()
 102  */
 103 int media_album_foreach_media_from_db(int album_id, filter_h filter, media_info_cb callback, void *user_data);
 104
 105 /**
 106  * @brief Destroys album handle.
 107  * @details Function frees all resources related to album handle. This handle
 108  * no longer can be used to perform any operation. A new handle has to
 109  * be created before the next use.
 110  *
 111  * @param [in] album The handle to media album
 112  * @return 0 on success, otherwise a negative error value.
 113  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 114  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 115  * @pre Get copy of album handle by calling media_album_clone()
 116  * @see media_album_clone()
 117  */
 118 int media_album_destroy(media_album_h album);
 119
 120 /**
 121  * @brief Clones media album.
 122  * @details This function copies the media album handle from a source to
 123  * destination. There is no media_album_create() function. The media_album_h is created internally and available through
 124  * media album foreach function such as media_album_foreach_album_from_db(). To use this handle outside of these foreach functions,
 125  * use this function.
 126  *
 127  * @remark The destination handle must be released with media_album_destroy() by you.
 128  *
 129  * @param [in] src The source handle to media album
 130  * @param [out] dst A destination handle to media album
 131  * @return 0 on success, otherwise a negative error value.
 132  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 133  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 134  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 135  * @see media_album_destroy()
 136  * @see media_album_foreach_album_from_db()
 137  */
 138 int media_album_clone(media_album_h *dst, media_album_h src);
 139
 140 /**
 141  * @brief Gets a ID of the album.
 142  *
 143  * @param [in] album The handle to media album
 144  * @param [out] album_id A ID of media album
 145  * @return 0 on success, otherwise a negative error value.
 146  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 147  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 148  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 149  * @see media_album_foreach_album_from_db()
 150  *
 151  */
 152 int media_album_get_album_id(media_album_h album, int *album_id);
 153
 154 /**
 155  * @brief Gets a name of the album.
 156  *
 157  * @remarks @a album_name must be released with free() by you.
 158  *
 159  * @param [in] album The handle to media album
 160  * @param [out] album_name A name of media album handle
 161  * @return 0 on success, otherwise a negative error value.
 162  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 163  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 164  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 165  *
 166  */
 167 int media_album_get_name(media_album_h album, char **album_name);
 168
 169 /**
 170  * @brief Gets a name of the artist from album.
 171  *
 172  * @remarks @a artist must be released with free() by you.
 173  *
 174  * @param [in] album The handle to media album
 175  * @param [out] artist A name of media artist
 176  * @return 0 on success, otherwise a negative error value.
 177  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 178  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 179  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 180  *
 181  */
 182 int media_album_get_artist(media_album_h album, char **artist);
 183
 184 /**
 185  * @brief Gets a album art path from album.
 186  *
 187  * @remarks @a album_art must be released with free() by you.
 188  *
 189  * @param [in] album The handle to media album
 190  * @param [out] album_art A path of media album_art
 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  *
 196  */
 197 int media_album_get_album_art(media_album_h album, char **album_art);
 198
 199 /**
 200  * @brief Gets the media album from the media database.
 201  *
 202  * @details This function creates a new media album handle from the media database by the given album_id.
 203  * media album will be created, which is filled with album information.
 204  *
 205  * @remarks @a folder must be released with media_album_destroy() by you.
 206  *
 207  * @param[in] album_id The ID of media album
 208  * @param[out] album The album handle associated with the album ID
 209  * @return 0 on success, otherwise a negative error value.
 210  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 211  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 212  * @pre This function requires opened connection to content service by media_content_connect().
 213  * @see media_content_connect()
 214  * @see media_album_destroy()
 215  *
 216  */
 217 int media_album_get_album_from_db(int album_id, media_album_h *album);
 218
 219
 220 /**
 221  * @}
 222  */
 223
 224
 225 /**
 226 * @addtogroup CAPI_CONTENT_MEDIA_GROUP_MODULE
 227 * @{
 228 */
 229
 230  /**
 231  * @brief Gets the number of group for the passed @a filter from the media database.
 232  *
 233  * @param[in] filter The handle to media filter
 234  * @param [in] group The type of media group
 235  * @param[out] group_count The count of media group
 236  * @return 0 on success, otherwise a negative error value.
 237  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 238  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 239  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
 240  * @pre This function requires opened connection to content service by media_content_connect().
 241  * @see media_content_connect()
 242  *
 243  */
 244 int media_group_get_group_count_from_db(filter_h filter, media_group_e group, int *group_count);
 245
 246  /**
 247  * @brief Iterates through the media group with optional @a filter from the media database.
 248  * @details This function gets the names of media group meeting the given filter.
 249  * The callback function will be invoked for every retrieved media group.
 250  * If NULL is passed to the filter, no filtering is applied.
 251  *
 252  * @param [in] filter The handle to media filter
 253  * @param [in] group The type of media group
 254  * @param [in] callback The callback function to invoke
 255  * @param [in] user_data The user data to be passed to the callback function
 256  * @return 0 on success, otherwise a negative error value.
 257  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 258  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 259  * @pre This function requires opened connection to content service by media_content_connect().
 260  * @post This function invokes media_group_cb().
 261  * @see #media_group_cb
 262  * @see media_content_connect()
 263  * @see media_filter_create()
 264  */
 265 int media_group_foreach_group_from_db(filter_h filter, media_group_e group, media_group_cb callback, void *user_data);
 266
 267  /**
 268  * @brief Gets number of media info for the given media group present in the media database.
 269  *
 270  * @param [in] group_name The name of media group
 271  * @param [in] group The type of media group
 272  * @param [in] filter The handle to media filter
 273  * @param [out] media_count The count of media
 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  * @pre This function requires opened connection to content service by media_content_connect().
 278  * @see media_content_connect()
 279  */
 280 int media_group_get_media_count_from_db(const char *group_name, media_group_e group, filter_h filter, int *media_count);
 281
 282  /**
 283  * @brief Iterates through the media files with optional @a filter in the given @a group from the media database.
 284  * @details This function gets all media files associated with the given group and
 285  * meeting desired filter option and calls registered callback function for
 286  * every retrieved media info. If NULL is passed to the @a filter, no filtering is applied.
 287  *
 288  * @param [in] group_name The name of media group
 289  * @param [in] group The type of media group
 290  * @param [in] filter The handle to media filter
 291  * @param [in] callback The callback function to invoke
 292  * @param [in] user_data The user data to be passed to the callback function
 293  * @return 0 on success, otherwise a negative error value.
 294  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 295  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 296  * @pre This function requires opened connection to content service by media_content_connect().
 297  * @post This function invokes media_info_cb().
 298  * @see #media_info_cb
 299  * @see media_content_connect()
 300  * @see media_filter_create()
 301  */
 302 int media_group_foreach_media_from_db(const char *group_name, media_group_e group, filter_h filter, media_info_cb callback, void *user_data);
 303
 304  /**
 305   * @}
 306   */
 307
 308 #ifdef __cplusplus
 309  }
 310 #endif /* __cplusplus */
 311
 312 #endif /* __TIZEN_MEDIA_GROUP_H__ */