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
230 * @see media_tag_destroy()
232 int media_tag_clone(media_tag_h *dst, media_tag_h src);
235 * @brief Destroys the media tag.
236 * @details This function frees all resources related to the tag handle. The tag handle can no longer
237 * be used for any operation. A new tag handle has to be created before next usage.
239 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
241 * @param[in] tag The media tag handle
243 * @return @c 0 on success,
244 * otherwise a negative error value
246 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
247 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
249 * @pre A copy of the media tag handle created by calling media_tag_clone() or media_tag_insert_to_db().
251 * @see media_tag_clone()
252 * @see media_tag_insert_to_db()
254 int media_tag_destroy(media_tag_h tag);
257 * @brief Gets the media tag ID.
258 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
260 * @param[in] tag The media tag handle
261 * @param[out] tag_id The ID of the media tag
263 * @return @c 0 on success,
264 * otherwise a negative error value
266 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
267 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
269 int media_tag_get_tag_id(media_tag_h tag, int *tag_id);
272 * @brief Gets the tag name.
273 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
275 * @remarks You must release @a tag_name using free().
277 * @param[in] tag The media tag handle
278 * @param[out] tag_name The name of the tag
280 * @return @c 0 on success,
281 * otherwise a negative error value
283 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
284 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
285 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
287 int media_tag_get_name(media_tag_h tag, char **tag_name);
290 * @brief Gets the media tag from the media database.
292 * @details This function creates a new media tag handle from the media database by the given @a tag_id.
293 * Media tag will be created and will be filled with tag information.
295 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
297 * @remarks You must release @a folder using media_tag_destroy().
299 * @param[in] tag_id The ID of the media tag
300 * @param[out] tag The media tag handle associated with the tag ID
302 * @return @c 0 on success,
303 * otherwise a negative error value
305 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
306 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
307 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
308 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
309 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
310 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
312 * @pre This function requires opened connection to content service by media_content_connect().
314 * @see media_content_connect()
315 * @see media_tag_destroy()
317 int media_tag_get_tag_from_db(int tag_id, media_tag_h *tag);
320 * @brief Adds a new media info to the tag.
321 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
323 * @param[in] tag The media tag handle
324 * @param[in] media_id The ID to the media info which is added
326 * @return @c 0 on success,
327 * otherwise a negative error value
329 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
330 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
331 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
333 * @pre This function requires opened connection to content service by media_content_connect().
334 * @post media_tag_update_to_db()
336 * @see media_content_connect()
337 * @see media_tag_remove_media()
339 int media_tag_add_media(media_tag_h tag, const char *media_id);
342 * @brief Removes the media info from the given tag.
343 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
345 * @param[in] tag The media tag handle
346 * @param[in] media_id The ID to the media info which is removed
348 * @return @c 0 on success,
349 * otherwise a negative error value
351 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
352 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
353 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
355 * @pre This function requires opened connection to content service by media_content_connect().
356 * @post media_tag_update_to_db()
358 * @see media_content_connect()
359 * @see media_tag_add_media()
361 int media_tag_remove_media(media_tag_h tag, const char *media_id);
364 * @brief Sets the name of the tag.
365 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
367 * @param[in] tag The media tag handle
368 * @param[in] tag_name The name of the media tag
370 * @return @c 0 on success,
371 * otherwise a negative error value
373 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
374 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
375 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
377 * @post media_tag_update_to_db()
379 int media_tag_set_name(media_tag_h tag, const char *tag_name);
382 * @brief Updates the media tag to the media database.
384 * @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
385 * 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
386 * the given tag attributes in the media database.
388 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
391 * @privilege %http://tizen.org/privilege/content.write
393 * @param[in] tag The media tag handle
395 * @return @c 0 on success,
396 * otherwise a negative error value
398 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
399 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
400 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
401 * @retval #MEDIA_CONTENT_ERROR_INVALID_OPERATION Invalid operation
402 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
403 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
404 * @retval #MEDIA_CONTENT_ERROR_NETWORK Network fail
405 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
407 * @pre This function requires opened connection to content service by media_content_connect().
409 * @see media_content_connect()
410 * @see media_tag_destroy()
411 * @see media_tag_add_media()
412 * @see media_tag_remove_media()
413 * @see media_tag_set_name()
415 int media_tag_update_to_db(media_tag_h tag);
423 #endif /* __cplusplus */
425 #endif /* __TIZEN_MEDIA_TAG_H__ */