inc/FSclAddressbookFilter.h

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