inc/FSclAddressbookFilter.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   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  * @file                FSclAddressbookFilter.h
  18  * @brief               This is the header file for the %AddressbookFilter class.
  19  *
  20  * This header file contains the declarations of the %AddressbookFilter class.
  21  */
  22 #ifndef _FSCL_ADDRESSBOOK_FILTER_H_
  23 #define _FSCL_ADDRESSBOOK_FILTER_H_
  24
  25 #include <FBaseTypes.h>
  26 #include <FBaseObject.h>
  27 #include <FSclTypes.h>
  28
  29 namespace Tizen { namespace Base
  30 {
  31 class String;
  32 class DateTime;
  33 }}
  34
  35 namespace Tizen { namespace Social
  36 {
  37
  38 /**
  39  * @class          AddressbookFilter
  40  * @brief          This class represents the condition for searching the specific item on addressbook.
  41  *
  42  * @since       2.0
  43  *
  44  * @final          This class is not intended for extension.
  45  *
  46  * The %AddressbookFilter class represents the condition for searching the specific item on addressbook.
  47  * The type of the filter decides which item will be searched (such as addressbook, contacts, persons, categories). @n
  48  * The filter can consist of multiple filtering expressions and conjunctive operators.
  49  * A filtering expression consists of a filter property, comparison operator and value.
  50  * The filter property must be an element of the enumerator that corresponds with the type of the filter. @n
  51  * <table border=1>
  52  * <tr>
  53  *  <th> Filter type </th>
  54  *  <th> Filter Property </th>
  55  *  <th> Search result </th>
  56  * </tr>
  57  * <tr>
  58  *  <td> AB_FI_TYPE_ADDRESSBOOK </td>
  59  *  <td> AddressbookFilterProperty </td>
  60  *  <td> A list of Addressbook </td>
  61  * </tr>
  62  * <tr>
  63  *  <td> AB_FI_TYPE_PERSON </td>
  64  *  <td> PersonFilterProperty </td>
  65  *  <td> A list of Person </td>
  66  * </tr>
  67  * <tr>
  68  *  <td> AB_FI_TYPE_CONTACT </td>
  69  *  <td> ContactFilterProperty </td>
  70  *  <td> A list of Contact </td>
  71  * </tr>
  72  * <tr>
  73  *  <td> AB_FI_TYPE_CATEGORY </td>
  74  *  <td> CategoryFilterProperty </td>
  75  *  <td> A list of Category </td>
  76  * </tr>
  77  * <tr>
  78  *  <td> AB_FI_TYPE_PHONE_CONTACT </td>
  79  *  <td> PhoneContactFilterProperty </td>
  80  *  <td> A list of PhoneNumberContact </td>
  81  * </tr>
  82  * <tr>
  83  *  <td> AB_FI_TYPE_EMAIL_CONTACT </td>
  84  *  <td> EmailContactFilterProperty </td>
  85  *  <td> A list of EmailContact </td>
  86  * </tr>
  87  * </table>
  88  *
  89  * The following example demonstrates how to use the %AddressbookFilter class.
  90  * @code
  91   // Search condition: (addressbookId=0 OR addressbookId=1) AND (display name LIKE '%John%')
  92   AddressbookFilter subFilter(AB_FI_TYPE_CONTACT);
  93   subFilter.AppendInt(FI_CONJ_OP_NONE, CONTACT_FI_PR_ADDRESSBOOK_ID, FI_CMP_OP_EQUAL, 0);
  94   subFilter.AppendInt(FI_CONJ_OP_OR, CONTACT_FI_PR_ADDRESSBOOK_ID, FI_CMP_OP_EQUAL, 1);
  95
  96   AddressbookFilter mainFilter(AB_FI_TYPE_CONTACT);
  97   mainFilter.AppendFilter(FI_CONJ_OP_NONE, subFilter);
  98   mainFilter.AppendString(FI_CONJ_OP_AND, CONTACT_FI_PR_DISPLAY_NAME, FI_STR_OP_CONTAIN, L"John");
  99
 100   AddressbookManager* pAddressbookManager = AddressbookManager::GetInstance();
 101
 102   IList* pEventList = pAddressbookManager->SearchN(mainFilter, CONTACT_FI_PR_DISPLAY_NAME, SORT_ORDER_ASCENDING);
 103
 104  * @endcode
 105  */
 106 class _OSP_EXPORT_ AddressbookFilter
 107            : public Tizen::Base::Object
 108 {
 109 public:
 110         /**
 111          * Initializes an instance of %AddressbookFilter with the specified @c type.
 112          *
 113          * @since       2.0
 114          *
 115          * @param[in]    type                The type of the filter @n It decides the type of item to search.
 116          */
 117         AddressbookFilter(AddressbookFilterType type);
 118
 119         /**
 120          * This destructor overrides Tizen::Base::Object::~Object().
 121          *
 122          * @since       2.0
 123          */
 124         virtual ~AddressbookFilter(void);
 125
 126         /**
 127          * Checks whether the value of the specified instance is equal to the value of the current instance of Tizen::Base::Object.
 128          *
 129          * @since       2.0
 130          *
 131          * @return        @c true if the value of the specified instance of Tizen::Base::Object is equal to the value of the current instance of %Tizen::Base::Object, @n
 132          *                             else @c false
 133          * @param[in]    rhs                 An instance of Tizen::Base::Object to compare
 134          */
 135         virtual bool Equals(const Tizen::Base::Object& rhs) const;
 136
 137         /**
 138          * Gets the hash value of the current instance.
 139          *
 140          * @since       2.0
 141          *
 142          * @return        The hash value of the current instance
 143          */
 144         virtual int GetHashCode(void) const;
 145
 146         /**
 147          * Appends the filtering expression for the integer value. @n
 148          * Firstly, this method appends the conjunctive operator.
 149          * Then, this method puts the filtering expression in parentheses and appends it. @n
 150          * The filtering expression consists of the filter property, comparison operator, and value.
 151          * The specified @c filterProperty must be an element of the enumerator that corresponds with the type of this filter.
 152          *
 153          * @since       2.0
 154          *
 155          * @return    The error code
 156          * @param[in]   conjunctiveOperator     The conjunctive operator to append the filtering expression @n
 157          *                                      If there is no filtering expression or filter has been appended before, #FI_CONJ_OP_NONE must be used. Otherwise #FI_CONJ_OP_AND or #FI_CONJ_OP_OR can be used.
 158          * @param[in]   filterProperty          The filter property
 159          * @param[in]   comparisonOperator      The comparison operator
 160          * @param[in]   value                   The integer value for comparison
 161          * @exception   E_SUCCESS               The method is successful.
 162          * @exception   E_INVALID_ARG        Either of the following conditions has occurred: @n
 163          *                                              - The @c filterProperty is not an element of the enumerator that corresponds with the type of this filter. @n
 164          *                                              - The type of the @c filterProperty is not @c int. @n
 165          *                                              - The specified @c conjuctiveOperator is invalid.
 166          */
 167         result AppendInt(FilterConjunctiveOperator conjunctiveOperator, unsigned long filterProperty, FilterComparisonOperator comparisonOperator, int value);
 168
 169         /**
 170          * Appends the filtering expression for the @c bool value. @n
 171          * Firstly, this method appends the conjunctive operator.
 172          * Then, this method puts the filtering expression in parentheses and appends it. @n
 173          * The filtering expression consists of the filter property, comparison operator, and value.
 174          * The specified @c filterProperty must be an element of the enumerator that corresponds with the type of this filter.
 175          *
 176          * @since       2.0
 177          *
 178          * @return      The error code
 179          * @param[in]   conjunctiveOperator     The conjunctive operator to append the filtering expression @n
 180          *                                     If there is no filtering expression or filter has been appended before, #FI_CONJ_OP_NONE must be used. Otherwise #FI_CONJ_OP_AND or #FI_CONJ_OP_OR can be used.
 181          * @param[in]   filterProperty          The filter property
 182          * @param[in]   comparisonOperator      The comparison operator #FI_CMP_OP_EQUAL is only permitted
 183          * @param[in]   value                   The @c bool value for comparison
 184          * @exception   E_SUCCESS               The method is successful.
 185          * @exception   E_INVALID_ARG           Either of the following conditions has occurred:
 186          *                                              - The @c filterProperty is not an element of the enumerator that corresponds with the type of this filter.
 187          *                                              - The type of the @c filterProperty is not @c bool.
 188          *                                              - The @c comparisonOperator is no #FI_CMP_OP_EQUAL.
 189          *                                              - The specified @c conjuctiveOperator is invalid.
 190          * @remarks  If the filtering expression is appended firstly, the @c conjunctiveOperator is ignored.
 191          */
 192         result AppendBool(FilterConjunctiveOperator conjunctiveOperator, unsigned long filterProperty, FilterComparisonOperator comparisonOperator, bool value);
 193
 194         /**
 195          * Appends the filtering expression for the Tizen::Base::String value. @n
 196          * Firstly, this method appends the conjunctive operator.
 197          * Then, this method puts the filtering expression in parentheses and appends it. @n
 198          * The filtering expression consists of the filter property, comparison operator, and value.
 199          * The specified @c filterProperty must be an element of the enumerator that corresponds with the type of this filter.
 200          *
 201          * @since       2.0
 202          *
 203          * @return      The error code
 204          * @param[in]   conjunctiveOperator     The conjunctive operator to append the filtering expression @n
 205          *                                     If there is no filtering expression or filter has been appended before, #FI_CONJ_OP_NONE must be used. Otherwise #FI_CONJ_OP_AND or #FI_CONJ_OP_OR can be used.
 206          * @param[in]   filterProperty          The filter property
 207          * @param[in]   comparisonOperator      The comparison operator
 208          * @param[in]   value                   The Tizen::Base::String value for matching
 209          * @exception   E_SUCCESS               The method is successful.
 210          * @exception   E_INVALID_ARG           Either of the following conditions has occurred: @n
 211          *                                              - The @c filterProperty is not an element of the enumerator that corresponds with the type of this filter. @n
 212          *                                              - The type of the @c filterProperty is not Tizen::Base::String. @n
 213          *                                              - The specified @c conjuctiveOperator is invalid.
 214          */
 215         result AppendString(FilterConjunctiveOperator conjunctiveOperator, unsigned long filterProperty, FilterStringOperator comparisonOperator, const Tizen::Base::String& value);
 216
 217         /**
 218          * Appends the filter. @n
 219          * Firstly, this method appends the conjunctive operator.
 220          * Then, this method puts the filtering expressions of the specified filter in parentheses and appends it. @n
 221          * The type of the specified @c filter must be same with the type of this filter.
 222          *
 223          * @since       2.0
 224          *
 225          * @return      The error code
 226          * @param[in]   conjunctiveOperator     The conjunctive operator to append the filtering expression @n
 227          *                                     If there is no filtering expression or filter has been appended before, #FI_CONJ_OP_NONE must be used. Otherwise #FI_CONJ_OP_AND or #FI_CONJ_OP_OR can be used.
 228          * @param[in]   filter                  The filter to append
 229          * @exception   E_SUCCESS               The method is successful.
 230          * @exception   E_INVALID_ARG           Either of the following conditions has occurred: @n
 231          *                                             - The type of the specified @c filter is not same with the type of this filter. @n
 232          *                                             - The specified @c filter is empty. @n
 233          *                                             - The specified @c conjuctiveOperator is invalid.
 234          */
 235         result AppendFilter(FilterConjunctiveOperator conjunctiveOperator, const AddressbookFilter& filter);
 236
 237 private:
 238         /*
 239          * This default constructor is intentionally declared as private so that only the platform can create an instance.
 240          *
 241          * @since       2.0
 242          */
 243         AddressbookFilter(void);
 244
 245         /**
 246          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 247          *
 248          * @since       2.0
 249          */
 250         AddressbookFilter(const AddressbookFilter& rhs);
 251
 252         /**
 253          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 254          *
 255          * @since       2.0
 256          */
 257         AddressbookFilter & operator =(const AddressbookFilter & rhs);
 258
 259 private:
 260            friend class _AddressbookFilterImpl;
 261            class _AddressbookFilterImpl* __pAddressbookFilterImpl;
 262 };         // AddressbookFilter
 263
 264 }} // Tizen::Social
 265
 266 #endif // _FSCL_ADDRESSBOOK_FILTER_H_