include/media_tag.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
  18
  19 #ifndef __TIZEN_MEDIA_TAG_H__
  20 #define __TIZEN_MEDIA_TAG_H__
  21
  22 #include <media_content_type.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif /* __cplusplus */
  27
  28 /**
  29  * @file media_tag.h
  30  * @brief This file contains the media tag API and functions related with handling tags. \n
  31  *        Functions include operations to get the number and content of the tag, the number of media files  \n
  32  *        and all media items in the tag, to clone, destroy, insert and delete tag from DB,  \n
  33  *        to handle with name, ID, and media info of the tag.
  34  */
  35
  36
  37 /**
  38  * @addtogroup CAPI_CONTENT_MEDIA_TAG_MODULE
  39  * @{
  40  */
  41
  42 /**
  43  * @brief Inserts a new tag in the media database.
  44  * @since_tizen 2.3
  45  *
  46  * @privlevel public
  47  * @privilege %http://tizen.org/privilege/content.write
  48  *
  49  * @remarks The created tag handle must be released using media_tag_destroy().
  50  *
  51  * @param[in]  tag_name The tag name to be inserted
  52  * @param[out] tag      The created handle to the media tag
  53  *
  54  * @return @c 0 on success,
  55  *         otherwise a negative error value
  56  *
  57  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  58  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  59  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
  60  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
  61  *
  62  * @pre This function requires opened connection to content service by media_content_connect().
  63  *
  64  * @see media_content_connect()
  65  * @see media_tag_delete_from_db()
  66  * @see media_tag_destroy()
  67  */
  68 int media_tag_insert_to_db(const char *tag_name, media_tag_h *tag);
  69
  70 /**
  71  * @brief Deletes a given tag from the media database.
  72  * @since_tizen 2.3
  73  *
  74  * @privlevel public
  75  * @privilege %http://tizen.org/privilege/content.write
  76  *
  77  * @param[in] tag_id The ID of media tag
  78  *
  79  * @return @c 0 on success,
  80  *         otherwise a negative error value
  81  *
  82  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  83  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  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  *
  88  * @see media_content_connect()
  89  * @see media_tag_insert_to_db()
  90  */
  91 int media_tag_delete_from_db(int tag_id);
  92
  93 /**
  94  * @brief Gets the count of the tag for the passed @a filter from the media database.
  95  * @since_tizen 2.3
  96  *
  97  * @param[in]  filter    The handle to the filter
  98  * @param[out] tag_count The count of the media tag
  99  *
 100  * @return @c 0 on success,
 101  *         otherwise a negative error value
 102  *
 103  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 104  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 105  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB operation failed
 106  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 107  *
 108  * @pre This function requires opened connection to content service by media_content_connect().
 109  *
 110  * @see media_content_connect()
 111  */
 112 int media_tag_get_tag_count_from_db(filter_h filter, int *tag_count);
 113
 114 /**
 115  * @brief Iterates through tags from the media database.
 116  * @details This function gets all tags meeting a desired @a filter
 117  *          and calls a registered callback function for every retrieved tag.
 118  *          If @c NULL is passed to the @a filter, no filtering is applied.
 119  *
 120  * @since_tizen 2.3
 121  *
 122  * @param[in] filter    The tag filter handle
 123  * @param[in] callback  The callback function to be invoked
 124  * @param[in] user_data The user data to be passed to the callback function
 125  *
 126  * @return @c 0 on success,
 127  *         otherwise a negative error value
 128  *
 129  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 130  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 131  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 132  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 133  *
 134  * @pre  This function requires opened connection to content service by media_content_connect().
 135  * @post This function invokes media_tag_cb().
 136  *
 137  * @see media_content_connect()
 138  * @see #media_tag_cb
 139  * @see media_filter_create()
 140  */
 141 int media_tag_foreach_tag_from_db (filter_h filter, media_tag_cb callback, void *user_data);
 142
 143 /**
 144  * @brief Gets the number of media files for the passed @a filter in the given @a tag from the media database.
 145  * @since_tizen 2.3
 146  *
 147  * @param[in]  tag_id      The ID of the media tag
 148  * @param[in]  filter      The handle to the media filter
 149  * @param[out] media_count The count of media items
 150  *
 151  * @return @c 0 on success,
 152  *         otherwise a negative error value
 153  *
 154  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 155  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 156  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED         DB operation failed
 157  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 158  *
 159  * @pre This function requires opened connection to content service by media_content_connect().
 160  *
 161  * @see media_content_connect()
 162  */
 163 int media_tag_get_media_count_from_db (int tag_id, filter_h filter, int *media_count);
 164
 165 /**
 166  * @brief Iterates through media items for a given tag from the media database.
 167  * @details This function gets all media items associated with a given tag and
 168  *          meeting a desired @a filter and calls a registered callback function for
 169  *          every retrieved media item. If @c NULL is passed to the @a filter, no filtering is applied.
 170  *
 171  * @since_tizen 2.3
 172  *
 173  * @param[in] tag_id    The ID of the media tag
 174  * @param[in] filter    The handle to the media filter
 175  * @param[in] callback  The callback function to be invoked
 176  * @param[in] user_data The user data to be passed to the callback function
 177  *
 178  * @return @c 0 on success,
 179  *         otherwise a negative error value
 180  *
 181  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 182  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 183  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 184  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 185  *
 186  * @pre  This function requires opened connection to content service by media_content_connect().
 187  * @post This function invokes media_info_cb().
 188  *
 189  * @see media_content_connect()
 190  * @see media_info_cb()
 191  * @see media_filter_create()
 192  */
 193 int media_tag_foreach_media_from_db(int tag_id, filter_h filter, media_info_cb callback, void *user_data);
 194
 195 /**
 196  * @brief Clones the media tag.
 197  * @details This function copies the media tag handle from a source to destination.
 198  *          There is no media_tag_create() function. The media_tag_h is created internally and available through media tag foreach function
 199  *          such as media_tag_foreach_tag_from_db().
 200  *          To use this handle outside of these foreach functions, use this function.
 201  *
 202  * @since_tizen 2.3
 203  *
 204  * @remarks You must release the destination handle using media_tag_destroy().
 205  *
 206  * @param[out] dst The destination handle to the media tag
 207  * @param[in]  src The source handle to the media tag
 208  *
 209  * @return @c 0 on success,
 210  *         otherwise a negative error value
 211  *
 212  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 213  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 214  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 215  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 216  *
 217  * @see media_tag_destroy()
 218  */
 219 int media_tag_clone(media_tag_h *dst, media_tag_h src);
 220
 221 /**
 222  * @brief Destroys the media tag.
 223  * @details This function frees all resources related to the tag handle. The tag handle can no longer
 224  *          be used for any operation. A new tag handle has to be created before next usage.
 225  *
 226  * @since_tizen 2.3
 227  *
 228  * @param[in] tag The media tag handle
 229  *
 230  * @return @c 0 on success,
 231  *         otherwise a negative error value
 232  *
 233  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 234  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 235  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 236  *
 237  * @pre A copy of the media tag handle created by calling media_tag_clone() or media_tag_insert_to_db().
 238  *
 239  * @see media_tag_clone()
 240  * @see media_tag_insert_to_db()
 241  */
 242 int media_tag_destroy(media_tag_h tag);
 243
 244 /**
 245  * @brief Gets the media tag ID.
 246  * @since_tizen 2.3
 247  *
 248  * @param[in]  tag     The media tag handle
 249  * @param[out] tag_id  The ID of the media tag
 250  *
 251  * @return @c 0 on success,
 252  *         otherwise a negative error value
 253  *
 254  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 255  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 256  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 257  */
 258 int media_tag_get_tag_id(media_tag_h tag, int *tag_id);
 259
 260 /**
 261  * @brief Gets the tag name.
 262  * @since_tizen 2.3
 263  *
 264  * @remarks You must release @a tag_name using free().
 265  *
 266  * @param[in]  tag      The media tag handle
 267  * @param[out] tag_name The name of the tag
 268  *
 269  * @return @c 0 on success,
 270  *         otherwise a negative error value
 271  *
 272  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 273  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 274  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 275  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 276  */
 277 int media_tag_get_name(media_tag_h tag, char **tag_name);
 278
 279 /**
 280  * @brief Gets the media tag from the media database.
 281  *
 282  * @details This function creates a new media tag handle from the media database by the given @a tag_id.
 283  *          Media tag will be created and will be filled with tag information.
 284  *
 285  * @since_tizen 2.3
 286  *
 287  * @remarks You must release @a folder using media_tag_destroy().
 288  *
 289  * @param[in]  tag_id The ID of the media tag
 290  * @param[out] tag    The media tag handle associated with the tag ID
 291  *
 292  * @return @c 0 on success,
 293  *         otherwise a negative error value
 294  *
 295  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 296  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 297  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 298  *
 299  * @pre This function requires opened connection to content service by media_content_connect().
 300  *
 301  * @see media_content_connect()
 302  * @see media_tag_destroy()
 303  */
 304 int media_tag_get_tag_from_db(int tag_id, media_tag_h *tag);
 305
 306 /**
 307  * @brief Adds a new media info to the tag.
 308  * @since_tizen 2.3
 309  *
 310  * @param[in] tag      The media tag handle
 311  * @param[in] media_id The ID to the media info which is added
 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_OUT_OF_MEMORY     Out of memory
 319  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 320  *
 321  * @pre  This function requires opened connection to content service by media_content_connect().
 322  * @post media_tag_update_to_db()
 323  *
 324  * @see media_content_connect()
 325  * @see media_tag_remove_media()
 326  */
 327 int media_tag_add_media(media_tag_h tag, const char *media_id);
 328
 329 /**
 330  * @brief Removes the media info from the given tag.
 331  * @since_tizen 2.3
 332  *
 333  * @param[in] tag      The media tag handle
 334  * @param[in] media_id The ID to the media info which is removed
 335  *
 336  * @return @c 0 on success,
 337  *         otherwise a negative error value
 338  *
 339  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 340  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 341  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 342  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 343  *
 344  * @pre  This function requires opened connection to content service by media_content_connect().
 345  * @post media_tag_update_to_db()
 346  *
 347  * @see media_content_connect()
 348  * @see media_tag_add_media()
 349  */
 350 int media_tag_remove_media(media_tag_h tag, const char *media_id);
 351
 352 /**
 353  * @brief Sets the name of the tag.
 354  * @since_tizen 2.3
 355  *
 356  * @param[in] tag      The media tag handle
 357  * @param[in] tag_name The name of the media tag
 358  *
 359  * @return @c 0 on success,
 360  *         otherwise a negative error value
 361  *
 362  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 363  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 364  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 365  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
 366  *
 367  * @post media_tag_update_to_db()
 368  */
 369 int media_tag_set_name(media_tag_h tag, char *tag_name);
 370
 371 /**
 372  * @brief Updates the media tag to the media database.
 373  *
 374  * @details The function updates the given media tag in the media database. The function should be called after any change in tag attributes, to be updated to the media
 375  *          database. For example, after using media_tag_set_name() for setting the name of the tag, the media_tag_update_to_db() function should be called so as to update
 376  *          the given tag attributes in the media database.
 377  *
 378  * @since_tizen 2.3
 379  *
 380  * @privlevel public
 381  * @privilege %http://tizen.org/privilege/content.write
 382  *
 383  * @param[in] tag The media tag handle
 384  *
 385  * @return @c 0 on success,
 386  *         otherwise a negative error value
 387  *
 388  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 389  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 390  *
 391  * @pre This function requires opened connection to content service by media_content_connect().
 392  *
 393  * @see media_content_connect()
 394  * @see media_tag_destroy()
 395  * @see media_tag_add_media()
 396  * @see media_tag_remove_media()
 397  * @see media_tag_set_name()
 398  */
 399 int media_tag_update_to_db(media_tag_h tag);
 400
 401 /**
 402  * @}
 403  */
 404
 405 #ifdef __cplusplus
 406 }
 407 #endif /* __cplusplus */
 408
 409 #endif /* __TIZEN_MEDIA_TAG_H__ */