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_CONTENT_MEDIA_GROUP_H__
18 #define __TIZEN_CONTENT_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 handle to the media filter
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
57 * @pre This function requires opened connection to content service by media_content_connect().
59 * @see media_content_connect()
61 int media_album_get_album_count_from_db(filter_h filter, int *album_count);
64 * @brief Iterates through the media album with optional @a filter from the media database.
65 * @details This function gets all media album handles meeting the given filter.
66 * The callback function will be invoked for every retrieved media album.
67 * If @c NULL is passed to the filter, no filtering is applied.
69 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
71 * @param[in] filter The handle to the media filter
72 * @param[in] callback The callback function to be invoked
73 * @param[in] user_data The user data to be passed to the callback function
75 * @return @c 0 on success,
76 * otherwise a negative error value
78 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
79 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
80 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
81 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
82 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
84 * @pre This function requires opened connection to content service by media_content_connect().
85 * @post This function invokes media_album_cb().
87 * @see #media_album_cb
88 * @see media_content_connect()
89 * @see media_filter_create()
91 int media_album_foreach_album_from_db(filter_h filter, media_album_cb callback, void *user_data);
94 * @brief Gets the number of media info for the given album present in the media database.
95 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
97 * @param[in] album_id The ID of the media album
98 * @param[in] filter The handle to the media filter
99 * @param[out] media_count The count of the media album
101 * @return @c 0 on success,
102 * otherwise a negative error value
104 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
105 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
106 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
107 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
109 * @pre This function requires opened connection to content service by media_content_connect().
111 * @see media_content_connect()
113 int media_album_get_media_count_from_db(int album_id, filter_h filter, int *media_count);
116 * @brief Iterates through the media files with an optional @a filter in the given media album from the media database.
117 * @details This function gets all media files associated with the given media album and
118 * meeting desired filter option and calls @a callback for
119 * every retrieved media info. If @c NULL is passed to the @a filter, no filtering is applied.
121 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
123 * @param[in] album_id The ID of the media album
124 * @param[in] filter The handle to the media filter
125 * @param[in] callback The callback function to be invoked
126 * @param[in] user_data The user data to be passed to the callback function
128 * @return @c 0 on success,
129 * otherwise a negative error value
131 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
132 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
133 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
134 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
135 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
137 * @pre This function requires opened connection to content service by media_content_connect().
138 * @post This function invokes media_info_cb().
140 * @see #media_info_cb
141 * @see media_content_connect()
142 * @see media_filter_create()
144 int media_album_foreach_media_from_db(int album_id, filter_h filter, media_info_cb callback, void *user_data);
147 * @brief Destroys the album handle.
148 * @details This function frees all resources related to the album handle. This handle
149 * can no longer be used to perform any operations. A new handle has to
150 * be created before the next use.
152 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
154 * @param[in] album The handle to the media album
156 * @return @c 0 on success,
157 * otherwise a negative error value
159 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
160 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
162 * @pre Get copy of album handle by calling media_album_clone().
164 * @see media_album_clone()
166 int media_album_destroy(media_album_h album);
169 * @brief Clones a media album.
170 * @details This function copies the media album handle from a source to
171 * destination. There is no media_album_create() function. The media_album_h is created internally and available through
172 * media album foreach function such as media_album_foreach_album_from_db(). To use this handle outside of these foreach functions,
175 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
177 * @remarks The @a dst should be released using media_album_destroy().
179 * @param[out] dst The destination handle to the media album
180 * @param[in] src The source handle to the media album
182 * @return @c 0 on success,
183 * otherwise a negative error value
185 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
186 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
187 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
189 * @see media_album_destroy()
190 * @see media_album_foreach_album_from_db()
192 int media_album_clone(media_album_h *dst, media_album_h src);
195 * @brief Gets the ID of the album.
196 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
198 * @param[in] album The handle to the media album
199 * @param[out] album_id The ID of the media album
201 * @return @c 0 on success,
202 * otherwise a negative error value
204 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
205 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
207 * @see media_album_foreach_album_from_db()
209 int media_album_get_album_id(media_album_h album, int *album_id);
212 * @brief Gets the name of the album.
213 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
215 * @remarks The @a album_name should be released using free().
217 * @param[in] album The handle to the media album
218 * @param[out] album_name The name of the media album handle
220 * @return @c 0 on success,
221 * otherwise a negative error value
223 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
224 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
225 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
227 int media_album_get_name(media_album_h album, char **album_name);
230 * @brief Gets the name of the artist from the given album.
231 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
233 * @remarks The @a artist should be released using free().
235 * @param[in] album The handle to the media album
236 * @param[out] artist The name of the media artist
238 * @return @c 0 on success,
239 * otherwise a negative error value
241 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
242 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
243 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
245 int media_album_get_artist(media_album_h album, char **artist);
248 * @brief Gets the album art path from the album.
249 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
251 * @remarks The @a album_art should be released using free().
253 * @param[in] album The handle to the media album
254 * @param[out] album_art The path of the media album_art
256 * @return @c 0 on success,
257 * otherwise a negative error value
259 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
260 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
261 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
263 int media_album_get_album_art(media_album_h album, char **album_art);
266 * @brief Gets the media album from the media database.
268 * @details This function creates a new media album handle from the media database by the given @a album_id.
269 * Media album will be created and will be filled with the album information.
271 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
273 * @remarks The @a album should be released using media_album_destroy().
275 * @param[in] album_id The ID of the media album
276 * @param[out] album The handle to the media album
278 * @return @c 0 on success,
279 * otherwise a negative error value
281 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
282 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
283 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
284 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
285 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
287 * @pre This function requires opened connection to content service by media_content_connect().
289 * @see media_content_connect()
290 * @see media_album_destroy()
292 int media_album_get_album_from_db(int album_id, media_album_h *album);
301 * @addtogroup CAPI_CONTENT_MEDIA_GROUP_MODULE
306 * @brief Gets the number of the group for the passed @a filter from the media database.
307 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
309 * @param[in] filter The handle to the media filter
310 * @param[in] group The type of the media group
311 * @param[out] group_count The count of the media group
313 * @return @c 0 on success,
314 * otherwise a negative error value
316 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
317 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
318 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
319 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
321 * @pre This function requires opened connection to content service by media_content_connect().
323 * @see media_content_connect()
325 int media_group_get_group_count_from_db(filter_h filter, media_group_e group, int *group_count);
328 * @brief Iterates through the media group with an optional @a filter from the media database.
329 * @details This function gets names of media group meeting the given filter.
330 * The callback function will be invoked for every retrieved media group.
331 * If @c NULL is passed to the filter, no filtering is applied.
333 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
335 * @param[in] filter The handle to the media filter
336 * @param[in] group The type of the media group
337 * @param[in] callback The callback function to be invoked
338 * @param[in] user_data The user data to be passed to the callback function
340 * @return @c 0 on success,
341 * otherwise a negative error value
343 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
344 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
345 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
346 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
347 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
349 * @pre This function requires opened connection to content service by media_content_connect().
350 * @post This function invokes media_group_cb().
352 * @see #media_group_cb
353 * @see media_content_connect()
354 * @see media_filter_create()
356 int media_group_foreach_group_from_db(filter_h filter, media_group_e group, media_group_cb callback, void *user_data);
359 * @brief Gets the count of the media info for the given media group present in the media database.
360 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
362 * @param[in] group_name The name of the media group
363 * @param[in] group The type of the media group
364 * @param[in] filter The handle to the media filter
365 * @param[out] media_count The count of the media
367 * @return @c 0 on success,
368 * otherwise a negative error value
370 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
371 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
372 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
373 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
374 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
376 * @pre This function requires opened connection to content service by media_content_connect().
378 * @see media_content_connect()
380 int media_group_get_media_count_from_db(const char *group_name, media_group_e group, filter_h filter, int *media_count);
383 * @brief Iterates through the media files with an optional @a filter in the given @a group from the media database.
384 * @details This function gets all media files associated with the given group and
385 * meeting desired filter option and calls @a callback for
386 * every retrieved media info. If @c NULL is passed to the @a filter, no filtering is applied.
388 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
390 * @param[in] group_name The name of the media group
391 * @param[in] group The type of the media group
392 * @param[in] filter The handle to the media filter
393 * @param[in] callback The callback function to be invoked
394 * @param[in] user_data The user data to be passed to the callback function
396 * @return @c 0 on success,
397 * otherwise a negative error value
399 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
400 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
401 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
402 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB Operation failed
403 * @retval #MEDIA_CONTENT_ERROR_DB_BUSY DB Operation busy
405 * @pre This function requires opened connection to content service by media_content_connect().
406 * @post This function invokes media_info_cb().
408 * @see media_info_cb()
409 * @see media_content_connect()
410 * @see media_filter_create()
412 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);
420 #endif /* __cplusplus */
422 #endif /* __TIZEN_CONTENT_MEDIA_GROUP_H__ */