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.
17 #ifndef __TIZEN_MEDIA_GROUP_H__
18 #define __TIZEN_MEDIA_GROUP_H__
21 #include <media_content_type.h>
26 #endif /* __cplusplus */
30 * @brief This file contains API related to handling different operations with album and other media data groups in DB.
31 * The following APIs are capable to get number of albums, media info in the given album from DB, \n
32 * to clone, destroy and get all albums and media files associated with the given media album from DB, \n
33 * to get name, ID, artist, album art path from album; to get number of groups and their names, \n
34 * to get the number of media files and their content associated with the given group from DB.
38 * @addtogroup CAPI_CONTENT_MEDIA_ALBUM_MODULE
43 * @brief Gets the number of the album for the passed @a filter from the media database.
44 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
46 * @param[in] filter The media filter handle
47 * @param[out] album_count The count of the media album
49 * @return @c 0 on success,
50 * otherwise a negative error value
52 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
53 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
54 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
55 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
56 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
58 * @pre This function requires opened connection to content service by media_content_connect().
60 * @see media_content_connect()
62 int media_album_get_album_count_from_db(filter_h filter, int *album_count);
65 * @brief Iterates through the media album with optional @a filter from the media database.
66 * @details This function gets all media album handles meeting the given filter.
67 * The callback function will be invoked for every retrieved media album.
68 * If @c NULL is passed to the filter, no filtering is applied.
70 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
72 * @param[in] filter The media filter handle
73 * @param[in] callback The callback function to be invoked
74 * @param[in] user_data The user data to be passed to the callback function
76 * @return @c 0 on success,
77 * otherwise a negative error value
79 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
80 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
81 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
82 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
83 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
84 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
86 * @pre This function requires opened connection to content service by media_content_connect().
87 * @post This function invokes media_album_cb().
89 * @see #media_album_cb
90 * @see media_content_connect()
91 * @see media_filter_create()
93 int media_album_foreach_album_from_db(filter_h filter, media_album_cb callback, void *user_data);
96 * @brief Gets the number of media info for the given album present in the media database.
97 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
99 * @param[in] album_id The ID of the media album
100 * @param[in] filter The media filter handle
101 * @param[out] media_count The count of the album
103 * @return @c 0 on success,
104 * otherwise a negative error value
106 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
107 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
108 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
109 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
110 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
113 * @pre This function requires opened connection to content service by media_content_connect().
115 * @see media_content_connect()
117 int media_album_get_media_count_from_db(int album_id, filter_h filter, int *media_count);
120 * @brief Iterates through the media files with an optional @a filter in the given media album from the media database.
121 * @details This function gets all media files associated with the given media album and
122 * meeting desired filter option and calls registered callback function for
123 * every retrieved media info. If @c NULL is passed to the @a filter, no filtering is applied.
125 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
127 * @param[in] album_id The ID of the media album
128 * @param[in] filter The media filter handle
129 * @param[in] callback The callback function to be invoked
130 * @param[in] user_data The user data to be passed to the callback function
132 * @return @c 0 on success,
133 * otherwise a negative error value
135 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
136 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
137 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
138 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
139 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
140 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
142 * @pre This function requires opened connection to content service by media_content_connect().
143 * @post This function invokes media_info_cb().
145 * @see #media_info_cb
146 * @see media_content_connect()
147 * @see media_filter_create()
149 int media_album_foreach_media_from_db(int album_id, filter_h filter, media_info_cb callback, void *user_data);
152 * @brief Destroys the album handle.
153 * @details This function frees all resources related to the album handle. This handle
154 * can no longer be used to perform any operation. A new handle has to
155 * be created before the next use.
157 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
159 * @param[in] album The media album handle
161 * @return @c 0 on success,
162 * otherwise a negative error value
164 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
165 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
166 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
168 * @pre Get copy of album handle by calling media_album_clone().
170 * @see media_album_clone()
172 int media_album_destroy(media_album_h album);
175 * @brief Clones a media album.
176 * @details This function copies the media album handle from a source to
177 * destination. There is no media_album_create() function. The media_album_h is created internally and available through
178 * media album foreach function such as media_album_foreach_album_from_db(). To use this handle outside of these foreach functions,
181 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
183 * @remarks You must release the destination handle using media_album_destroy().
185 * @param[in] src The source handle to the media album
186 * @param[out] dst The destination handle to the media album
188 * @return @c 0 on success,
189 * otherwise a negative error value
191 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
192 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
193 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
194 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
196 * @see media_album_destroy()
197 * @see media_album_foreach_album_from_db()
199 int media_album_clone(media_album_h *dst, media_album_h src);
202 * @brief Gets the ID of the album.
203 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
205 * @param[in] album The media album handle
206 * @param[out] album_id The media album ID
208 * @return @c 0 on success,
209 * otherwise a negative error value
211 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
212 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
213 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
214 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
216 * @see media_album_foreach_album_from_db()
218 int media_album_get_album_id(media_album_h album, int *album_id);
221 * @brief Gets the name of the album.
222 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
224 * @remarks You must release @a album_name using free().
226 * @param[in] album The media album handle
227 * @param[out] album_name The name of the media album handle
229 * @return @c 0 on success,
230 * otherwise a negative error value
232 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
233 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
234 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
235 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
237 int media_album_get_name(media_album_h album, char **album_name);
240 * @brief Gets the name of the artist from the given album.
241 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
243 * @remarks You must release @a artist using free().
245 * @param[in] album The media album handle
246 * @param[out] artist The name of the media artist
248 * @return @c 0 on success,
249 * otherwise a negative error value
251 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
252 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
253 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
254 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
256 int media_album_get_artist(media_album_h album, char **artist);
259 * @brief Gets the album art path from the album.
260 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
262 * @remarks You must release @a album_art using free().
264 * @param[in] album The media album handle
265 * @param[out] album_art The path of the media album_art
267 * @return @c 0 on success,
268 * otherwise a negative error value
270 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
271 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
272 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
273 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
275 int media_album_get_album_art(media_album_h album, char **album_art);
278 * @brief Gets the media album from the media database.
280 * @details This function creates a new media album handle from the media database by the given @a album_id.
281 * Media album will be created and will be filled with the album information.
283 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
285 * @remarks You must release @a folder using media_album_destroy().
287 * @param[in] album_id The ID of the media album
288 * @param[out] album The album handle associated with the album ID
290 * @return @c 0 on success,
291 * otherwise a negative error value
293 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
294 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
295 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
296 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
297 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
298 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
300 * @pre This function requires opened connection to content service by media_content_connect().
302 * @see media_content_connect()
303 * @see media_album_destroy()
305 int media_album_get_album_from_db(int album_id, media_album_h *album);
314 * @addtogroup CAPI_CONTENT_MEDIA_GROUP_MODULE
319 * @brief Gets the number of the group for the passed @a filter from the media database.
320 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
322 * @param[in] filter The media filter handle
323 * @param[in] group The type of the media group
324 * @param[out] group_count The count of the media group
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_DB_FAILED DB Operation failed
332 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
333 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
335 * @pre This function requires opened connection to content service by media_content_connect().
337 * @see media_content_connect()
339 int media_group_get_group_count_from_db(filter_h filter, media_group_e group, int *group_count);
342 * @brief Iterates through the media group with optional @a filter from the media database.
343 * @details This function gets the names and counts of media group meeting the given filter.
344 * The callback function will be invoked for every retrieved media group.
345 * If NULL is passed to the filter, no filtering is applied.
347 * @param [in] filter The handle to media filter
348 * @param [in] group The type of media group
349 * @param [in] callback The callback function to invoke
350 * @param [in] user_data The user data to be passed to the callback function
351 * @return 0 on success, otherwise a negative error value.
352 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
353 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
354 * @pre This function requires opened connection to content service by media_content_connect().
355 * @post This function invokes media_group_cb().
356 * @see #media_group_and_count_cb
357 * @see media_content_connect()
358 * @see media_filter_create()
360 int media_group_foreach_group_and_count_from_db(filter_h filter, media_group_e group, media_group_and_count_cb callback, void *user_data);
363 * @brief Iterates through the media group with an optional @a filter from the media database.
364 * @details This function gets names of media group meeting the given filter.
365 * The callback function will be invoked for every retrieved media group.
366 * If @c NULL is passed to the filter, no filtering is applied.
368 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
370 * @param[in] filter The media filter handle
371 * @param[in] group The type of the media group
372 * @param[in] callback The callback function to be invoked
373 * @param[in] user_data The user data to be passed to the callback function
375 * @return @c 0 on success,
376 * otherwise a negative error value
378 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
379 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
380 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
381 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
382 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
383 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
385 * @pre This function requires opened connection to content service by media_content_connect().
386 * @post This function invokes media_group_cb().
388 * @see #media_group_cb
389 * @see media_content_connect()
390 * @see media_filter_create()
392 int media_group_foreach_group_from_db(filter_h filter, media_group_e group, media_group_cb callback, void *user_data);
395 * @brief Gets the count of the media info for the given media group present in the media database.
396 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
398 * @param[in] group_name The name of the media group
399 * @param[in] group The type of the media group
400 * @param[in] filter The media filter handle
401 * @param[out] media_count The count of the media
403 * @return @c 0 on success,
404 * otherwise a negative error value
406 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
407 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
408 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
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_PERMISSION_DENIED Permission denied
413 * @pre This function requires opened connection to content service by media_content_connect().
415 * @see media_content_connect()
417 int media_group_get_media_count_from_db(const char *group_name, media_group_e group, filter_h filter, int *media_count);
420 * @brief Iterates through the media files with an optional @a filter in the given @a group from the media database.
421 * @details This function gets all media files associated with the given group and
422 * meeting desired filter option and calls registered callback function for
423 * every retrieved media info. If @c NULL is passed to the @a filter, no filtering is applied.
425 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
427 * @param[in] group_name The name of the media group
428 * @param[in] group The type of the media group
429 * @param[in] filter The media filter handle
430 * @param[in] callback The callback function to be invoked
431 * @param[in] user_data The user data to be passed to the callback function
433 * @return @c 0 on success,
434 * otherwise a negative error value
436 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
437 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
438 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
439 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
440 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
441 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
443 * @pre This function requires opened connection to content service by media_content_connect().
444 * @post This function invokes media_info_cb().
446 * @see media_info_cb()
447 * @see media_content_connect()
448 * @see media_filter_create()
450 int media_group_foreach_media_from_db(const char *group_name, media_group_e group, filter_h filter, media_info_cb callback, void *user_data);
458 #endif /* __cplusplus */
460 #endif /* __TIZEN_MEDIA_GROUP_H__ */