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_MEDIA_FILTER_H__
  20 #define __TIZEN_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 You must release the @a filter handle using media_info_filter_destroy().
  50  *
  51  * @param[out] filter A 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  * @retval #MEDIA_CONTENT_ERROR_PERMISSION_DENIED Permission denied
  60  *
  61  * @see media_filter_destroy()
  62  */
  63 int media_filter_create(filter_h *filter);
  64
  65 /**
  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.
  70  *
  71  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  72  *
  73  * @param[in] filter The handle to the media filter
  74  *
  75  * @return @c 0 on success,
  76  *         otherwise a negative error value
  77  *
  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
  81  *
  82  * @see media_filter_create()
  83  */
  84 int media_filter_destroy(filter_h filter);
  85
  86 /**
  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.
  90  *
  91  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  92  *
  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
  96  *
  97  * @return @c 0 on success,
  98  *         otherwise a negative error value
  99  *
 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
 103  *
 104  * @see media_filter_create()
 105  * @see media_filter_destroy()
 106  */
 107 int media_filter_set_offset(filter_h filter, int offset, int count);
 108
 109 /**
 110  * @brief Sets the @a condition for the given @a filter.
 111  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 112  *
 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
 116  *
 117  * @return @c 0 on success,
 118  *         otherwise a negative error value
 119  *
 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
 124  *
 125  * @see media_filter_create()
 126  * @see media_filter_destroy()
 127  */
 128 int media_filter_set_condition(filter_h filter, const char *condition, media_content_collation_e collate_type);
 129
 130 /**
 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
 133  *
 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
 138  *
 139  * @return @c 0 on success,
 140  *         otherwise a negative error value
 141  *
 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
 145  *
 146  * @see media_filter_create()
 147  * @see media_filter_destroy()
 148  */
 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);
 150
 151 /**
 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
 154  *
 155  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 156  *
 157  * @param[in] filter       The handle to the media filter
 158  * @param[in] storage_id    The storage_id for browsing or searching
 159  *
 160  * @return @c 0 on success,
 161  *         otherwise a negative error value
 162  *
 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
 167  *
 168  * @see media_filter_create()
 169  * @see media_filter_destroy()
 170  */
 171 int media_filter_set_storage(filter_h filter, const char *storage_id);
 172
 173 /**
 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
 176  *
 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
 180  *
 181  * @return @c 0 on success,
 182  *         otherwise a negative error value
 183  *
 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
 187  *
 188  * @see media_filter_create()
 189  * @see media_filter_destroy()
 190  */
 191 int media_filter_get_offset(filter_h filter, int *offset, int *count);
 192
 193 /**
 194  * @brief Gets the @a condition for the given @a filter.
 195  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 196  *
 197  * @remarks You must release @a condition using free().
 198  *
 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
 202  *
 203  * @return @c 0 on success,
 204  *         otherwise a negative error value
 205  *
 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
 210  *
 211  * @see media_filter_create()
 212  * @see media_filter_destroy()
 213  */
 214 int media_filter_get_condition(filter_h filter, char **condition, media_content_collation_e *collate_type);
 215
 216 /**
 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
 219  *
 220  * @remarks You must release @a order_keyword using free().
 221  *
 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
 226  *
 227  * @return @c 0 on success,
 228  *         otherwise a negative error value
 229  *
 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
 233  *
 234  * @see media_filter_create()
 235  * @see media_filter_destroy()
 236  */
 237 int media_filter_get_order(filter_h filter, media_content_order_e* order_type, char **order_keyword, media_content_collation_e *collate_type);
 238
 239 /**
 240  * @brief Get the @a storage id for given @a filter.
 241  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 242  *
 243  * @remarks You must release @a storage_id using free().
 244  *
 245  * @param[in] filter The handle to media info filter
 246  * @param[out] storage_id The storage_id which is used in filter
 247  *
 248  * @return @c 0 on success,
 249  *         otherwise a negative error value
 250  *
 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
 254  *
 255  * @see media_filter_create()
 256  * @see media_filter_destroy()
 257  */
 258 int media_filter_get_storage(filter_h filter, char **storage_id);
 259
 260 /**
 261  * @}
 262  */
 263
 264 #ifdef __cplusplus
 265 }
 266 #endif /* __cplusplus */
 267
 268 #endif /* __TIZEN_MEDIA_FILTER_H__ */