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 * @addtogroup CAPI_CONTENT_MEDIA_TAG_MODULE
35 * @brief Inserts a new tag in the media database.
37 * @remark The created tag handle must be released with media_tag_destroy() by you.
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()
51 int media_tag_insert_to_db(const char *tag_name, media_tag_h *tag);
54 * @brief Deletes a given tag from the media database.
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()
65 int media_tag_delete_from_db(int tag_id);
68 * @brief Gets the number of tag for the passed @a filter from the media database.
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()
80 int media_tag_get_tag_count_from_db(filter_h filter, int *tag_count);
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.
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()
98 * @see media_filter_create()
101 int media_tag_foreach_tag_from_db (filter_h filter, media_tag_cb callback, void *user_data);
104 * @brief Gets the number of media files for the passed @a filter in the given @a tag from the media database.
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()
117 int media_tag_get_media_count_from_db (int tag_id, filter_h filter, int *media_count);
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.
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()
139 int media_tag_foreach_media_from_db(int tag_id, filter_h filter, media_info_cb callback, void *user_data);
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.
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()
158 int media_tag_clone(media_tag_h *dst, media_tag_h src);
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.
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()
174 int media_tag_destroy(media_tag_h tag);
177 * @brief Gets media tag's ID.
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
186 int media_tag_get_tag_id(media_tag_h tag, int *tag_id);
189 * @brief Gets the tag name.
191 * @remarks @a tag_name must be released with free() by you.
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
201 int media_tag_get_name(media_tag_h tag, char **tag_name);
204 * @brief Gets the media tag from the media database.
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.
209 * @remarks @a folder must be released with media_tag_destroy() by you.
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()
221 int media_tag_get_tag_from_db(int tag_id, media_tag_h *tag);
224 * @brief Adds a new media info to the tag.
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()
238 int media_tag_add_media(media_tag_h tag, const char *media_id);
241 * @brief Removes the media info from the given tag.
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()
255 int media_tag_remove_media(media_tag_h tag, const char *media_id);
258 * @brief Sets the tag name.
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()
269 int media_tag_set_name(media_tag_h tag, char *tag_name);
272 * @brief Updates the media tag to the media database.
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.
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()
290 int media_tag_update_to_db(media_tag_h tag);
298 #endif /* __cplusplus */
300 #endif /* __TIZEN_MEDIA_TAG_H__ */