inc/FSclRecurrence.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        FSclRecurrence.h
  19  * @brief       This is the header file for the %Recurrence class.
  20  *
  21  * This header file contains the declarations of the %Recurrence class.
  22  */
  23 #ifndef _FSCL_RECURRENCE_H_
  24 #define _FSCL_RECURRENCE_H_
  25
  26 #include <FBaseObject.h>
  27 #include <FBaseDataType.h>
  28 #include <FBaseColIListT.h>
  29 #include <FBaseColArrayListT.h>
  30 #include <FBaseDateTime.h>
  31 #include <FSclTypes.h>
  32
  33 namespace Tizen { namespace Base { namespace Collection
  34 {
  35 class IList;
  36 }}}
  37
  38 namespace Tizen { namespace Social
  39 {
  40
  41 /**
  42  * @class       Recurrence
  43  * @brief       This class provides methods to access the information of a %Recurrence.
  44  *
  45  * @since       2.0
  46  *
  47  * @final       This class is not intended for extension.
  48  *
  49  * The %Recurrence class provides methods to access the information of a %Recurrence.
  50  *      A CalEvent can be made a recurring event using this class. To set or get the information of a recurrence (such as start time and recurrence
  51  *                      pattern) use the methods of this class. The recurrence date is the start date of the CalEvent, if they do not match.
  52  *
  53  *
  54  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/social/recurrence_reminder_sensitivity.htm">Recurrence, Reminder, and Sensitivity Properties of Calendar Items</a>.
  55  *
  56  * @see         CalEvent::SetRecurrence()
  57  *
  58  * The following examples demonstrate how to use the %Recurrence class.
  59  *
  60  * 1. Repeat daily for 10 occurrences:
  61  *
  62  * @code
  63
  64         void
  65         MyRecurrence::RepeatDayily10(void)
  66         {
  67                 result r;
  68                 Recurrence* pRecurrence = new Recurrence();
  69                 if (IsFailed(GetLastResult()) || pRecurrence == null)
  70                 {
  71                         AppLogException("Create instance has failed");
  72                 }
  73                 pRecurrence->SetFrequency(FREQ_DAILY);
  74                 r = pRecurrence->SetCounts(10);
  75                 if (IsFailed(r))
  76                 {
  77                         AppLogException("Set counts has failed");
  78                 }
  79         }
  80
  81  * @endcode
  82  * 2. Repeat weekly until May 4, 2009:
  83  *
  84  * @code
  85
  86         void
  87         MyRecurrence::RepeatDayilyUntil(void)
  88         {
  89                 result r;
  90                 Recurrence* pRecurrence = new Recurrence();
  91                 if (IsFailed(GetLastResult()) || pRecurrence == null)
  92                 {
  93                         AppLogException("Create instance has failed");
  94                 }
  95                 DateTime until;
  96                 r = until.SetValue(2009, 5, 4);
  97                 if (IsFailed(r))
  98                 {
  99                         AppLogException("Set date/time has failed");
 100                 }
 101
 102                 pRecurrence->SetFrequency(FREQ_WEEKLY);
 103                 r = pRecurrence->SetUntil(&until);
 104                 if (IsFailed(r))
 105                 {
 106                         AppLogException("Set until has failed");
 107                 }
 108         }
 109
 110  * @endcode
 111  *
 112  * 3. Repeat bi-weekly on Tuesday and Thursday until May 4, 2009:
 113  * @code
 114
 115         void
 116         MyRecurrence::RepeatByWeeklyUntil(void)
 117         {
 118                 result r;
 119                 Recurrence* pRecurrence = new Recurrence();
 120                 if (IsFailed(GetLastResult()) || pRecurrence == null)
 121                 {
 122                         AppLogException("Create instance has failed");
 123                 }
 124
 125                 DateTime until;
 126                 r = until.SetValue(2009, 5, 4);
 127                 if (IsFailed(r))
 128                 {
 129                         AppLogException("Set date/time has failed");
 130                 }
 131
 132                 pRecurrence->SetFrequency(FREQ_WEEKLY);
 133                 r = pRecurrence->SetInterval(2);
 134                 if (IsFailed(r))
 135                 {
 136                         AppLogException("Set interval has failed");
 137                 }
 138
 139                 r = pRecurrence->SetDayOfWeek(CAL_TUESDAY | CAL_THURSDAY);
 140                 if (IsFailed(r))
 141                 {
 142                         AppLogException("Set day of week has failed");
 143                 }
 144
 145                 r = pRecurrence->SetUntil(&until);
 146                 if (IsFailed(r))
 147                 {
 148                         AppLogException("Set until has failed");
 149                 }
 150         }
 151  * @endcode
 152  *
 153  * 4. Repeat monthly on the first Thursday for 10 occurrences. The week starts on Monday:
 154  * @code
 155
 156         void
 157         MyRecurrence::RepeatMonthlyUntil(void)
 158         {
 159                 result r;
 160                 Recurrence* pRecurrence = new Recurrence();
 161                 if (IsFailed(GetLastResult()) || pRecurrence == null)
 162                 {
 163                         AppLogException("Create instance has failed");
 164                 }
 165
 166                 pRecurrence->SetFrequency(FREQ_MONTHLY);
 167
 168                 r = pRecurrence->SetWeekStart(CAL_MONDAY);
 169                 if (IsFailed(r))
 170                 {
 171                         AppLogException("Set week start has failed");
 172                 }
 173
 174                 r = pRecurrence->SetDayOfWeek(CAL_THURSDAY);
 175                 if (IsFailed(r))
 176                 {
 177                         AppLogException("Set day of the week has failed");
 178                 }
 179
 180                 r = pRecurrence->SetWeekOfMonth(1);
 181                 if (IsFailed(r))
 182                 {
 183                         AppLogException("Set week of month has failed");
 184                 }
 185
 186                 r = pRecurrence->SetCounts(10);
 187                 if (IsFailed(r))
 188                 {
 189                         AppLogException("Set counts has failed");
 190                 }
 191         }
 192
 193  * @endcode
 194  *
 195  */
 196 class _OSP_EXPORT_ Recurrence
 197         : public Tizen::Base::Object
 198 {
 199 public:
 200         /**
 201          * This is the default constructor for this class. @n
 202          * This constructor sets the default values. The recurrence type is daily and recurrence interval is @c 1. @n
 203          * The week start day is #CAL_MONDAY. The recurrence count is @c 1.
 204          *
 205          * @since       2.0
 206          */
 207         Recurrence(void);
 208
 209         /**
 210          * Copying of objects using this copy constructor is allowed.
 211          *
 212          * @since       2.0
 213          *
 214          * @param[in]   rhs             An instance of %Recurrence
 215          */
 216         Recurrence(const Recurrence& rhs);
 217
 218         /**
 219          * This destructor overrides Tizen::Base::Object::~Object().
 220          *
 221          * @since       2.0
 222          */
 223         virtual ~Recurrence(void);
 224
 225         /**
 226          * Compares the input Tizen::Base::Object with the calling %Recurrence instance.
 227          *
 228          * @since       2.0
 229          *
 230          * @return              @c true if the input object equals the calling %Recurrence instance, @n
 231          *                              else @c false
 232          * @param[in]   rhs     The object instance to compare with the calling object
 233          * @see                 GetHashCode()
 234          */
 235         virtual bool Equals(const Tizen::Base::Object& rhs) const;
 236
 237         /**
 238          * Gets the hash value of the current instance.
 239          *
 240          * @since       2.0
 241          *
 242          * @return              The hash value of the current instance
 243          */
 244         virtual int GetHashCode(void) const;
 245
 246         /**
 247          * Gets the recurrence frequency type.
 248          *
 249          * @since       2.0
 250          *
 251          * @return              A reference to one of the @c RecurFrequency enumeration values, @n
 252          *                              else #FREQ_DAILY if this property is not set
 253          */
 254         RecurFrequency GetFrequency(void) const;
 255
 256         /**
 257          * Gets the recurrence interval. @n
 258          * This represents the number of units between two recurrences. @n
 259          * If the frequency is weekly and the recurrence interval is set to @c 2, the event occurs every two weeks.
 260          *
 261          * @since       2.0
 262          *
 263          * @return              An integer value representing the recurrence interval, @n
 264          *                              else @c 1 if this property is not set
 265          */
 266         int GetInterval(void) const;
 267
 268         /**
 269          * Gets the end date and time of recurrence.
 270          *
 271          * @since       2.0
 272          *
 273          * @return              An instance of Tizen::Base::DateTime representing the end date and time
 274          * @remarks             If this method returns @c null, get the recurrence counts using the GetCounts() method.
 275          *
 276          */
 277         const Tizen::Base::DateTime* GetUntil(void) const;
 278
 279         /**
 280          * Gets the number of times the event recurs.
 281          *
 282          * @since       2.0
 283          *
 284          * @return              An integer value representing the number of recurrences
 285          * @remarks             If this method returns @c 0, get the recurrence end date and time using the GetUntil() method.
 286          *
 287          */
 288         int GetCounts(void) const;
 289
 290         /**
 291          * Gets the first day of the week. @n
 292          * The default value is #CAL_MONDAY.
 293          *
 294          * @since       2.0
 295          *
 296          * @return              An integer value representing the first day of the week
 297          *
 298          */
 299         CalDayOfWeek GetWeekStart(void) const;
 300
 301         /**
 302          * Gets the day of the week when the event should recur. @n
 303          * The default value is @c 0.
 304          *
 305          * @since       2.0
 306          *
 307          * @return              An integer value representing the CalDayofWeek
 308          * @remarks             The Frequency property must be obtained. If the frequency is #FREQ_WEEKLY, the return value may be a combination of days,
 309          *                              like #CAL_MONDAY| #CAL_THURSDAY.
 310          *
 311          */
 312         int GetDayOfWeek(void) const;
 313
 314         /**
 315          * Gets the day of the month. @n
 316          * The default value is @c 0.
 317          *
 318          * @since       2.0
 319          *
 320          * @return              An integer value between @c 1 ~ @c 31 representing the day of a month
 321          * @remarks             The Frequency property must be obtained.
 322          */
 323         int GetDayOfMonth(void) const;
 324
 325         /**
 326          * Gets the week of the month. @n
 327          * The default value is @c 0.
 328          *
 329          * @since       2.0
 330          *
 331          * @return              An integer value between @c 1 ~ @c 5 representing the week of a month
 332          * @remarks             The Frequency property must be obtained.
 333          *
 334          */
 335         int GetWeekOfMonth(void) const;
 336
 337         /**
 338          * Gets the month of the year. @n
 339          * The default value is @c 0.
 340          *
 341          * @since       2.0
 342          *
 343          * @return              An integer value between @c 1 ~ @c 12 representing the month of a year
 344          * @remarks             The Frequency property must be obtained.
 345          *
 346          */
 347         int GetMonthOfYear(void) const;
 348
 349         /**
 350          * Sets a recurring frequency type among specific types (daily, weekly, monthly, and yearly). @n
 351          * This property must be set before setting the day of recurrence. After setting the frequency, other properties are reset to default values. @n
 352          * For weekly, the day of week must be set. @n
 353          * For monthly, the day of the week and the week of the month must be set. @n
 354          * For yearly, either the day of the month and the month of the year, or the day of the week, the week of the month, and the month of the year must be set.
 355          *
 356          * @since       2.0
 357          *
 358          * @param[in]   type    The recurrence type
 359          *
 360          */
 361         void SetFrequency(RecurFrequency type);
 362
 363         /**
 364          * Sets the interval of recurrence. @n
 365          * If the frequency is weekly and the recurrence interval is set to 2, the event occurs every two weeks.
 366          *
 367          * @if OSPCOMPAT
 368          * @brief <i> [Compatibility] </i>
 369          * @endif
 370          * @since       2.0
 371          * @if OSPCOMPAT
 372          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 373      *                                  For more information, see @ref CompRecurrenceSetIntervalPage "here".
 374      * @endif
 375          *
 376          * @return              An error code
 377          * @param[in]   interval                The interval of recurrence
 378          * @exception   E_SUCCESS               The method is successful.
 379          * @exception   E_INVALID_ARG   The specified @c interval is less than @c 1.
 380          */
 381         result SetInterval(int interval);
 382
 383         /**
 384          * @if OSPCOMPAT
 385          * @page        CompRecurrenceSetIntervalPage Compatibility for SetInterval()
 386          * @section     CompRecurrenceSetIntervalPageIssueSection Issues
 387          *          Implementing this method in OSP compatible applications has the following issues:   @n
 388          *                      -# If the value of the interval to be set is greater than 255, E_INVALID_ARG is returned.
 389          *
 390          * @section     CompRecurrenceSetIntervalPageSolutionSection Resolutions
 391          *                      This issue has been resolved in Tizen.  @n
 392          *                      -# There is no limit for the value of the interval.
 393          * @endif
 394          */
 395
 396         /**
 397          * Sets the end date of the recurrence. @n
 398          * If you want to set the event to have no end date, set the maximum date and time using the Tizen::Base::DateTime::GetMaxValue() method.
 399          *
 400          * @since       2.0
 401          *
 402          * @return              An error code
 403          * @param[in]   pUntil                  The end date and time
 404          * @exception   E_SUCCESS               The method is successful.
 405          * @exception   E_INVALID_ARG           The @c pUntil is not in a valid range. @n
 406          *                                      The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().
 407          * @remarks             Either the until or count properties may be set. @n
 408          *                              When the until property is set, the count property becomes @c 0. @n
 409          *                              When the count property is set, the until property becomes @c null.
 410          */
 411         result SetUntil(const Tizen::Base::DateTime* pUntil);
 412
 413         /**
 414          * Sets the number of times the event recurs.
 415          *
 416          * @since       2.0
 417          *
 418          * @return              An error code
 419          * @param[in]   count                   The number of times the event recurs
 420          * @exception   E_SUCCESS               The method is successful.
 421          * @exception   E_INVALID_ARG   The specified @c count is less than @c 0.
 422          * @remarks             Either the until or count properties may be set. @n
 423          *                              When the until property is set, the count property becomes @c 0. @n
 424          *                              When the count property is set, the until property becomes @c null. @n
 425          */
 426         result SetCounts(int count);
 427
 428         /**
 429          * Sets the first day of the week. @n
 430          * The default value is set to #CAL_MONDAY. The valid values are #CAL_SUNDAY and #CAL_MONDAY. @n
 431          * This value is very important when the recurrence type is weekly and the interval is greater than @c 1. @n
 432          * The weekly recurrence rule will be calculated based on the week start value.
 433          *
 434          * @since       2.0
 435          *
 436          * @return              An error code
 437          * @param[in]   weekStart                               The day on which the week starts
 438          * @exception   E_SUCCESS               The method is successful.
 439          * @exception   E_INVALID_ARG   The specified @c day is invalid.
 440          */
 441         result SetWeekStart(CalDayOfWeek weekStart);
 442
 443         /**
 444          * Sets the day of the week that represents the days when the event should recur. @n
 445          * The valid values range between #CAL_SUNDAY and #CAL_SATURDAY. @n
 446          * Any values other than #CAL_SUNDAY ~ #CAL_SATURDAY are ignored. @n
 447          * The Frequency property must be set before setting this property.
 448          * This property is valid for the following #RecurFrequency enumeration types: #FREQ_WEEKLY, #FREQ_MONTHLY, and #FREQ_YEARLY.
 449          * If the frequency is #FREQ_WEEKLY, the value of the day may be a combination of days, such as #CAL_MONDAY|#CAL_FRIDAY.
 450          *
 451          * @since       2.0
 452          *
 453          * @return              An error code
 454          * @param[in]   day                             An integer value representing the day of the week
 455          * @exception   E_SUCCESS               The method is successful.
 456          * @exception   E_INVALID_ARG   The specified @c day is invalid.
 457          * @exception   E_TYPE_MISMATCH The #RecurFrequency is not #FREQ_WEEKLY, #FREQ_MONTHLY, or #FREQ_YEARLY.
 458          * @remarks             After this property is set, the DayOfMonth property value is reset automatically.
 459          */
 460         result SetDayOfWeek(int day);
 461
 462         /**
 463          * Sets the day of the month which indicates when the event recurs. @n
 464          * The Frequency property must be set before setting this property. @n
 465          * This property is valid for the following #RecurFrequency enumeration types: #FREQ_MONTHLY and #FREQ_YEARLY. @n
 466          * If the day of the month is 31 and the frequency is monthly, the months which have only 30 days are not included in the recurrence instance set. @c
 467          * Accordingly, with the recurrence rule, 2/29 yearly, 2/29 every four years will be included in the recurrence set.
 468          *
 469          * @since       2.0
 470          *
 471          * @return              An error code
 472          * @param[in]   day                                     An integer value between @c 1 and @c 31 indicating the day of the month
 473          * @exception   E_SUCCESS                       The method is successful.
 474          * @exception   E_INVALID_ARG           The specified @c day is less than @c 1 or greater than @c 31.
 475          * @exception   E_TYPE_MISMATCH         The #RecurFrequency is not #FREQ_MONTHLY or #FREQ_YEARLY.
 476          * @remarks             After this property is set, the DayOfWeek and WeekOfMonth property value are reset automatically.
 477          */
 478         result SetDayOfMonth(int day);
 479
 480         /**
 481          * Sets the week of the month. @n
 482          * If the value of the week is @c 5, it is set as the last week of the month. @n
 483          * This property is valid for the following #RecurFrequency enumeration types: #FREQ_MONTHLY and #FREQ_YEARLY.
 484          * The Frequency property must be set before setting this property. @n
 485          * When the week of the month is set, the day of the week must be set accordingly.
 486          *
 487          * @since       2.0
 488          *
 489          * @return              An error code
 490          * @param[in]   week                            An integer value between @c 1 and @c 5 representing the week of the month
 491          * @exception   E_SUCCESS                       The method is successful.
 492          * @exception   E_INVALID_ARG           The specified @c week is less than @c 1 or greater than @c 5.
 493          * @exception   E_TYPE_MISMATCH         The #RecurFrequency is not #FREQ_MONTHLY or #FREQ_YEARLY.
 494          * @remarks             After this property is set, the DayOfMonth property value is reset automatically.
 495          */
 496         result SetWeekOfMonth(int week);
 497
 498         /**
 499          * Sets the month of the year. @n
 500          * This property is valid for the following #RecurFrequency enumeration type: #FREQ_YEARLY. @n
 501          * The Frequency property must be set before setting this property. @n
 502          * When the month of the year is set, the day of the month or both the day of the week and the week of the month must be set accordingly.
 503          *
 504          * @since       2.0
 505          *
 506          * @return              An error code
 507          * @param[in]   month                           An integer value between @c 1 and @c 12 representing the month of the year
 508          * @exception   E_SUCCESS                       The method is successful.
 509          * @exception   E_INVALID_ARG           The specified @c month is less than @c 1 or greater than @c 12.
 510          * @exception   E_TYPE_MISMATCH         The #RecurFrequency is not #FREQ_YEARLY.
 511          */
 512         result SetMonthOfYear(int month);
 513
 514         /**
 515          * Adds an exception date to this event.
 516          * The instance that its start date and time matched with the exception date will be exclude from recurrence instances.
 517          * If there are any changes in this recurrence, the exception dates would be cleared.
 518          *
 519          * @since       2.0
 520          *
 521          * @return              An error code
 522          * @param[in]   exceptionDate                   The exception date to exclude
 523          * @exception   E_SUCCESS                               The method is successful.
 524          * @exception   E_INVALID_ARG                   The specified @c exceptionDate is invalid.
 525          * @exception   E_OBJ_ALREADY_EXIST             The specified @c exceptionDate already exists.
 526          */
 527         result AddExceptionDate(const Tizen::Base::DateTime& exceptionDate);
 528
 529         /**
 530          * Gets the exception dates.
 531          *
 532          * @since       2.0
 533          *
 534          * @return              A list containing the exception dates, @n
 535          *                              else an empty list if there are no exception dates, or @c null if an exception occurs @n
 536          *                              The results are listed in the order of date and time.
 537          * @exception   E_SUCCESS                               The method is successful.
 538          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 539          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 540          */
 541         Tizen::Base::Collection::IList* GetExceptionDatesN(void) const;
 542
 543         /**
 544          * Copying of objects using this copy assignment operator is allowed.
 545          *
 546          * @since       2.0
 547          *
 548          * @param[in]   rhs             An instance of %Recurrence
 549          */
 550         Recurrence& operator =(const Recurrence& rhs);
 551
 552 private:
 553         friend class _RecurrenceImpl;
 554         class _RecurrenceImpl* __pRecurrenceImpl;
 555 };      // Recurrence
 556
 557 }}      // Tizen::Social
 558
 559 #endif // _FSCL_RECURRENCE_H_