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_MEDIA_TAG_H__
20 #define __TIZEN_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 created tag handle must be released using media_tag_destroy().
51 * @param[in] tag_name The tag name to be inserted
52 * @param[out] tag The created 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 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 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
115 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
117 * @pre This function requires opened connection to content service by media_content_connect().
119 * @see media_content_connect()
121 int media_tag_get_tag_count_from_db(filter_h filter, int *tag_count);
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.
129 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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
135 * @return @c 0 on success,
136 * otherwise a negative error value
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
145 * @pre This function requires opened connection to content service by media_content_connect().
146 * @post This function invokes media_tag_cb().
148 * @see media_content_connect()
150 * @see media_filter_create()
152 int media_tag_foreach_tag_from_db(filter_h filter, media_tag_cb callback, void *user_data);
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
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
162 * @return @c 0 on success,
163 * otherwise a negative error value
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
171 * @pre This function requires opened connection to content service by media_content_connect().
173 * @see media_content_connect()
175 int media_tag_get_media_count_from_db(int tag_id, filter_h filter, int *media_count);
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.
183 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
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
190 * @return @c 0 on success,
191 * otherwise a negative error value
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
200 * @pre This function requires opened connection to content service by media_content_connect().
201 * @post This function invokes media_info_cb().
203 * @see media_content_connect()
204 * @see media_info_cb()
205 * @see media_filter_create()
207 int media_tag_foreach_media_from_db(int tag_id, filter_h filter, media_info_cb callback, void *user_data);
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.
216 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
218 * @remarks You must release the destination handle using media_tag_destroy().
220 * @param[out] dst The destination handle to the media tag
221 * @param[in] src The source handle to the media tag
223 * @return @c 0 on success,
224 * otherwise a negative error value
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
231 * @see media_tag_destroy()
233 int media_tag_clone(media_tag_h *dst, media_tag_h src);
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.
240 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
242 * @param[in] tag The media tag handle
244 * @return @c 0 on success,
245 * otherwise a negative error value
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
251 * @pre A copy of the media tag handle created by calling media_tag_clone() or media_tag_insert_to_db().
253 * @see media_tag_clone()
254 * @see media_tag_insert_to_db()
256 int media_tag_destroy(media_tag_h tag);
259 * @brief Gets the media tag ID.
260 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
262 * @param[in] tag The media tag handle
263 * @param[out] tag_id The ID of the media tag
265 * @return @c 0 on success,
266 * otherwise a negative error value
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
272 int media_tag_get_tag_id(media_tag_h tag, int *tag_id);
275 * @brief Gets the tag name.
276 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
278 * @remarks You must release @a tag_name using free().
280 * @param[in] tag The media tag handle
281 * @param[out] tag_name The name of the tag
283 * @return @c 0 on success,
284 * otherwise a negative error value
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
291 int media_tag_get_name(media_tag_h tag, char **tag_name);
294 * @brief Gets the media tag from the media database.
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.
299 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
301 * @remarks You must release @a folder using media_tag_destroy().
303 * @param[in] tag_id The ID of the media tag
304 * @param[out] tag The media tag handle associated with the tag ID
306 * @return @c 0 on success,
307 * otherwise a negative error value
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
316 * @pre This function requires opened connection to content service by media_content_connect().
318 * @see media_content_connect()
319 * @see media_tag_destroy()
321 int media_tag_get_tag_from_db(int tag_id, media_tag_h *tag);
324 * @brief Adds a new media info to the tag.
325 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
327 * @param[in] tag The media tag handle
328 * @param[in] media_id The ID to the media info which is added
330 * @return @c 0 on success,
331 * otherwise a negative error value
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
338 * @pre This function requires opened connection to content service by media_content_connect().
339 * @post media_tag_update_to_db()
341 * @see media_content_connect()
342 * @see media_tag_remove_media()
344 int media_tag_add_media(media_tag_h tag, const char *media_id);
347 * @brief Removes the media info from the given tag.
348 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
350 * @param[in] tag The media tag handle
351 * @param[in] media_id The ID to the media info which is removed
353 * @return @c 0 on success,
354 * otherwise a negative error value
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
361 * @pre This function requires opened connection to content service by media_content_connect().
362 * @post media_tag_update_to_db()
364 * @see media_content_connect()
365 * @see media_tag_add_media()
367 int media_tag_remove_media(media_tag_h tag, const char *media_id);
370 * @brief Sets the name of the tag.
371 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
373 * @param[in] tag The media tag handle
374 * @param[in] tag_name The name of the media tag
376 * @return @c 0 on success,
377 * otherwise a negative error value
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
384 * @post media_tag_update_to_db()
386 int media_tag_set_name(media_tag_h tag, char *tag_name);
389 * @brief Updates the media tag to the media database.
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.
395 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
398 * @privilege %http://tizen.org/privilege/content.write
400 * @param[in] tag The media tag handle
402 * @return @c 0 on success,
403 * otherwise a negative error value
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
414 * @pre This function requires opened connection to content service by media_content_connect().
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()
422 int media_tag_update_to_db(media_tag_h tag);
430 #endif /* __cplusplus */
432 #endif /* __TIZEN_MEDIA_TAG_H__ */