include_product/media_filter.h

   1 /*
   2 * Copyright (c) 2011 Samsung Electronics Co., Ltd All Rights Reserved
   3 *
   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
   7 *
   8 * http://www.apache.org/licenses/LICENSE-2.0
   9 *
  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.
  15 */
  16
  17
  18
  19 #ifndef __TIZEN_CONTENT_MEDIA_FILTER_H__
  20 #define __TIZEN_CONTENT_MEDIA_FILTER_H__
  21
  22 #include <media_content_type.h>
  23
  24
  25 #ifdef __cplusplus
  26 extern "C" {
  27 #endif /* __cplusplus */
  28
  29 /**
  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.
  35  */
  36
  37 /**
  38  * @addtogroup CAPI_CONTENT_MEDIA_FILTER_MODULE
  39  * @{
  40  */
  41
  42 /**
  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.
  46  *
  47  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  48  *
  49  * @remarks The @a filter should be released using media_info_filter_destroy().
  50  *
  51  * @param[out] filter The handle to the media filter
  52  *
  53  * @return @c 0 on success,
  54  *         otherwise a negative error value
  55  *
  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  *
  60  * @see media_filter_destroy()
  61  */
  62 int media_filter_create(filter_h *filter);
  63
  64 /**
  65  * @brief Destroys a media filter handle.
  66  * @details The function frees all resources related to the media filter handle. The filter
  67  *          handle no longer can be used to perform any operations. A new filter handle
  68  *          has to be created before the next usage.
  69  *
  70  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  71  *
  72  * @param[in] filter The handle to the media filter
  73  *
  74  * @return @c 0 on success,
  75  *         otherwise a negative error value
  76  *
  77  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  78  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  79  *
  80  * @see media_filter_create()
  81  */
  82 int media_filter_destroy(filter_h filter);
  83
  84 /**
  85  * @brief Sets the media filter offset and count.
  86  * @details This function sets the @a offset and @a count for the given filter used to limit number of items returned.
  87  *          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.
  88  *
  89  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  90  *
  91  * @param[in] filter The handle to the media filter
  92  * @param[in] offset The start position of the given media filter (Starting from zero)
  93  * @param[in] count The number of items to be searched with respect to the offset
  94  *
  95  * @return @c 0 on success,
  96  *         otherwise a negative error value
  97  *
  98  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
  99  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 100  *
 101  * @see media_filter_create()
 102  * @see media_filter_destroy()
 103  */
 104 int media_filter_set_offset(filter_h filter, int offset, int count);
 105
 106 /**
 107  * @brief Sets the @a condition for the given @a filter.
 108  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 109  *
 110  * @param[in] filter The handle to the media filter
 111  * @param[in] condition The condition which is used WHERE clause on a query
 112  * @param[in] collate_type The collate type for comparing two strings
 113  *
 114  * @return @c 0 on success,
 115  *         otherwise a negative error value
 116  *
 117  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 118  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 119  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 120  *
 121  * @see media_filter_create()
 122  * @see media_filter_destroy()
 123  */
 124 int media_filter_set_condition(filter_h filter, const char *condition, media_content_collation_e collate_type);
 125
 126 /**
 127  * @brief Sets the media filter content @a order_type and @a order_keyword i.e. either descending or ascending.
 128  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 129  *
 130  * @param[in] filter The handle to the media filter
 131  * @param[in] order_type The search order type
 132  * @param[in] order_keyword The search order keyword
 133  * @param[in] collate_type The collate type for comparing two strings
 134  *
 135  * @return @c 0 on success,
 136  *         otherwise a negative error value
 137  *
 138  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 139  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 140  *
 141  * @see media_filter_create()
 142  * @see media_filter_destroy()
 143  */
 144 int media_filter_set_order(filter_h filter, media_content_order_e order_type, const char *order_keyword, media_content_collation_e collate_type);
 145
 146 /**
 147  * @deprecated Deprecated since 5.0. Use media_filter_set_condition() with MEDIA_PATH keyword instead. \n
 148  *             See @ref CAPI_SYSTEM_STORAGE_MODULE for information about file system paths.
 149  *
 150  * @brief Sets the @a storage_id for the given @a filter.
 151  * @details You can use this function when you want to search items only in the specific storage
 152  *
 153  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 154  *
 155  * @param[in] filter The handle to the media filter
 156  * @param[in] storage_id The ID of the media storage
 157  *
 158  * @return @c 0 on success,
 159  *         otherwise a negative error value
 160  *
 161  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 162  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 163  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 164  *
 165  * @see media_filter_create()
 166  * @see media_filter_destroy()
 167  */
 168 int media_filter_set_storage(filter_h filter, const char *storage_id) TIZEN_DEPRECATED_API;
 169
 170 /**
 171  * @brief Gets the @a offset and @a count for the given @a filter used to limit the number of items returned.
 172  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 173  *
 174  * @param[in] filter The handle to the media filter
 175  * @param[out] offset The start position of the given media filter (Starting from zero)
 176  * @param[out] count The number of items to be searched with respect to the offset
 177  *
 178  * @return @c 0 on success,
 179  *         otherwise a negative error value
 180  *
 181  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 182  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 183  *
 184  * @see media_filter_create()
 185  * @see media_filter_destroy()
 186  */
 187 int media_filter_get_offset(filter_h filter, int *offset, int *count);
 188
 189 /**
 190  * @brief Gets the @a condition for the given @a filter.
 191  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 192  *
 193  * @remarks The @a condition should be released using free().
 194  *
 195  * @param[in] filter The handle to the media filter
 196  * @param[out] condition The condition which is used WHERE clause on a query
 197  * @param[out] collate_type The collate type for comparing two strings
 198  *
 199  * @return @c 0 on success,
 200  *         otherwise a negative error value
 201  *
 202  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 203  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY     Out of memory
 204  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 205  *
 206  * @see media_filter_create()
 207  * @see media_filter_destroy()
 208  */
 209 int media_filter_get_condition(filter_h filter, char **condition, media_content_collation_e *collate_type);
 210
 211 /**
 212  * @brief Gets the media filter's content @a order_type and @a order_keyword i.e. either descending or ascending.
 213  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 214  *
 215  * @remarks The @a order_keyword should be released using free().
 216  *
 217  * @param[in] filter The handle to the media filter
 218  * @param[out] order_type The search order type
 219  * @param[out] order_keyword The search order keyword
 220  * @param[out] collate_type The collate type for comparing two strings
 221  *
 222  * @return @c 0 on success,
 223  *         otherwise a negative error value
 224  *
 225  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 226  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 227  *
 228  * @see media_filter_create()
 229  * @see media_filter_destroy()
 230  */
 231 int media_filter_get_order(filter_h filter, media_content_order_e* order_type, char **order_keyword, media_content_collation_e *collate_type);
 232
 233 /**
 234  * @deprecated Deprecated since 5.0.
 235  * @brief Gets the @a storage_id for given @a filter.
 236  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 237  *
 238  * @remarks The @a storage_id should be released using free().
 239  *
 240  * @param[in] filter The handle to the media filter
 241  * @param[out] storage_id The ID of the media storage
 242  *
 243  * @return @c 0 on success,
 244  *         otherwise a negative error value
 245  *
 246  * @retval #MEDIA_CONTENT_ERROR_NONE              Successful
 247  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 248  *
 249  * @see media_filter_create()
 250  * @see media_filter_destroy()
 251  */
 252 int media_filter_get_storage(filter_h filter, char **storage_id) TIZEN_DEPRECATED_API;
 253
 254 /**
 255  * @}
 256  */
 257
 258 #ifdef __cplusplus
 259 }
 260 #endif /* __cplusplus */
 261
 262 #endif /* __TIZEN_CONTENT_MEDIA_FILTER_H__ */