include/contacts_filter.h

   1 /*
   2  * Contacts Service
   3  *
   4  * Copyright (c) 2010 - 2015 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  */
  19
  20
  21 #ifndef __TIZEN_SOCIAL_CONTACTS_FILTER_H__
  22 #define __TIZEN_SOCIAL_CONTACTS_FILTER_H__
  23
  24
  25 #ifdef __cplusplus
  26 extern "C"
  27 {
  28 #endif
  29
  30
  31 /**
  32  * @file contacts_filter.h
  33  */
  34
  35
  36 /**
  37  * @ingroup CAPI_SOCIAL_CONTACTS_SVC_MODULE
  38  * @defgroup CAPI_SOCIAL_CONTACTS_SVC_FILTER_MODULE Filter
  39  * @brief The contacts Filter API provides the set of definitions and interfaces that enable application developers to make filters to set query.
  40  * @section CAPI_SOCIAL_CONTACTS_SVC_CONTACTS_FILTER_HEADER Required Header
  41  *          \#include <contacts.h>
  42  * <BR>
  43  * @{
  44  */
  45
  46
  47 /**
  48  * @brief Enumeration for Contacts match string flags.
  49  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  50  */
  51 typedef enum {
  52         CONTACTS_MATCH_EXACTLY, /**< Full string, case-sensitive */
  53         CONTACTS_MATCH_FULLSTRING, /**< Full string, case-insensitive */
  54         CONTACTS_MATCH_CONTAINS, /**< Sub string, case-insensitive */
  55         CONTACTS_MATCH_STARTSWITH, /**< Start with, case-insensitive */
  56         CONTACTS_MATCH_ENDSWITH, /**< End with, case-insensitive */
  57         CONTACTS_MATCH_EXISTS /**< IS NOT NULL */
  58 } contacts_match_str_flag_e;
  59
  60
  61 /**
  62  * @brief Enumeration for Contacts match int flags.
  63  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  64  */
  65 typedef enum {
  66         CONTACTS_MATCH_EQUAL, /**< '=' */
  67         CONTACTS_MATCH_GREATER_THAN, /**< '>' */
  68         CONTACTS_MATCH_GREATER_THAN_OR_EQUAL, /**< '>=' */
  69         CONTACTS_MATCH_LESS_THAN, /**< '<' */
  70         CONTACTS_MATCH_LESS_THAN_OR_EQUAL, /**< '<=' */
  71         CONTACTS_MATCH_NOT_EQUAL, /**< '<>', this flag can yield poor performance */
  72         CONTACTS_MATCH_NONE, /**< IS NULL */
  73 } contacts_match_int_flag_e;
  74
  75
  76 /**
  77  * @brief Enumeration for Contacts filter operators.
  78  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  79  */
  80 typedef enum {
  81         CONTACTS_FILTER_OPERATOR_AND, /**< AND */
  82         CONTACTS_FILTER_OPERATOR_OR /**< OR */
  83 } contacts_filter_operator_e;
  84
  85
  86 /**
  87  * @brief Creates a filter.
  88  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
  89  * @remarks You must release @a filter using contacts_filter_destroy().
  90  * @param[in] view_uri The view URI of a filter
  91  * @param[out] filter The filter handle
  92  * @return @c 0 on success,
  93  *         otherwise a negative error value
  94  * @retval #CONTACTS_ERROR_NONE Successful
  95  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
  96  * @retval #CONTACTS_ERROR_OUT_OF_MEMORY Out of memory
  97  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
  98  * @pre contacts_connect() should be called to initialize
  99  * @see contacts_filter_destroy()
 100  */
 101 int contacts_filter_create(const char *view_uri, contacts_filter_h *filter);
 102
 103
 104 /**
 105  * @brief Destroys a filter.
 106  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 107  * @param[in] filter The filter handle
 108  * @return @c 0 on success,
 109  *         otherwise a negative error value
 110  * @retval #CONTACTS_ERROR_NONE Successful
 111  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 112  * @see contacts_filter_create()
 113  */
 114 int contacts_filter_destroy(contacts_filter_h filter);
 115
 116
 117 /**
 118  * @brief Adds a condition for a string type property.
 119  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 120  * @param[in] filter The filter handle
 121  * @param[in] property_id The property ID to add a condition
 122  * @param[in] match The match flag
 123  * @param[in] match_value The match value
 124  * @return @c 0 on success,
 125  *         otherwise a negative error value
 126  * @retval #CONTACTS_ERROR_NONE Successful
 127  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 128  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 129  * @see contacts_filter_add_operator()
 130  */
 131 int contacts_filter_add_str(contacts_filter_h filter, unsigned int property_id, contacts_match_str_flag_e match, const char *match_value);
 132
 133
 134 /**
 135  * @brief Adds a condition for an integer type property.
 136  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 137  * @param[in] filter The filter handle
 138  * @param[in] property_id The property ID to add a condition
 139  * @param[in] match The match flag
 140  * @param[in] match_value The match value
 141  * @return @c 0 on success,
 142  *         otherwise a negative error value
 143  * @retval #CONTACTS_ERROR_NONE Successful
 144  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 145  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 146  * @see contacts_filter_add_operator()
 147  */
 148 int contacts_filter_add_int(contacts_filter_h filter, unsigned int property_id, contacts_match_int_flag_e match, int match_value);
 149
 150
 151 /**
 152  * @brief Adds a condition for a long int type property.
 153  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 154  * @param[in] filter The filter handle
 155  * @param[in] property_id The property ID to add a condition
 156  * @param[in] match The match flag
 157  * @param[in] match_value The match value
 158  * @return @c 0 on success,
 159  *         otherwise a negative error value
 160  * @retval #CONTACTS_ERROR_NONE Successful
 161  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 162  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 163  * @see contacts_filter_add_operator()
 164  */
 165 int contacts_filter_add_lli(contacts_filter_h filter, unsigned int property_id, contacts_match_int_flag_e match, long long int match_value);
 166
 167
 168 /**
 169  * @brief Adds a condition for a double type property.
 170  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 171  * @param[in] filter The filter handle
 172  * @param[in] property_id The property ID to add a condition
 173  * @param[in] match The match flag
 174  * @param[in] match_value The match value
 175  * @return @c 0 on success,
 176  *         otherwise a negative error value
 177  * @retval #CONTACTS_ERROR_NONE Successful
 178  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 179  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 180  * @see contacts_filter_add_operator()
 181  */
 182 int contacts_filter_add_double(contacts_filter_h filter, unsigned int property_id, contacts_match_int_flag_e match, double match_value);
 183
 184
 185 /**
 186  * @brief Adds a condition for a boolean type property.
 187  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 188  * @param[in] filter The filter handle
 189  * @param[in] property_id The property ID to add a condition
 190  * @param[in] match_value The match value
 191  * @return @c 0 on success,
 192  *         otherwise a negative error value
 193  * @retval #CONTACTS_ERROR_NONE Successful
 194  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 195  * @retval #CONTACTS_ERROR_NOT_SUPPORTED Not supported
 196  * @see contacts_filter_add_operator()
 197  */
 198 int contacts_filter_add_bool(contacts_filter_h filter, unsigned int property_id, bool match_value);
 199
 200
 201 /**
 202  * @brief Adds an operator between conditions.
 203  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 204  * @param[in] filter The filter handle
 205  * @param[in] operator_type The operator type
 206  * @return @c 0 on success,
 207  *         otherwise a negative error value
 208  * @retval #CONTACTS_ERROR_NONE Successful
 209  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 210  * @see contacts_filter_add_str()
 211  * @see contacts_filter_add_int()
 212  * @see contacts_filter_add_bool()
 213  */
 214 int contacts_filter_add_operator(contacts_filter_h filter, contacts_filter_operator_e operator_type);
 215
 216
 217 /**
 218  * @brief Adds a filter to a given filter.
 219  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 3.0 @endif
 220  * @param[in] parent_filter The parent filter handle
 221  * @param[in] child_filter The child filter handle
 222  * @return @c 0 on success,
 223  *         otherwise a negative error value
 224  * @retval #CONTACTS_ERROR_NONE Successful
 225  * @retval #CONTACTS_ERROR_INVALID_PARAMETER Invalid parameter
 226  * @see contacts_filter_add_operator()
 227  */
 228 int contacts_filter_add_filter(contacts_filter_h parent_filter, contacts_filter_h child_filter);
 229
 230
 231 /**
 232  * @}
 233  */
 234
 235
 236 #ifdef __cplusplus
 237 }
 238 #endif
 239
 240
 241 #endif /* __TIZEN_SOCIAL_CONTACTS_FILTER_H__ */
 242