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