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_FILTER_H__
20 #define __TIZEN_MEDIA_FILTER_H__
22 #include <media_content_type.h>
27 #endif /* __cplusplus */
30 * @file media_filter.h
31 * @brief This file contains the media filter API and related operation with filters. \n
32 * The functions include: creating and destroying media filter handles that are used to get the filtered information, \n
33 * making free all resources related to the filter handle, limiting number of items returned, setting conditions for the filter, \n
34 * setting and getting media filter's content order and ordering keyword either descending or ascending.
38 * @addtogroup CAPI_CONTENT_MEDIA_FILTER_MODULE
43 * @brief Creates a media filter handle.
44 * @details This function creates a media filter handle. The handle can be
45 * used to get the filtered information based on filter properties i.e. offset, count, condition for searching and order.
47 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
49 * @remarks You must release the @a filter handle using media_info_filter_destroy().
51 * @param[out] filter A handle to the media filter
53 * @return @c 0 on success,
54 * otherwise a negative error value
56 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
57 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
58 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
59 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
61 * @see media_filter_destroy()
63 int media_filter_create(filter_h *filter);
66 * @brief Destroys a media filter handle.
67 * @details The function frees all resources related to the media filter handle. The filter
68 * handle no longer can be used to perform any operation. A new filter handle
69 * has to be created before the next usage.
71 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
73 * @param[in] filter The handle to the media filter
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_PERMISSION_DENIED Permission denied
82 * @see media_filter_create()
84 int media_filter_destroy(filter_h filter);
87 * @brief Sets the media filter offset and count.
88 * @details This function sets the @a offset and @a count for the given filter used to limit number of items returned.
89 * For example, if you set the @a offset as @c 10 and @a count as @c 5, then only searched data from @c 10 to @c 14 will be returned when the filter is used with foreach functions.
91 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
93 * @param[in] filter The handle to the media filter
94 * @param[in] offset The start position of the given filter (Starting from zero)
95 * @param[in] count The number of items to be searched with respect to the offset
97 * @return @c 0 on success,
98 * otherwise a negative error value
100 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
101 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
102 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
104 * @see media_filter_create()
105 * @see media_filter_destroy()
107 int media_filter_set_offset(filter_h filter, int offset, int count);
110 * @brief Sets the @a condition for the given @a filter.
111 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
113 * @param[in] filter The handle to the media filter
114 * @param[in] condition The condition which is used WHERE clause on a query
115 * @param[in] collate_type The collate type for comparing two strings
117 * @return @c 0 on success,
118 * otherwise a negative error value
120 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
121 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
122 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
123 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
125 * @see media_filter_create()
126 * @see media_filter_destroy()
128 int media_filter_set_condition(filter_h filter, const char *condition, media_content_collation_e collate_type);
131 * @brief Sets the media filter content @a order and order keyword i.e. either descending or ascending.
132 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
134 * @param[in] filter The handle to the media filter
135 * @param[in] order_type The search order type
136 * @param[in] order_keyword The search order keyword
137 * @param[in] collate_type The collate type for comparing two strings
139 * @return @c 0 on success,
140 * otherwise a negative error value
142 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
143 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
144 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
146 * @see media_filter_create()
147 * @see media_filter_destroy()
149 int media_filter_set_order(filter_h filter, media_content_order_e order_type, const char *order_keyword, media_content_collation_e collate_type);
152 * @brief Sets the @a storage id for the given @a filter.
153 * @details You can use this API when you want to search items only in the specific storage
157 * @param[in] filter The handle to the media filter
158 * @param[in] storage_id The storage_id for browsing or searching
160 * @return @c 0 on success,
161 * otherwise a negative error value
163 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
164 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
165 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
166 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
168 * @see media_filter_create()
169 * @see media_filter_destroy()
171 int media_filter_set_storage(filter_h filter, const char *storage_id);
174 * @brief Gets the @a offset and @a count for the given @a filter used to limit the number of items returned.
175 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
177 * @param[in] filter The handle to the media filter
178 * @param[out] offset The start position of the given filter (Starting from zero)
179 * @param[out] count The number of items to be searched with respect to the offset
181 * @return @c 0 on success,
182 * otherwise a negative error value
184 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
185 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
186 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
188 * @see media_filter_create()
189 * @see media_filter_destroy()
191 int media_filter_get_offset(filter_h filter, int *offset, int *count);
194 * @brief Gets the @a condition for the given @a filter.
195 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
197 * @remarks You must release @a condition using free().
199 * @param[in] filter The handle to the media info filter
200 * @param[out] condition The condition which is used WHERE clause on a query
201 * @param[out] collate_type The collate type for comparing two strings
203 * @return @c 0 on success,
204 * otherwise a negative error value
206 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
207 * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
208 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
209 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
211 * @see media_filter_create()
212 * @see media_filter_destroy()
214 int media_filter_get_condition(filter_h filter, char **condition, media_content_collation_e *collate_type);
217 * @brief Gets the media filter's content @a order and order keyword i.e. either descending or ascending.
218 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
220 * @remarks You must release @a order_keyword using free().
222 * @param[in] filter The handle to the media filter
223 * @param[out] order_type The search order type
224 * @param[out] order_keyword The search order keyword
225 * @param[out] collate_type The collate type for comparing two strings
227 * @return @c 0 on success,
228 * otherwise a negative error value
230 * @retval #MEDIA_CONTENT_ERROR_NONE Successful
231 * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
232 * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
234 * @see media_filter_create()
235 * @see media_filter_destroy()
237 int media_filter_get_order(filter_h filter, media_content_order_e* order_type, char **order_keyword, media_content_collation_e *collate_type);
240 * @brief Get the @a storage id for given @a filter.
243 * @remarks You must release @a storage_id using free().
245 * @param[in] filter The handle to media info filter
246 * @param[out] storage_id The storage_id which is used in filter
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_PERMISSION_DENIED Permission denied
255 * @see media_filter_create()
256 * @see media_filter_destroy()
258 int media_filter_get_storage(filter_h filter, char **storage_id);
266 #endif /* __cplusplus */
268 #endif /* __TIZEN_MEDIA_FILTER_H__ */