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 /**
  30  * @addtogroup CAPI_CONTENT_MEDIA_TAG_MODULE
  31  * @{
  32  */
  33
  34 /**
  35  * @brief Inserts a new tag in the media database.
  36  *
  37  * @remark The created tag handle must be released with media_tag_destroy() by you.
  38  *
  39  * @param[in] tag_name The tag name to be inserted
  40  * @param[out] tag A created handle to media tag
  41  * @return 0 on success, otherwise a negative error value.
  42  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  43  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  44  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
  45  * @pre This function requires opened connection to content service by media_content_connect().
  46  * @see media_content_connect()
  47  * @see media_tag_delete_from_db()
  48  * @see media_tag_destroy()
  49  *
  50  */
  51 int media_tag_insert_to_db(const char *tag_name, media_tag_h *tag);
  52
  53 /**
  54  * @brief Deletes a given tag from the media database.
  55  *
  56  * @param[in] tag The handle to media tag
  57  * @return 0 on success, otherwise a negative error value.
  58  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  59  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  60  * @pre This function requires opened connection to content service by media_content_connect().
  61  * @see media_content_connect()
  62  * @see media_tag_insert_to_db()
  63  *
  64  */
  65 int media_tag_delete_from_db(int tag_id);
  66
  67 /**
  68  * @brief Gets the number of tag for the passed @a filter from the media database.
  69  *
  70  * @param[in] filter The handle to filter
  71  * @param[out] tag_count The count of media tag
  72  * @return 0 on success, otherwise a negative error value.
  73  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  74  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  75  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
  76  * @pre This function requires opened connection to content service by media_content_connect().
  77  * @see media_content_connect()
  78  *
  79  */
  80 int media_tag_get_tag_count_from_db(filter_h filter, int *tag_count);
  81
  82 /**
  83  * @brief Iterates through tags from the media database.
  84  * @details This function gets all tags meeting a desired @a filter
  85  * and calls a registered callback function for every retrieved tag. If NULL is passed to the @a filter, no filtering is applied.
  86  *
  87  * @param[in] filter The handle to tag filter
  88  * @param[in] callback The callback function to invoke
  89  * @param[in] user_data The user data to be passed to the callback function
  90  * @return 0 on success, otherwise a negative error value.
  91  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  92  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
  93  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  94  * @pre This function requires opened connection to content service by media_content_connect().
  95  * @post This function invokes media_tag_cb().
  96  * @see media_content_connect()
  97  * @see #media_tag_cb
  98  * @see media_filter_create()
  99  *
 100  */
 101 int media_tag_foreach_tag_from_db (filter_h filter, media_tag_cb callback, void *user_data);
 102
 103 /**
 104  * @brief Gets the number of media files for the passed @a filter in the given @a tag from the media database.
 105  *
 106  * @param[in] tag_id The ID of media tag
 107  * @param[in] filter The handle to media filter
 108  * @param[out] media_count The count of media items
 109  * @return 0 on success, otherwise a negative error value.
 110  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 111  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 112  * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
 113  * @pre This function requires opened connection to content service by media_content_connect().
 114  * @see media_content_connect()
 115  *
 116  */
 117 int media_tag_get_media_count_from_db (int tag_id, filter_h filter, int *media_count);
 118
 119 /**
 120  * @brief Iterates through media items for a given tag from the media database.
 121  * @details This function gets all media items associated with a given tag and
 122  * meeting a desired @a filter and calls a registered callback function for
 123  * every retrieved media item. If NULL is passed to the @a filter, no filtering is applied.
 124  *
 125  * @param[in] tag_id The ID of media tag
 126  * @param[in] filter The handle to media filter
 127  * @param[in] callback The callback function to invoke
 128  * @param[in] user_data The user data to be passed to the callback function
 129  * @return 0 on success, otherwise a negative error value.
 130  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 131  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 132  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 133  * @pre This function requires opened connection to content service by media_content_connect().
 134  * @post This function invokes media_info_cb().
 135  * @see media_content_connect()
 136  * @see #media_info_cb
 137  * @see media_filter_create()
 138  */
 139 int media_tag_foreach_media_from_db(int tag_id, filter_h filter, media_info_cb callback, void *user_data);
 140
 141 /**
 142  * @brief Clones the media tag.
 143  * @details This function copies the media tag handle from a source to destination.
 144  * There is no media_tag_create() function. The media_tag_h is created internally and available through media tag foreach function
 145  * such as media_tag_foreach_tag_from_db().
 146  * To use this handle outside of these foreach functions, use this function.
 147  * @remark The destination handle must be released with media_tag_destroy() by you.
 148  *
 149  * @param[out] dst A destination handle to media tag
 150  * @param[in] src The source handle to media tag
 151  * @return 0 on success, otherwise a negative error value.
 152  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 153  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 154  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 155  * @see media_tag_destroy()
 156  *
 157  */
 158 int media_tag_clone(media_tag_h *dst, media_tag_h src);
 159
 160 /**
 161  * @brief Destroys the media tag.
 162  * @details This function frees all resources related to the tag handle. The tag handle can no longer
 163  * be used for any operation. A new tag handle has to be created before next usage.
 164  *
 165  * @param[in] tag The media tag handle
 166  * @return 0 on success, otherwise a negative error value.
 167  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 168  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 169  * @pre A copy of the media tag handle created by calling media_tag_clone() or media_tag_insert_to_db()
 170  * @see media_tag_clone()
 171  * @see media_tag_insert_to_db()
 172  *
 173  */
 174 int media_tag_destroy(media_tag_h tag);
 175
 176 /**
 177  * @brief Gets media tag's ID.
 178  *
 179  *
 180  * @param [in] tag The handle to media tag
 181  * @param [out] tag_id The ID of media tag
 182  * @return 0 on success, otherwise a negative error value.
 183  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 184  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 185  */
 186 int media_tag_get_tag_id(media_tag_h tag, int *tag_id);
 187
 188 /**
 189  * @brief Gets the tag name.
 190  *
 191  * @remarks @a tag_name must be released with free() by you.
 192  *
 193  * @param[in] tag The handle to media tag
 194  * @param[out] tag_name The name of the tag
 195  * @return 0 on success, otherwise a negative error value.
 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  *
 200  */
 201 int media_tag_get_name(media_tag_h tag, char **tag_name);
 202
 203 /**
 204  * @brief Gets the media tag from the media database.
 205  *
 206  * @details This function creates a new media tag handle from the media database by the given tag_id.
 207  * media tag will be created, which is filled with tag information.
 208  *
 209  * @remarks @a folder must be released with media_tag_destroy() by you.
 210  *
 211  * @param[in] tag_id The ID of media tag
 212  * @param[out] tag The media tag handle associated with the tag ID
 213  * @return 0 on success, otherwise a negative error value.
 214  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 215  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 216  * @pre This function requires opened connection to content service by media_content_connect().
 217  * @see media_content_connect()
 218  * @see media_tag_destroy()
 219  *
 220  */
 221 int media_tag_get_tag_from_db(int tag_id, media_tag_h *tag);
 222
 223 /**
 224  * @brief Adds a new media info to the tag.
 225  *
 226  * @param[in] tag The handle to media tag
 227  * @param[in] media_id The ID to media info which is added
 228  * @return 0 on success, otherwise a negative error value.
 229  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 230  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 231  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 232  * @pre This function requires opened connection to content service by media_content_connect().
 233  * @post media_tag_update_to_db()
 234  * @see media_content_connect()
 235  * @see media_tag_remove_media()
 236  *
 237  */
 238 int media_tag_add_media(media_tag_h tag, const char *media_id);
 239
 240 /**
 241  * @brief Removes the media info from the given tag.
 242  *
 243  * @param[in] tag The handle to media tag
 244  * @param[in] media_id The ID to media info which is removed
 245  * @return 0 on success, otherwise a negative error value.
 246  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 247  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 248  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 249  * @pre This function requires opened connection to content service by media_content_connect().
 250  * @post media_tag_update_to_db()
 251  * @see media_content_connect()
 252  * @see media_tag_add_media()
 253  *
 254  */
 255 int media_tag_remove_media(media_tag_h tag, const char *media_id);
 256
 257 /**
 258  * @brief Sets the tag name.
 259  *
 260  * @param[in] tag The handle to media tag
 261  * @param[in] tag_name The name of the media tag
 262  * @return 0 on success, otherwise a negative error value.
 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  * @post media_tag_update_to_db()
 267  *
 268  */
 269 int media_tag_set_name(media_tag_h tag, char *tag_name);
 270
 271 /**
 272  * @brief Updates the media tag to the media database.
 273  *
 274  * @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
 275  * database. For example, after using media_tag_set_name() for setting the name of the tag, media_tag_update_to_db() function should be called so as to update
 276  * the given tag attibutes in the media database.
 277  *
 278  * @param[in] tag The handle to media tag
 279  * @return 0 on success, otherwise a negative error value.
 280  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 281  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 282  * @pre This function requires opened connection to content service by media_content_connect().
 283  * @see media_content_connect()
 284  * @see media_tag_destroy()
 285  * @see media_tag_add_media()
 286  * @see media_tag_remove_media()
 287  * @see media_tag_set_name()
 288  *
 289  */
 290 int media_tag_update_to_db(media_tag_h tag);
 291
 292 /**
 293  * @}
 294  */
 295
 296 #ifdef __cplusplus
 297 }
 298 #endif /* __cplusplus */
 299
 300 #endif /* __TIZEN_MEDIA_TAG_H__ */