include/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  * @addtogroup CAPI_CONTENT_MEDIA_FILTER_MODULE
  31  * @{
  32  */
  33
  34 /**
  35  * @brief Creates a media filter handle.
  36  * @details This function creates a media filter handle. The handle can be
  37  * used to get filtered information based on filter properties i.e. offset, count, condition for searching and order.
  38  * @remarks The @a filter handle must be released with media_info_filter_destroy() by you.
  39  * @param[out] filter A handle to media filter
  40  * @return 0 on success, otherwise a negative error value.
  41  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  42  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  43  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
  44  * @see media_filter_destroy()
  45  *
  46  */
  47 int media_filter_create(filter_h *filter);
  48
  49 /**
  50  * @brief Destroys a media filter handle.
  51  * @details The function frees all resources related to the media filter handle. The filter
  52  * handle no longer can be used to perform any operation. A new filter handle
  53  * has to be created before the next usage.
  54  *
  55  * @param[in] filter The handle to media filter
  56  * @return 0 on success, otherwise a negative error value.
  57  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  58  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  59  * @see media_filter_create()
  60  *
  61  */
  62 int media_filter_destroy(filter_h filter);
  63
  64 /**
  65  * @brief Set the media filter's offset and count.
  66  * @details This function set the @a offset and @a count for the given filter used to limit number of items returned.
  67  * For example, if you set the @a offset as 10 and @a count as 5, then only searched data from 10 to 14 will be returned when the filter is used with foreach functions.
  68  *
  69  * @param[in] filter The handle to media filter
  70  * @param[in] offset The start position of the given filter(Starting from zero).
  71  * @param[in] count The number of items to be searched with respect to offset
  72  * @return return 0 on success, otherwise a negative error value.
  73  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  74  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  75  * @see media_filter_create()
  76  * @see media_filter_destroy()
  77  */
  78 int media_filter_set_offset(filter_h filter, int offset, int count);
  79
  80 /**
  81  * @brief Set the @a condition for given @a filter.
  82  *
  83  * @param[in] filter The handle to media filter
  84  * @param[in] condition The condition which is used WHERE clause on a query
  85  * @param[in] collate_type The collate type for comparing two strings
  86  * @return return 0 on success, otherwise a negative error value.
  87  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
  88  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
  89  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
  90  * @see media_filter_create()
  91  * @see media_filter_destroy()
  92  */
  93 int media_filter_set_condition(filter_h filter, const char *condition, media_content_collation_e collate_type);
  94
  95 /**
  96  * @brief Set the media filter's content @a order and @a order @a keyword either descending or ascending.
  97  *
  98  * @param[in] filter The handle to media filter
  99  * @param[in] order_type The search order type
 100  * @param[in] order_keyword The search order keyword
 101  * @param[in] collate_type The collate type for comparing two strings
 102  * @return return 0 on success, otherwise a negative error value.
 103  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 104  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 105  * @see media_filter_create()
 106  * @see media_filter_destroy()
 107  */
 108 int media_filter_set_order(filter_h filter, media_content_order_e order_type, const char *order_keyword, media_content_collation_e collate_type);
 109
 110 /**
 111  * @brief Gets the @a offset and @a count for the given @a filter used to limit number of items returned.
 112  *
 113  * @param[in] filter The handle to Media filter
 114  * @param[out] offset The start position of the given filter(Starting from zero)
 115  * @param[out] count The number of items to be searched with respect to offset
 116  * @return return 0 on success, otherwise a negative error value.
 117  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 118  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 119  * @see media_filter_create()
 120  * @see media_filter_destroy()
 121  */
 122 int media_filter_get_offset(filter_h filter, int *offset, int *count);
 123
 124 /**
 125  * @brief Get the @a condition for given @a filter.
 126  *
 127  * @remarks @a condition must be released with free() by you.
 128  * @param[in] filter The handle to media info filter
 129  * @param[out] condition The condition which is used WHERE clause on a query
 130  * @param[out] collate_type The collate type for comparing two strings
 131  * @return return 0 on success, otherwise a negative error value.
 132  * @retval #MEDIA_CONTENT_ERROR_NONE Successful
 133  * @retval #MEDIA_CONTENT_ERROR_OUT_OF_MEMORY Out of memory
 134  * @retval #MEDIA_CONTENT_ERROR_INVALID_PARAMETER Invalid parameter
 135  * @see media_filter_create()
 136  * @see media_filter_destroy()
 137  */
 138 int media_filter_get_condition(filter_h filter, char **condition, media_content_collation_e *collate_type);
 139
 140 /**
 141  * @brief Get the media filter's content @a order and @a order @a keyword either descending or ascending.
 142  *
 143  * @remarks @a order_keyword must be released with free() by you.
 144  * @param[in] filter The handle to media filter
 145  * @param[out] order_type The search order type
 146  * @param[out] order_keyword The search order keyword
 147  * @param[out] collate_type The collate type for comparing two strings
 148  * @return 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
 151  * @see media_filter_create()
 152  * @see media_filter_destroy()
 153  */
 154 int media_filter_get_order(filter_h filter, media_content_order_e* order_type, char **order_keyword, media_content_collation_e *collate_type);
 155
 156
 157 /**
 158  * @}
 159  */
 160
 161
 162 #ifdef __cplusplus
 163 }
 164 #endif /* __cplusplus */
 165
 166 #endif /* __TIZEN_MEDIA_FILTER_H__ */