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