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