2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
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
8 * http://www.apache.org/licenses/LICENSE-2.0
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.
19 #ifndef __TIZEN_CONTENT_MEDIA_TAG_H__
20 #define __TIZEN_CONTENT_MEDIA_TAG_H__
22 #include <media_content_type.h>
26 #endif /* __cplusplus */
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.
38 * @addtogroup CAPI_CONTENT_MEDIA_TAG_MODULE
43 * @brief Inserts a new tag in the media database.
44 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
47 * @privilege %http://tizen.org/privilege/content.write
49 * @remarks The @a tag should be released using media_tag_destroy().
51 * @param[in] tag_name The tag name to be inserted
52 * @param[out] tag The handle to the media tag
54 * @return @c 0 on success,
55 * otherwise a negative error value
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
66 * @pre This function requires opened connection to content service by media_content_connect().
68 * @see media_content_connect()
69 * @see media_tag_delete_from_db()
70 * @see media_tag_destroy()
72 int media_tag_insert_to_db(const char *tag_name, media_tag_h *tag);
75 * @brief Deletes a given tag from the media database.
76 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
79 * @privilege %http://tizen.org/privilege/content.write
81 * @param[in] tag_id The ID of the media tag
83 * @return @c 0 on success,
84 * otherwise a negative error value
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
94 * @pre This function requires opened connection to content service by media_content_connect().
96 * @see media_content_connect()
97 * @see media_tag_insert_to_db()
99 int media_tag_delete_from_db(int tag_id);
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
105 * @param[in] filter The handle to the media filter
106 * @param[out] tag_count The count of the media tag
108 * @return @c 0 on success,
109 * otherwise a negative error value
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
116 * @pre This function requires opened connection to content service by media_content_connect().
118 * @see media_content_connect()
120 int media_tag_get_tag_count_from_db(filter_h filter, int *tag_count);
123 * @brief Iterates through tags from the media database.
124 * @details This function gets all tags meeting a desired @a filter
125 * and calls a registered callback function for every retrieved tag.
126 * If @c NULL is passed to the @a filter, no filtering is applied.
128 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
130 * @param[in] filter The handle to the media filter
131 * @param[in] callback The callback function to be invoked
132 * @param[in] user_data The user data to be passed to the callback function
134 * @return @c 0 on success,
135 * otherwise a negative error value
137 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
138 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
139 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
140 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
141 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
143 * @pre This function requires opened connection to content service by media_content_connect().
144 * @post This function invokes media_tag_cb().
146 * @see media_content_connect()
148 * @see media_filter_create()
150 int media_tag_foreach_tag_from_db(filter_h filter, media_tag_cb callback, void *user_data);
153 * @brief Gets the number of media files for the passed @a filter in the given @a tag_id from the media database.
154 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
156 * @param[in] tag_id The ID of the media tag
157 * @param[in] filter The handle to the media filter
158 * @param[out] media_count The count of media items
160 * @return @c 0 on success,
161 * otherwise a negative error value
163 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
164 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
165 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
166 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
168 * @pre This function requires opened connection to content service by media_content_connect().
170 * @see media_content_connect()
172 int media_tag_get_media_count_from_db(int tag_id, filter_h filter, int *media_count);
175 * @brief Iterates through media items for a given tag from the media database.
176 * @details This function gets all media items associated with a given tag and
177 * meeting a desired @a filter and calls a registered callback function for
178 * every retrieved media item. If @c NULL is passed to the @a filter, no filtering is applied.
180 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
182 * @param[in] tag_id The ID of the media tag
183 * @param[in] filter The handle to the media filter
184 * @param[in] callback The callback function to be invoked
185 * @param[in] user_data The user data to be passed to the callback function
187 * @return @c 0 on success,
188 * otherwise a negative error value
190 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
191 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
192 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
193 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
194 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
196 * @pre This function requires opened connection to content service by media_content_connect().
197 * @post This function invokes media_info_cb().
199 * @see media_content_connect()
200 * @see media_info_cb()
201 * @see media_filter_create()
203 int media_tag_foreach_media_from_db(int tag_id, filter_h filter, media_info_cb callback, void *user_data);
206 * @brief Clones the media tag.
207 * @details This function copies the media tag handle from a source to destination.
208 * There is no media_tag_create() function. The media_tag_h is created internally and available through media tag foreach function
209 * such as media_tag_foreach_tag_from_db().
210 * To use this handle outside of these foreach functions, use this function.
212 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
214 * @remarks The @a dst should be released using media_tag_destroy().
216 * @param[out] dst The destination handle to the media tag
217 * @param[in] src The source handle to the media tag
219 * @return @c 0 on success,
220 * otherwise a negative error value
222 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
223 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
224 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
226 * @see media_tag_destroy()
228 int media_tag_clone(media_tag_h *dst, media_tag_h src);
231 * @brief Destroys the media tag.
232 * @details This function frees all resources related to the tag handle. The tag handle can no longer
233 * be used for any operations. A new tag handle has to be created before next usage.
235 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
237 * @param[in] tag The handle to the media tag
239 * @return @c 0 on success,
240 * otherwise a negative error value
242 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
243 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
245 * @pre A copy of the media tag handle created by calling media_tag_clone() or media_tag_insert_to_db().
247 * @see media_tag_clone()
248 * @see media_tag_insert_to_db()
250 int media_tag_destroy(media_tag_h tag);
253 * @brief Gets the media tag ID.
254 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
256 * @param[in] tag The handle to the media tag
257 * @param[out] tag_id The ID of the media tag
259 * @return @c 0 on success,
260 * otherwise a negative error value
262 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
263 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
265 int media_tag_get_tag_id(media_tag_h tag, int *tag_id);
268 * @brief Gets the tag name.
269 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
271 * @remarks The @a tag_name should be released using free().
273 * @param[in] tag The handle to the media tag
274 * @param[out] tag_name The name of the media tag
276 * @return @c 0 on success,
277 * otherwise a negative error value
279 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
280 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
281 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
283 int media_tag_get_name(media_tag_h tag, char **tag_name);
286 * @brief Gets the media tag from the media database.
288 * @details This function creates a new media tag handle from the media database by the given @a tag_id.
289 * Media tag will be created and will be filled with tag information.
291 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
293 * @remarks The @a tag should be released using media_tag_destroy().
295 * @param[in] tag_id The ID of the media tag
296 * @param[out] tag The handle to the media tag
298 * @return @c 0 on success,
299 * otherwise a negative error value
301 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
302 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
303 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
304 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
305 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
307 * @pre This function requires opened connection to content service by media_content_connect().
309 * @see media_content_connect()
310 * @see media_tag_destroy()
312 int media_tag_get_tag_from_db(int tag_id, media_tag_h *tag);
315 * @brief Adds a new media info to the tag.
316 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
318 * @param[in] tag The handle to the media tag
319 * @param[in] media_id The media ID
321 * @return @c 0 on success,
322 * otherwise a negative error value
324 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
325 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
326 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
328 * @pre This function requires opened connection to content service by media_content_connect().
329 * @post media_tag_update_to_db()
331 * @see media_content_connect()
332 * @see media_tag_remove_media()
334 int media_tag_add_media(media_tag_h tag, const char *media_id);
337 * @brief Removes the media info from the given tag.
338 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
340 * @param[in] tag The handle to the media tag
341 * @param[in] media_id The media ID
343 * @return @c 0 on success,
344 * otherwise a negative error value
346 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
347 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
348 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
350 * @pre This function requires opened connection to content service by media_content_connect().
351 * @post media_tag_update_to_db()
353 * @see media_content_connect()
354 * @see media_tag_add_media()
356 int media_tag_remove_media(media_tag_h tag, const char *media_id);
359 * @brief Sets the name of the tag.
360 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
362 * @param[in] tag The handle to the media tag
363 * @param[in] tag_name The name of the media tag
365 * @return @c 0 on success,
366 * otherwise a negative error value
368 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
369 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
370 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
372 * @post media_tag_update_to_db()
374 int media_tag_set_name(media_tag_h tag, const char *tag_name);
377 * @brief Updates the media tag to the media database.
379 * @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
380 * 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
381 * the given tag attributes in the media database.
383 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
386 * @privilege %http://tizen.org/privilege/content.write
388 * @param[in] tag The handle to the media tag
390 * @return @c 0 on success,
391 * otherwise a negative error value
393 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
394 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
395 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
396 * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
397 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
398 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
399 * @retval #MEDIA_CONTENT_ERROR_NETWORK Network fail
400 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
402 * @pre This function requires opened connection to content service by media_content_connect().
404 * @see media_content_connect()
405 * @see media_tag_destroy()
406 * @see media_tag_add_media()
407 * @see media_tag_remove_media()
408 * @see media_tag_set_name()
410 int media_tag_update_to_db(media_tag_h tag);
418 #endif /* __cplusplus */
420 #endif /* __TIZEN_CONTENT_MEDIA_TAG_H__ */