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