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.
18 #ifndef __TIZEN_MEDIA_FOLDER_H__
19 #define __TIZEN_MEDIA_FOLDER_H__
22 #include <media_content_type.h>
27 #endif /* __cplusplus */
30 * @addtogroup CAPI_CONTENT_MEDIA_FOLDER_MODULE
35 * @brief Gets the number of folder for the passed @a filter from the media database.
37 * @param[in] filter The handle to filter. \n To allow searching over different content types, you should use @a filter_h.
38 * @param[out] folder_count The count of media folder
39 * @return 0 on success, otherwise a negative error value.
40 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
41 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
42 * @retval #MEDIA_CONTENT_ERROR_DB_FAILED DB operation failed
43 * @pre This function requires opened connection to content service by media_content_connect().
44 * @see media_content_connect()
47 int media_folder_get_folder_count_from_db(filter_h filter, int *folder_count);
50 * @brief Iterates through available media folders with optional @a filter from the media database.
51 * @details This function gets media folder handles meeting the given
52 * @a filter. The @a callback function will be invoked for every retrieved
53 * folder. If NULL is passed to the @a filter, no filtering is applied.
55 * @param[in] filter The handle to media folder filter
56 * @param[in] callback The callback function to invoke
57 * @param[in] user_data The user data to be passed to the callback function
58 * @return return 0 on success, otherwise a negative error value.
59 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
60 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
61 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
62 * @pre This function requires opened connection to content service by media_content_connect().
63 * @pre A filter handle has to be created by calling media_folder_filter_create()
64 * @post This function invokes media_folder_cb()
65 * @see media_content_connect()
66 * @see #media_folder_cb
67 * @see media_filter_create()
69 int media_folder_foreach_folder_from_db(filter_h filter, media_folder_cb callback, void *user_data);
72 * @brief Gets the number of media files for the passed @a filter in the given @a folder from the media database.
74 * @param[in] folder_id The ID of media folder
75 * @param[in] filter The filter of media content
76 * @param[out] media_count The count of media folder items
77 * @return 0 on success, 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_DB_FAILED DB operation failed
81 * @pre This function requires opened connection to content service by media_content_connect().
82 * @see media_content_connect()
85 int media_folder_get_media_count_from_db(const char *folder_id, filter_h filter, int *media_count);
88 * @brief Iterates through the media files with optional @a filter in the given @a folder from the media database.
89 * @details This function gets all media files associated with the given folder and
90 * meeting desired filter option and calls registered callback function for
91 * every retrieved media item. If NULL is passed to the @a filter, no filtering is applied.
93 * @param[in] folder_id The ID of media folder
94 * @param[in] filter The handle to media info filter
95 * @param[in] callback The callback function to invoke
96 * @param[in] user_data The user data to be passed to the callback function
97 * @return 0 on success, otherwise a negative error value.
98 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
99 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
100 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
101 * @pre This function requires opened connection to content service by media_content_connect().
102 * @post This function invokes media_info_cb()
103 * @see #media_info_cb
104 * @see media_content_connect()
105 * @see media_folder_filter_create()
107 int media_folder_foreach_media_from_db(const char *folder_id, filter_h filter, media_info_cb callback, void *user_data);
110 * @brief Clones the media folder.
111 * @details This function copies the media folder handle from a source to
112 * destination. There is no media_folder_create() function. The media_folder_h is created internally and available through
113 * media folder foreach function such as media_folder_foreach_folder_from_db(). To use this handle outside of these foreach functions,
115 * @remark The destination handle must be released with media_folder_destroy() by you.
116 * @param[out] dst A destination handle to media folder
117 * @param[in] src The source handle to media folder
118 * @return 0 on success, otherwise a negative error value.
119 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
120 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
121 * @see media_folder_destroy()
122 * @see media_folder_foreach_folder_from_db()
124 int media_folder_clone(media_folder_h *dst, media_folder_h src);
127 * @brief Destroys the media folder.
128 * @details The function frees all resources related to the folder handle. This handle
129 * no longer can be used to perform any operation. A new handle has to
130 * be created before the next use.
132 * @param[in] folder The handle to media folder
133 * @return 0 on success, otherwise a negative error value.
134 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
135 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
136 * @pre A copy of the media folder handle created by calling media_folder_clone()
137 * @see media_folder_clone()
139 int media_folder_destroy(media_folder_h folder);
142 * @brief Gets media folder's ID.
144 * @remarks @a folder_id must be released with free() by you.
146 * @param [in] folder The handle to media folder
147 * @param [out] folder_id The ID of media folder
148 * @return 0 on success, otherwise a negative error value.
149 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
150 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
152 int media_folder_get_folder_id(media_folder_h folder, char **folder_id);
155 * @brief Gets the absolute path to the folder.
157 * @remarks @a path must be released with free() by you.
159 * @param[in] folder The handle to media folder
160 * @param[out] path The path of the media folder
161 * @return 0 on success, otherwise a negative error value.
162 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
163 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
164 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
167 int media_folder_get_path(media_folder_h folder, char **path);
170 * @brief Gets the folder name.
172 * @remarks @a folder_name must be released with free() by you.
174 * @param[in] folder The handle to media folder
175 * @param[out] folder_name The name of the media folder
176 * @return 0 on success, otherwise a negative error value.
177 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
178 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
179 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
182 int media_folder_get_name(media_folder_h folder, char **folder_name);
185 * @brief Gets the modified date of the folder.
187 * @param[in] folder The handle to media folder
188 * @param[out] date The modified date of folder
189 * @return 0 on success, otherwise a negative error value.
190 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
191 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
194 int media_folder_get_modified_time(media_folder_h folder, time_t *date);
197 * @brief Gets the folder storage type.
199 * @param[in] folder The handle to media folder
200 * @param[out] storage_type The storage type of the media folder
201 * @return 0 on success, otherwise a negative error value.
202 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
203 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
206 int media_folder_get_storage_type(media_folder_h folder, media_content_storage_e *storage_type);
209 * @brief Gets the media folder from the media database.
211 * @details This function creates a new media folder handle from the media database by the given folder_id.
212 * media folder will be created, which is filled with folder information.
214 * @remarks @a folder must be released with media_folder_destroy() by you.
216 * @param[in] folder_id The ID of media folder
217 * @param[out] folder The media folder handle associated with the folder ID
218 * @return 0 on success, otherwise a negative error value.
219 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
220 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
221 * @pre This function requires opened connection to content service by media_content_connect().
222 * @see media_content_connect()
223 * @see media_folder_destroy()
226 int media_folder_get_folder_from_db(const char *folder_id, media_folder_h *folder);
229 * @brief Updates the media folder to the media database.
231 * @details The function updates the given media folder in the media database. The function should be called after any change in folder attributes, to be updated to the media
232 * database. For example, after using media_folder_set_name() for setting the name of the folder, media_folder_update_to_db() function should be called so as to update
233 * the given folder attibutes in the media database.
235 * @param[in] folder The handle to media folder
236 * @return 0 on success, otherwise a negative error value.
237 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
238 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
239 * @pre This function requires opened connection to content service by media_content_connect().
240 * @see media_content_connect()
241 * @see media_folder_destroy()
242 * @see media_folder_set_name()
245 int media_folder_update_to_db(media_folder_h folder);
248 * @brief Sets the folder name.
250 * @param[in] folder The handle to media folder
251 * @param[in] name The name of the media folder
252 * @return 0 on success, otherwise a negative error value.
253 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
254 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
255 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
256 * @post media_folder_update_to_db()
259 int media_folder_set_name(media_folder_h folder, const char *name);
267 #endif /* __cplusplus */
269 #endif /* __TIZEN_MEDIA_FOLDER_H__ */