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  * @file media_group.h
  30  * @brief This file contains API related to handling different operations with album and other media data groups in DB.
  31  *        The following APIs are capable to get number of albums, media info in the given album from DB, \n
  32  *        to clone, destroy and get all albums and media files associated with the given media album from DB,  \n
  33  *        to get name, ID, artist, album art path from album; to get number of groups and their names, \n
  34  *        to get the number of media files and their content associated with the given group from DB.
  35  */
  36
  37 /**
  38  * @addtogroup CAPI_CONTENT_MEDIA_ALBUM_MODULE
  39  * @{
  40  */
  41
  42 /**
  43  * @brief Gets the number of the album for the passed @a filter from the media database.
  44  * @since_tizen 2.3
  45  *
  46  * @param[in]  filter      The media filter handle
  47  * @param[out] album_count The count of the media album
  48  *
  49  * @return @c 0 on success,
  50  *         otherwise a negative error value
  51  *
  52  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  53  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  54  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
  55  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
  56  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
  57  *
  58  * @pre This function requires opened connection to content service by media_content_connect().
  59  *
  60  * @see media_content_connect()
  61  */
  62 int media_album_get_album_count_from_db(filter_h filter, int *album_count);
  63
  64 /**
  65  * @brief Iterates through the media album with optional @a filter from the media database.
  66  * @details This function gets all media album handles meeting the given filter.
  67  *          The callback function will be invoked for every retrieved media album.
  68  *          If @c NULL is passed to the filter, no filtering is applied.
  69  *
  70  * @since_tizen 2.3
  71  *
  72  * @param[in] filter    The media filter handle
  73  * @param[in] callback  The callback function to be invoked
  74  * @param[in] user_data The user data to be passed to the callback function
  75  *
  76  * @return @c 0 on success,
  77  *         otherwise a negative error value
  78  *
  79  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  80  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  81  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
  82  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
  83  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
  84  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
  85  *
  86  * @pre  This function requires opened connection to content service by media_content_connect().
  87  * @post This function invokes media_album_cb().
  88  *
  89  * @see #media_album_cb
  90  * @see media_content_connect()
  91  * @see media_filter_create()
  92  */
  93 int media_album_foreach_album_from_db(filter_h filter, media_album_cb callback, void *user_data);
  94
  95 /**
  96  * @brief Gets the number of media info for the given album present in the media database.
  97  * @since_tizen 2.3
  98  *
  99  * @param[in]  album_id    The ID of the media album
 100  * @param[in]  filter      The media filter handle
 101  * @param[out] media_count The count of the album
 102  *
 103  * @return @c 0 on success,
 104  *         otherwise a negative error value
 105  *
 106  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 107  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 108  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 109  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 110  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 111
 112  *
 113  * @pre This function requires opened connection to content service by media_content_connect().
 114  *
 115  * @see media_content_connect()
 116  */
 117 int media_album_get_media_count_from_db (int album_id, filter_h filter, int *media_count);
 118
 119 /**
 120  * @brief Iterates through the media files with an optional @a filter in the given media album from the media database.
 121  * @details This function gets all media files associated with the given media album and
 122  *          meeting desired filter option and calls registered callback function for
 123  *          every retrieved media info. If @c NULL is passed to the @a filter, no filtering is applied.
 124  *
 125  * @since_tizen 2.3
 126  *
 127  * @param[in] album_id  The ID of the media album
 128  * @param[in] filter    The media filter handle
 129  * @param[in] callback  The callback function to be invoked
 130  * @param[in] user_data The user data to be passed to the callback function
 131  *
 132  * @return @c 0 on success,
 133  *         otherwise a negative error value
 134  *
 135  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 136  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 137  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 138  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 139  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 140  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 141  *
 142  * @pre  This function requires opened connection to content service by media_content_connect().
 143  * @post This function invokes media_info_cb().
 144  *
 145  * @see #media_info_cb
 146  * @see media_content_connect()
 147  * @see media_filter_create()
 148  */
 149 int media_album_foreach_media_from_db(int album_id, filter_h filter, media_info_cb callback, void *user_data);
 150
 151 /**
 152  * @brief Destroys the album handle.
 153  * @details This function frees all resources related to the album handle. This handle
 154  *          can no longer be used to perform any operation. A new handle has to
 155  *          be created before the next use.
 156  *
 157  * @since_tizen 2.3
 158  *
 159  * @param[in] album The media album handle
 160  *
 161  * @return @c 0 on success,
 162  *         otherwise a negative error value
 163  *
 164  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 165  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 166  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 167  *
 168  * @pre Get copy of album handle by calling media_album_clone().
 169  *
 170  * @see media_album_clone()
 171  */
 172 int media_album_destroy(media_album_h album);
 173
 174 /**
 175  * @brief Clones a media album.
 176  * @details This function copies the media album handle from a source to
 177  *          destination. There is no media_album_create() function. The media_album_h is created internally and available through
 178  *          media album foreach function such as media_album_foreach_album_from_db(). To use this handle outside of these foreach functions,
 179  *          use this function.
 180  *
 181  * @since_tizen 2.3
 182  *
 183  * @remarks You must release the destination handle using media_album_destroy().
 184  *
 185  * @param[in]  src  The source handle to the media album
 186  * @param[out] dst  The destination handle to the media album
 187  *
 188  * @return @c 0 on success,
 189  *         otherwise a negative error value
 190  *
 191  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 192  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 193  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 194  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 195  *
 196  * @see media_album_destroy()
 197  * @see media_album_foreach_album_from_db()
 198  */
 199 int media_album_clone(media_album_h *dst, media_album_h src);
 200
 201 /**
 202  * @brief Gets the ID of the album.
 203  * @since_tizen 2.3
 204  *
 205  * @param[in]  album    The media album handle
 206  * @param[out] album_id The media album 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_OUT_OF_MEMORY     Out of memory
 214  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 215  *
 216  * @see media_album_foreach_album_from_db()
 217  */
 218 int media_album_get_album_id(media_album_h album, int *album_id);
 219
 220 /**
 221  * @brief Gets the name of the album.
 222  * @since_tizen 2.3
 223  *
 224  * @remarks You must release @a album_name using free().
 225  *
 226  * @param[in]  album       The media album handle
 227  * @param[out] album_name  The name of the media album handle
 228  *
 229  * @return @c 0 on success,
 230  *         otherwise a negative error value
 231  *
 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  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 236  */
 237 int media_album_get_name(media_album_h album, char **album_name);
 238
 239 /**
 240  * @brief Gets the name of the artist from the given album.
 241  * @since_tizen 2.3
 242  *
 243  * @remarks You must release @a artist using free().
 244  *
 245  * @param[in]  album  The media album handle
 246  * @param[out] artist The name of the media artist
 247  *
 248  * @return @c 0 on success,
 249  *         otherwise a negative error value
 250  *
 251  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 252  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 253  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 254  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 255  */
 256 int media_album_get_artist(media_album_h album, char **artist);
 257
 258 /**
 259  * @brief Gets the album art path from the album.
 260  * @since_tizen 2.3
 261  *
 262  * @remarks You must release @a album_art using free().
 263  *
 264  * @param[in]  album     The media album handle
 265  * @param[out] album_art The path of the media album_art
 266  *
 267  * @return @c 0 on success,
 268  *         otherwise a negative error value
 269  *
 270  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 271  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 272  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 273  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 274  */
 275 int media_album_get_album_art(media_album_h album, char **album_art);
 276
 277 /**
 278  * @brief Gets the media album from the media database.
 279  *
 280  * @details This function creates a new media album handle from the media database by the given @a album_id.
 281  *          Media album will be created and will be filled with the album information.
 282  *
 283  * @since_tizen 2.3
 284  *
 285  * @remarks You must release @a folder using media_album_destroy().
 286  *
 287  * @param[in]  album_id The ID of the media album
 288  * @param[out] album    The album handle associated with the album ID
 289  *
 290  * @return @c 0 on success,
 291  *         otherwise a negative error value
 292  *
 293  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 294  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 295  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 296  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 297  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 298  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 299  *
 300  * @pre This function requires opened connection to content service by media_content_connect().
 301  *
 302  * @see media_content_connect()
 303  * @see media_album_destroy()
 304  */
 305 int media_album_get_album_from_db(int album_id, media_album_h *album);
 306
 307
 308 /**
 309  * @}
 310  */
 311
 312
 313 /**
 314 * @addtogroup CAPI_CONTENT_MEDIA_GROUP_MODULE
 315 * @{
 316 */
 317
 318  /**
 319  * @brief Gets the number of the group for the passed @a filter from the media database.
 320  * @since_tizen 2.3
 321  *
 322  * @param[in]  filter       The media filter handle
 323  * @param[in]  group        The type of the media group
 324  * @param[out] group_count  The count of the media group
 325  *
 326  * @return @c 0 on success,
 327  *         otherwise a negative error value
 328  *
 329  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 330  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 331  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 332  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 333  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 334  *
 335  * @pre This function requires opened connection to content service by media_content_connect().
 336  *
 337  * @see media_content_connect()
 338  */
 339 int media_group_get_group_count_from_db(filter_h filter, media_group_e group, int *group_count);
 340
 341  /**
 342  * @brief Iterates through the media group with an optional @a filter from the media database.
 343  * @details This function gets names of media group meeting the given filter.
 344  *          The callback function will be invoked for every retrieved media group.
 345  *          If @c NULL is passed to the filter, no filtering is applied.
 346  *
 347  * @since_tizen 2.3
 348  *
 349  * @param[in] filter    The media filter handle
 350  * @param[in] group     The type of the media group
 351  * @param[in] callback  The callback function to be invoked
 352  * @param[in] user_data The user data to be passed to the callback function
 353  *
 354  * @return @c 0 on success,
 355  *         otherwise a negative error value
 356  *
 357  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 358  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 359  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 360  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 361  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 362  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 363  *
 364  * @pre  This function requires opened connection to content service by media_content_connect().
 365  * @post This function invokes media_group_cb().
 366  *
 367  * @see #media_group_cb
 368  * @see media_content_connect()
 369  * @see media_filter_create()
 370  */
 371 int media_group_foreach_group_from_db(filter_h filter, media_group_e group, media_group_cb callback, void *user_data);
 372
 373  /**
 374  * @brief Gets the count of the media info for the given media group present in the media database.
 375  * @since_tizen 2.3
 376  *
 377  * @param[in]  group_name  The name of the media group
 378  * @param[in]  group       The type of the media group
 379  * @param[in]  filter      The media filter handle
 380  * @param[out] media_count The count of the media
 381  *
 382  * @return @c 0 on success,
 383  *         otherwise a negative error value
 384  *
 385  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 386  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 387  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 388  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 389  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 390  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 391  *
 392  * @pre This function requires opened connection to content service by media_content_connect().
 393  *
 394  * @see media_content_connect()
 395  */
 396 int media_group_get_media_count_from_db(const char *group_name, media_group_e group, filter_h filter, int *media_count);
 397
 398  /**
 399  * @brief Iterates through the media files with an optional @a filter in the given @a group from the media database.
 400  * @details This function gets all media files associated with the given group and
 401  *          meeting desired filter option and calls registered callback function for
 402  *          every retrieved media info. If @c NULL is passed to the @a filter, no filtering is applied.
 403  *
 404  * @since_tizen 2.3
 405  *
 406  * @param[in] group_name The name of the media group
 407  * @param[in] group      The type of the media group
 408  * @param[in] filter     The media filter handle
 409  * @param[in] callback   The callback function to be invoked
 410  * @param[in] user_data  The user data to be passed to the callback function
 411  *
 412  * @return @c 0 on success,
 413  *         otherwise a negative error value
 414  *
 415  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 416  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 417  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 418  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 419  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 420  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 421  *
 422  * @pre  This function requires opened connection to content service by media_content_connect().
 423  * @post This function invokes media_info_cb().
 424  *
 425  * @see media_info_cb()
 426  * @see media_content_connect()
 427  * @see media_filter_create()
 428  */
 429 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);
 430
 431  /**
 432   * @}
 433   */
 434
 435 #ifdef __cplusplus
 436  }
 437 #endif /* __cplusplus */
 438
 439 #endif /* __TIZEN_MEDIA_GROUP_H__ */