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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 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 @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 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  *
 167  * @pre Get copy of album handle by calling media_album_clone().
 168  *
 169  * @see media_album_clone()
 170  */
 171 int media_album_destroy(media_album_h album);
 172
 173 /**
 174  * @brief Clones a media album.
 175  * @details This function copies the media album handle from a source to
 176  *          destination. There is no media_album_create() function. The media_album_h is created internally and available through
 177  *          media album foreach function such as media_album_foreach_album_from_db(). To use this handle outside of these foreach functions,
 178  *          use this function.
 179  *
 180  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 181  *
 182  * @remarks You must release the destination handle using media_album_destroy().
 183  *
 184  * @param[in]  src  The source handle to the media album
 185  * @param[out] dst  The destination handle to the media album
 186  *
 187  * @return @c 0 on success,
 188  *         otherwise a negative error value
 189  *
 190  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 191  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 192  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 193  *
 194  * @see media_album_destroy()
 195  * @see media_album_foreach_album_from_db()
 196  */
 197 int media_album_clone(media_album_h *dst, media_album_h src);
 198
 199 /**
 200  * @brief Gets the ID of the album.
 201  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 202  *
 203  * @param[in]  album    The media album handle
 204  * @param[out] album_id The media album ID
 205  *
 206  * @return @c 0 on success,
 207  *         otherwise a negative error value
 208  *
 209  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 210  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 211  *
 212  * @see media_album_foreach_album_from_db()
 213  */
 214 int media_album_get_album_id(media_album_h album, int *album_id);
 215
 216 /**
 217  * @brief Gets the name of the album.
 218  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 219  *
 220  * @remarks You must release @a album_name using free().
 221  *
 222  * @param[in]  album       The media album handle
 223  * @param[out] album_name  The name of the media album handle
 224  *
 225  * @return @c 0 on success,
 226  *         otherwise a negative error value
 227  *
 228  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 229  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 230  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 231  */
 232 int media_album_get_name(media_album_h album, char **album_name);
 233
 234 /**
 235  * @brief Gets the name of the artist from the given album.
 236  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 237  *
 238  * @remarks You must release @a artist using free().
 239  *
 240  * @param[in]  album  The media album handle
 241  * @param[out] artist The name of the media artist
 242  *
 243  * @return @c 0 on success,
 244  *         otherwise a negative error value
 245  *
 246  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 247  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 248  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 249  */
 250 int media_album_get_artist(media_album_h album, char **artist);
 251
 252 /**
 253  * @brief Gets the album art path from the album.
 254  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 255  *
 256  * @remarks You must release @a album_art using free().
 257  *
 258  * @param[in]  album     The media album handle
 259  * @param[out] album_art The path of the media album_art
 260  *
 261  * @return @c 0 on success,
 262  *         otherwise a negative error value
 263  *
 264  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 265  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 266  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 267  */
 268 int media_album_get_album_art(media_album_h album, char **album_art);
 269
 270 /**
 271  * @brief Gets the media album from the media database.
 272  *
 273  * @details This function creates a new media album handle from the media database by the given @a album_id.
 274  *          Media album will be created and will be filled with the album information.
 275  *
 276  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 277  *
 278  * @remarks You must release @a folder using media_album_destroy().
 279  *
 280  * @param[in]  album_id The ID of the media album
 281  * @param[out] album    The album handle associated with the album ID
 282  *
 283  * @return @c 0 on success,
 284  *         otherwise a negative error value
 285  *
 286  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 287  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 288  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 289  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 290  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 291  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 292  *
 293  * @pre This function requires opened connection to content service by media_content_connect().
 294  *
 295  * @see media_content_connect()
 296  * @see media_album_destroy()
 297  */
 298 int media_album_get_album_from_db(int album_id, media_album_h *album);
 299
 300
 301 /**
 302  * @}
 303  */
 304
 305
 306 /**
 307 * @addtogroup CAPI_CONTENT_MEDIA_GROUP_MODULE
 308 * @{
 309 */
 310
 311  /**
 312  * @brief Gets the number of the group for the passed @a filter from the media database.
 313  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 314  *
 315  * @param[in]  filter       The media filter handle
 316  * @param[in]  group        The type of the media group
 317  * @param[out] group_count  The count of the media group
 318  *
 319  * @return @c 0 on success,
 320  *         otherwise a negative error value
 321  *
 322  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 323  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 324  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 325  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 326  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 327  *
 328  * @pre This function requires opened connection to content service by media_content_connect().
 329  *
 330  * @see media_content_connect()
 331  */
 332 int media_group_get_group_count_from_db(filter_h filter, media_group_e group, int *group_count);
 333
 334  /**
 335  * @brief Iterates through the media group with an optional @a filter from the media database.
 336  * @details This function gets names of media group meeting the given filter.
 337  *          The callback function will be invoked for every retrieved media group.
 338  *          If @c NULL is passed to the filter, no filtering is applied.
 339  *
 340  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 341  *
 342  * @param[in] filter    The media filter handle
 343  * @param[in] group     The type of the media group
 344  * @param[in] callback  The callback function to be invoked
 345  * @param[in] user_data The user data to be passed to the callback function
 346  *
 347  * @return @c 0 on success,
 348  *         otherwise a negative error value
 349  *
 350  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 351  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 352  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 353  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 354  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 355  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 356  *
 357  * @pre  This function requires opened connection to content service by media_content_connect().
 358  * @post This function invokes media_group_cb().
 359  *
 360  * @see #media_group_cb
 361  * @see media_content_connect()
 362  * @see media_filter_create()
 363  */
 364 int media_group_foreach_group_from_db(filter_h filter, media_group_e group, media_group_cb callback, void *user_data);
 365
 366  /**
 367  * @brief Gets the count of the media info for the given media group present in the media database.
 368  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 369  *
 370  * @param[in]  group_name  The name of the media group
 371  * @param[in]  group       The type of the media group
 372  * @param[in]  filter      The media filter handle
 373  * @param[out] media_count The count of the media
 374  *
 375  * @return @c 0 on success,
 376  *         otherwise a negative error value
 377  *
 378  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 379  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 380  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 381  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 382  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 383  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 384  *
 385  * @pre This function requires opened connection to content service by media_content_connect().
 386  *
 387  * @see media_content_connect()
 388  */
 389 int media_group_get_media_count_from_db(const char *group_name, media_group_e group, filter_h filter, int *media_count);
 390
 391  /**
 392  * @brief Iterates through the media files with an optional @a filter in the given @a group from the media database.
 393  * @details This function gets all media files associated with the given group and
 394  *          meeting desired filter option and calls registered callback function for
 395  *          every retrieved media info. If @c NULL is passed to the @a filter, no filtering is applied.
 396  *
 397  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 398  *
 399  * @param[in] group_name The name of the media group
 400  * @param[in] group      The type of the media group
 401  * @param[in] filter     The media filter handle
 402  * @param[in] callback   The callback function to be invoked
 403  * @param[in] user_data  The user data to be passed to the callback function
 404  *
 405  * @return @c 0 on success,
 406  *         otherwise a negative error value
 407  *
 408  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 409  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 410  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 411  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB Operation failed
 412  * @retval #MEDIA_CONTENT_ERROR_DB_BUSY           DB Operation busy
 413  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 414  *
 415  * @pre  This function requires opened connection to content service by media_content_connect().
 416  * @post This function invokes media_info_cb().
 417  *
 418  * @see media_info_cb()
 419  * @see media_content_connect()
 420  * @see media_filter_create()
 421  */
 422 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);
 423
 424  /**
 425   * @}
 426   */
 427
 428 #ifdef __cplusplus
 429 }
 430 #endif /* __cplusplus */
 431
 432 #endif /* __TIZEN_MEDIA_GROUP_H__ */