inc/FSclCalendarbookFilter.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                        FSclCalendarbookFilter.h
  18  * @brief               This is the header file for the %CalendarbookFilter class.
  19  *
  20  * This header file contains the declarations of the %CalendarbookFilter class.
  21  */
  22 #ifndef _FSCL_CALENDARBOOK_FILTER_H_
  23 #define _FSCL_CALENDARBOOK_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       CalendarbookFilter
  40  * @brief       This class represents the condition for searching the specific item on calendarbook.
  41  *
  42  * @since       2.0
  43  *
  44  * @final               This class is not intended for extension.
  45  *
  46  * The %CalendarbookFilter class represents the condition for searching the specific item on calendarbook.
  47  * The type of the filter decides which item will be searched (such as events, to-dos, calendars, all day event instances, or non-all day event instances). @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> CB_FI_TYPE_EVENT </td>
  59  * <td> EventFilterProperty </td>
  60  * <td> A list of CalEvent </td>
  61  * </tr>
  62  * <tr>
  63  * <td> CB_FI_TYPE_TODO </td>
  64  * <td> TodoFilterProperty </td>
  65  * <td> A list of CalTodo </td>
  66  * </tr>
  67  * <tr>
  68  * <td> CB_FI_TYPE_CALENDAR </td>
  69  * <td> CalendarFilterProperty </td>
  70  * <td> A list of Calendar </td>
  71  * </tr>
  72  * <tr>
  73  * <td> CB_FI_TYPE_ALL_DAY_EVENT_INSTANCE </td>
  74  * <td> EventInstanceFilterProperty </td>
  75  * <td> A list of CalEventInstance </td>
  76  * </tr>
  77  * <tr>
  78  * <td> CB_FI_TYPE_NON_ALL_DAY_EVENT_INSTANCE </td>
  79  * <td> EventInstanceFilterProperty </td>
  80  * <td> A list of CalEventInstance </td>
  81  * </tr>
  82  * </table>
  83  *
  84  * The following example demonstrates how to use the %CalendarbookFilter class.
  85  * @code
  86  *
  87         //search condition: (calendarId=3 OR calendarId=4) AND (subject LIKE '%meeting%')
  88         CalendarbookFilter subFilter(CB_FI_TYPE_EVENT);
  89         subFilter.AppendInt(FI_CONJ_OP_NONE, EVENT_FI_PR_CALENDAR_ID, FI_CMP_OP_EQUAL, 3);
  90         subFilter.AppendInt(FI_CONJ_OP_OR, EVENT_FI_PR_CALENDAR_ID, FI_CMP_OP_EQUAL, 4);
  91
  92         CalendarbookFilter mainFilter(CB_FI_TYPE_EVENT);
  93         mainFilter.AppendFilter(FI_CONJ_OP_NONE, subFilter);
  94         mainFilter.AppendString(FI_CONJ_OP_AND, EVENT_FI_PR_SUBJECT, FI_STR_OP_CONTAIN, L"meeting");
  95
  96         Calendarbook calendarbook;
  97         calendarbook.Construct();
  98         IList* pEventList = calendarbook.SearchN(mainFilter, EVENT_FI_PR_SUBJECT, SORT_ORDER_ASCENDING);
  99
 100  * @endcode
 101  */
 102 class _OSP_EXPORT_ CalendarbookFilter
 103         : public Tizen::Base::Object
 104 {
 105 public:
 106         /**
 107          * Initializes an instance of %CalendarbookFilter with the specified @c type.
 108          *
 109          * @since       2.0
 110          *
 111          * @param[in]   type                    The type of the filter @n It decides the type of item to search.
 112          */
 113         explicit CalendarbookFilter(CalendarbookFilterType type);
 114
 115         /**
 116          * This destructor overrides Tizen::Base::Object::~Object().
 117          *
 118          * @since       2.0
 119          */
 120         virtual ~CalendarbookFilter(void);
 121
 122         /**
 123          * Checks whether the value of the specified instance is equal to the value of the current instance of Tizen::Base::Object.
 124          *
 125          * @since       2.0
 126          *
 127          * @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
 128          *                                      else @c false
 129          * @param[in]   rhs                     An instance of Tizen::Base::Object to compare
 130          */
 131         virtual bool Equals(const Tizen::Base::Object& rhs) const;
 132
 133         /**
 134          * Gets the hash value of the current instance.
 135          *
 136          * @since       2.0
 137          *
 138          * @return              The hash value of the current instance
 139          */
 140         virtual int GetHashCode(void) const;
 141
 142         /**
 143          * Appends the filtering expression for the integer value. @n
 144          * Firstly, this method appends the conjunctive operator.
 145          * Then, this method puts the filtering expression in parentheses and appends it. @n
 146          * The filtering expression consists of the filter property, comparison operator, and value.
 147          * The specified @c filterProperty must be an element of the enumerator that corresponds with the type of this filter.
 148          *
 149          * @since       2.0
 150          *
 151          * @return              The error code
 152          * @param[in]   conjunctiveOperator             The conjunctive operator to append the filtering expression @n
 153          *                                                                              If there is no filtering expression or filter has been appended before, FI_CONJ_OP_NON must be used. Otherwise FI_CONJ_OP_AND or FI_CONJ_OP_OR can be used.
 154          * @param[in]   filterProperty          The filter property
 155          * @param[in]   comparisonOperator              The comparison operator
 156          * @param[in]   value           The integer value for comparison
 157          * @exception   E_SUCCESS                               The method is successful.
 158          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n
 159          *                                              - The @c filterProperty is not an element of the enumerator that corresponds with the type of this filter. @n
 160          *                                              - The @c filterProperty is not for integer value. @n
 161          *                                              - The specified @c conjunctiveOperator is invalid.
 162          */
 163         result AppendInt(FilterConjunctiveOperator conjunctiveOperator, unsigned long filterProperty, FilterComparisonOperator comparisonOperator, int value);
 164
 165         /**
 166          * Appends the filtering expression for the double value. @n
 167          * Firstly, this method appends the conjunctive operator.
 168          * Then, this method puts the filtering expression in parentheses and appends it. @n
 169          * The filtering expression consists of the filter property, comparison operator, and value.
 170          * The specified @c filterProperty must be an element of the enumerator that corresponds with the type of this filter.
 171          *
 172          * @since       2.0
 173          *
 174          * @return              The error code
 175          * @param[in]   conjunctiveOperator             The conjunctive operator to append the filtering expression @n
 176          *                                                                              If there is no filtering expression or filter has been appended before, FI_CONJ_OP_NON must be used. Otherwise FI_CONJ_OP_AND or FI_CONJ_OP_OR can be used.
 177          * @param[in]   filterProperty          The filter property
 178          * @param[in]   comparisonOperator              The comparison operator
 179          * @param[in]   value           The double value for comparison
 180          * @exception   E_SUCCESS                               The method is successful.
 181          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n
 182          *                                              - The @c filterProperty is not an element of the enumerator that corresponds with the type of this filter. @n
 183          *                                              - The @c filterProperty is not for double value. @n
 184          *                                              - The specified @c conjunctiveOperator is invalid.
 185          */
 186         result AppendDouble(FilterConjunctiveOperator conjunctiveOperator, unsigned long filterProperty, FilterComparisonOperator comparisonOperator, double value);
 187
 188         /**
 189          * Appends the filtering expression for the bool value. @n
 190          * Firstly, this method appends the conjunctive operator.
 191          * Then, this method puts the filtering expression in parentheses and appends it. @n
 192          * The filtering expression consists of the filter property, comparison operator, and value.
 193          * The specified @c filterProperty must be an element of the enumerator that corresponds with the type of this filter.
 194          *
 195          * @since       2.0
 196          *
 197          * @return              The error code
 198          * @param[in]   conjunctiveOperator             The conjunctive operator to append the filtering expression @n
 199          *                                                                              If there is no filtering expression or filter has been appended before, FI_CONJ_OP_NON must be used. Otherwise FI_CONJ_OP_AND or FI_CONJ_OP_OR can be used.
 200          * @param[in]   filterProperty          The filter property
 201          * @param[in]   comparisonOperator              The comparison operator FILTER_COMPARISON_OPERATOR_EQUAL is only permitted
 202          * @param[in]   value           The bool value for comparison
 203          * @exception   E_SUCCESS                               The method is successful.
 204          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n
 205          *                                              - The @c filterProperty is not an element of the enumerator that corresponds with the type of this filter. @n
 206          *                                              - The @c filterProperty is not for bool value. @n
 207          *                                              - The specified @c conjunctiveOperator is invalid.
 208          */
 209         result AppendBool(FilterConjunctiveOperator conjunctiveOperator, unsigned long filterProperty, FilterComparisonOperator comparisonOperator, bool value);
 210
 211         /**
 212          * Appends the filtering expression for the Tizen::Base::DateTime value. @n
 213          * Firstly, this method appends the conjunctive operator.
 214          * Then, this method puts the filtering expression in parentheses and appends it. @n
 215          * The filtering expression consists of the filter property, comparison operator, and value.
 216          * The specified @c filterProperty must be an element of the enumerator that corresponds with the type of this filter.
 217          *
 218          * @since       2.0
 219          *
 220          * @return              The error code
 221          * @param[in]   conjunctiveOperator             The conjunctive operator to append the filtering expression @n
 222          *                                                                              If there is no filtering expression or filter has been appended before, FI_CONJ_OP_NON must be used. Otherwise FI_CONJ_OP_AND or FI_CONJ_OP_OR can be used.
 223          * @param[in]   filterProperty          The filter property
 224          * @param[in]   comparisonOperator              The comparison operator
 225          * @param[in]   value           The Tizen::Base::DateTime value for comparison. @n Any value with a unit that is less than a second is ignored.
 226          * @exception   E_SUCCESS                               The method is successful.
 227          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred:
 228          *                                              - The @c filterProperty is not an element of the enumerator that corresponds with the type of this filter.
 229          *                                              - The @c filterProperty is not for Tizen::Base::DateTime value.
 230          *                                              - The specified @c conjunctiveOperator is invalid.
 231          *                                              - The specified @c value is out of the valid range.
 232          */
 233         result AppendDateTime(FilterConjunctiveOperator conjunctiveOperator, unsigned long filterProperty, FilterComparisonOperator comparisonOperator, const Tizen::Base::DateTime& value);
 234
 235         /**
 236          * Appends the filtering expression for the Tizen::Base::String value. @n
 237          * Firstly, this method appends the conjunctive operator.
 238          * Then, this method puts the filtering expression in parentheses and appends it. @n
 239          * The filtering expression consists of the filter property, comparison operator, and value.
 240          * The specified @c filterProperty must be an element of the enumerator that corresponds with the type of this filter.
 241          *
 242          * @since       2.0
 243          *
 244          * @return              The error code
 245          * @param[in]   conjunctiveOperator             The conjunctive operator to append the filtering expression @n
 246          *                                                                              If there is no filtering expression or filter has been appended before, FI_CONJ_OP_NON must be used. Otherwise FI_CONJ_OP_AND or FI_CONJ_OP_OR can be used.
 247          * @param[in]   filterProperty          The filter property
 248          * @param[in]   comparisonOperator              The comparison operator
 249          * @param[in]   value           The Tizen::Base::String value for matching
 250          * @exception   E_SUCCESS                               The method is successful.
 251          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n
 252          *                                              - The @c filterProperty is not an element of the enumerator that corresponds with the type of this filter. @n
 253          *                                              - The @c filterProperty is not for Tizen::Base::String value. @n
 254          *                                              - The specified @c conjunctiveOperator is invalid.
 255          */
 256         result AppendString(FilterConjunctiveOperator conjunctiveOperator, unsigned long filterProperty, FilterStringOperator comparisonOperator, const Tizen::Base::String& value);
 257
 258         /**
 259          * Appends the filter. @n
 260          * Firstly, this method appends the conjunctive operator.
 261          * Then, this method puts the filtering expressions of the specified filter in parentheses and appends it. @n
 262          * The type of the specified @c filter must be same with the type of this filter.
 263          *
 264          * @since       2.0
 265          *
 266          * @return              The error code
 267          * @param[in]   conjunctiveOperator             The conjunctive operator to append the filtering expression @n
 268          *                                                                              If there is no filtering expression or filter has been appended before, FI_CONJ_OP_NON must be used. Otherwise FI_CONJ_OP_AND or FI_CONJ_OP_OR can be used.
 269          * @param[in]   filter                  The filter to append
 270          * @exception   E_SUCCESS                               The method is successful.
 271          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n
 272          *                                              - The type of the specified @c filter is not same with the type of this filter. @n
 273          *                                              - The specified @c filter is empty. @n
 274          *                                              - The specified @c conjunctiveOperator is invalid.
 275          */
 276         result AppendFilter(FilterConjunctiveOperator conjunctiveOperator, const CalendarbookFilter& filter);
 277
 278 private:
 279         /*
 280          * This default constructor is intentionally declared as private so that only the platform can create an instance.
 281          *
 282          * @since       2.0
 283          */
 284         CalendarbookFilter(void);
 285
 286         /*
 287          * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 288          *
 289          * @since       2.0
 290          */
 291         CalendarbookFilter(const CalendarbookFilter& rhs);
 292
 293         /*
 294          * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 295          *
 296          * @since       2.0
 297          */
 298         CalendarbookFilter & operator =(const CalendarbookFilter & rhs);
 299
 300 private:
 301         friend class _CalendarbookFilterImpl;
 302         class _CalendarbookFilterImpl* __pCalendarbookFilterImpl;
 303 };              // CalendarbookFilter
 304
 305 }} // Tizen::Social
 306
 307 #endif // _FSCL_CALENDARBOOK_FILTER_H_