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 * @deprecated Deprecated since 9.0.
44 * @brief Inserts a new tag in the media database.
48 * @privilege %http://tizen.org/privilege/content.write
50 * @remarks The @a tag should be released using media_tag_destroy().
52 * @param[in] tag_name The tag name to be inserted
53 * @param[out] tag The handle to the media tag
55 * @return @c 0 on success,
56 * otherwise a negative error value
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
67 * @pre This function requires opened connection to content service by media_content_connect().
69 * @see media_content_connect()
70 * @see media_tag_delete_from_db()
71 * @see media_tag_destroy()
73 int media_tag_insert_to_db(const char *tag_name, media_tag_h *tag) TIZEN_DEPRECATED_API;
76 * @deprecated Deprecated since 9.0.
77 * @brief Deletes a given tag from the media database.
81 * @privilege %http://tizen.org/privilege/content.write
83 * @param[in] tag_id The ID of the media tag
85 * @return @c 0 on success,
86 * otherwise a negative error value
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
96 * @pre This function requires opened connection to content service by media_content_connect().
98 * @see media_content_connect()
99 * @see media_tag_insert_to_db()
101 int media_tag_delete_from_db(int tag_id) TIZEN_DEPRECATED_API;
104 * @deprecated Deprecated since 9.0.
105 * @brief Gets the count of the tag for the passed @a filter from the media database.
108 * @param[in] filter The handle to the media filter
109 * @param[out] tag_count The count of the media tag
111 * @return @c 0 on success,
112 * otherwise a negative error value
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
119 * @pre This function requires opened connection to content service by media_content_connect().
121 * @see media_content_connect()
123 int media_tag_get_tag_count_from_db(filter_h filter, int *tag_count) TIZEN_DEPRECATED_API;
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.
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
138 * @return @c 0 on success,
139 * otherwise a negative error value
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
147 * @pre This function requires opened connection to content service by media_content_connect().
148 * @post This function invokes media_tag_cb().
150 * @see media_content_connect()
152 * @see media_filter_create()
154 int media_tag_foreach_tag_from_db(filter_h filter, media_tag_cb callback, void *user_data) TIZEN_DEPRECATED_API;
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.
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
165 * @return @c 0 on success,
166 * otherwise a negative error value
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
173 * @pre This function requires opened connection to content service by media_content_connect().
175 * @see media_content_connect()
177 int media_tag_get_media_count_from_db(int tag_id, filter_h filter, int *media_count) TIZEN_DEPRECATED_API;
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.
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
193 * @return @c 0 on success,
194 * 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 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
200 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
202 * @pre This function requires opened connection to content service by media_content_connect().
203 * @post This function invokes media_info_cb().
205 * @see media_content_connect()
206 * @see media_info_cb()
207 * @see media_filter_create()
209 int media_tag_foreach_media_from_db(int tag_id, filter_h filter, media_info_cb callback, void *user_data) TIZEN_DEPRECATED_API;
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.
221 * @remarks The @a dst should be released using media_tag_destroy().
223 * @param[out] dst The destination handle to the media tag
224 * @param[in] src The source handle to the media tag
226 * @return @c 0 on success,
227 * otherwise a negative error value
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
233 * @see media_tag_destroy()
235 int media_tag_clone(media_tag_h *dst, media_tag_h src) TIZEN_DEPRECATED_API;
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.
245 * @param[in] tag The handle to the media tag
247 * @return @c 0 on success,
248 * otherwise a negative error value
250 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
251 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
253 * @pre A copy of the media tag handle created by calling media_tag_clone() or media_tag_insert_to_db().
255 * @see media_tag_clone()
256 * @see media_tag_insert_to_db()
258 int media_tag_destroy(media_tag_h tag) TIZEN_DEPRECATED_API;
261 * @deprecated Deprecated since 9.0.
262 * @brief Gets the media tag ID.
265 * @param[in] tag The handle to the media tag
266 * @param[out] tag_id The ID of the media tag
268 * @return @c 0 on success,
269 * otherwise a negative error value
271 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
272 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
274 int media_tag_get_tag_id(media_tag_h tag, int *tag_id) TIZEN_DEPRECATED_API;
277 * @deprecated Deprecated since 9.0.
278 * @brief Gets the tag name.
281 * @remarks The @a tag_name should be released using free().
283 * @param[in] tag The handle to the media tag
284 * @param[out] tag_name The name of the media tag
286 * @return @c 0 on success,
287 * otherwise a negative error value
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
293 int media_tag_get_name(media_tag_h tag, char **tag_name) TIZEN_DEPRECATED_API;
296 * @deprecated Deprecated since 9.0.
297 * @brief Gets the media tag from the media database.
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.
304 * @remarks The @a tag should be released using media_tag_destroy().
306 * @param[in] tag_id The ID of the media tag
307 * @param[out] tag The handle to the media tag
309 * @return @c 0 on success,
310 * otherwise a negative error value
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
318 * @pre This function requires opened connection to content service by media_content_connect().
320 * @see media_content_connect()
321 * @see media_tag_destroy()
323 int media_tag_get_tag_from_db(int tag_id, media_tag_h *tag) TIZEN_DEPRECATED_API;
326 * @deprecated Deprecated since 9.0.
327 * @brief Adds a new media info to the tag.
330 * @param[in] tag The handle to the media tag
331 * @param[in] media_id The media ID
333 * @return @c 0 on success,
334 * otherwise a negative error value
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
340 * @pre This function requires opened connection to content service by media_content_connect().
341 * @post media_tag_update_to_db()
343 * @see media_content_connect()
344 * @see media_tag_remove_media()
346 int media_tag_add_media(media_tag_h tag, const char *media_id) TIZEN_DEPRECATED_API;
349 * @deprecated Deprecated since 9.0.
350 * @brief Removes the media info from the given tag.
353 * @param[in] tag The handle to the media tag
354 * @param[in] media_id The media ID
356 * @return @c 0 on success,
357 * otherwise a negative error value
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
363 * @pre This function requires opened connection to content service by media_content_connect().
364 * @post media_tag_update_to_db()
366 * @see media_content_connect()
367 * @see media_tag_add_media()
369 int media_tag_remove_media(media_tag_h tag, const char *media_id) TIZEN_DEPRECATED_API;
372 * @deprecated Deprecated since 9.0.
373 * @brief Sets the name of the tag.
376 * @param[in] tag The handle to the media tag
377 * @param[in] tag_name The name of the media tag
379 * @return @c 0 on success,
380 * otherwise a negative error value
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
386 * @post media_tag_update_to_db()
388 int media_tag_set_name(media_tag_h tag, const char *tag_name) TIZEN_DEPRECATED_API;
391 * @deprecated Deprecated since 9.0.
392 * @brief Updates the media tag to the media database.
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.
401 * @privilege %http://tizen.org/privilege/content.write
403 * @param[in] tag The handle to the media tag
405 * @return @c 0 on success,
406 * otherwise a negative error value
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
417 * @pre This function requires opened connection to content service by media_content_connect().
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()
425 int media_tag_update_to_db(media_tag_h tag) TIZEN_DEPRECATED_API;
433 #endif /* __cplusplus */
435 #endif /* __TIZEN_CONTENT_MEDIA_TAG_H__ */