inc/FSclCalEvent.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        FSclCalEvent.h
  18  * @brief       This is the header file for the %CalEvent class.
  19  *
  20  * This header file contains the declarations of the %CalEvent class.
  21  */
  22 #ifndef _FSCL_CAL_EVENT_H_
  23 #define _FSCL_CAL_EVENT_H_
  24
  25 #include <FBaseDataType.h>
  26 #include <FBaseColIList.h>
  27 #include <FBaseString.h>
  28 #include <FBaseByteBuffer.h>
  29 #include <FBaseDateTime.h>
  30 #include <FLclCalendar.h>
  31 #include <FSclTypes.h>
  32 #include <FSclRecord.h>
  33 #include <FSclRecurrence.h>
  34 #include <FSclReminder.h>
  35 #include <FSclAttendee.h>
  36
  37 namespace Tizen { namespace Locales
  38 {
  39 class TimeZone;
  40 }}
  41
  42 namespace Tizen { namespace Social
  43 {
  44
  45 /**
  46  *      @class  CalEvent
  47  *      @brief  This class provides methods to manage the information of a calendar book event.
  48  *
  49  * @since       2.0
  50  *
  51  *      @final  This class is not intended for extension.
  52  *
  53  *      The %CalEvent class describes an occasion planned in a particular situation. @n
  54  *      An event is a subset of vEvent. A %CalEvent instance includes the category, subject, description, start time, end time, location, and sensitivity.
  55  *      %CalEvent also includes the recurring and reminder data. For more information, see the Recurrence, and Reminder classes.
  56  *
  57  *      For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/social/calevent.htm">Calendar Events</a>.
  58  *
  59  *      The following example demonstrates how to use the %CalEvent class.
  60
  61  *      @code
  62  *
  63         #include <FSocial.h>
  64         #include <FLocales.h>
  65
  66         using namespace Tizen::Base;
  67         using namespace Tizen::Social;
  68         using namespace Tizen::Locales;
  69
  70         void
  71         CreateCalEventWithTimeZone(void)
  72         {
  73                 DateTime startWallTime;
  74                 DateTime endWallTime;
  75                 DateTime startUtcTime;
  76                 DateTime endUtcTime;
  77
  78                 // Suppose a user set 2010/2/17 12:00:00 ~ 2010/2/17 14:00:00 in wall time for start/end time
  79                 startWallTime.SetValue(2010, 2, 17, 12, 0, 0);
  80                 endWallTime.SetValue(2010, 2, 17, 14, 0, 0);
  81
  82                 // Gets the system time zone
  83                 LocaleManager localeManager;
  84                 localeManager.Construct();
  85
  86                 TimeZone timeZone = localeManager.GetSystemTimeZone();
  87
  88                 // Converts the wall time to UTC time before set start and end time of the event
  89                 startUtcTime = timeZone.WallTimeToUtcTime(startWallTime);
  90                 endUtcTime = timeZone.WallTimeToUtcTime(endWallTime);
  91
  92                 // Creates an event
  93                 CalEvent event;
  94
  95                 // Sets the values
  96                 event.SetTimeZone(timeZone);
  97                 event.SetStartAndEndTime(startUtcTime, endUtcTime);
  98         }
  99  *
 100  * @endcode
 101  *
 102  *      The following example demonstrates how to use the %CalEvent class to add calendarbook all day event.
 103  *      @code
 104  *
 105         #include <FBase.h>
 106         #include <FSocial.h>
 107
 108         using namespace Tizen::Base;
 109         using namespace Tizen::Social;
 110
 111         void
 112         CreateAlldayEvent(void)
 113         {
 114
 115                 DateTime startWallTime;
 116                 DateTime endWallTime;
 117
 118                 // Sets the start/end time for an all day event on 2013/7/17
 119                 // The end time for all day event must be later than the start date(RFC 5545)
 120                 startWallTime.SetValue(2013, 7, 17, 0, 0, 0);
 121                 endWallTime.SetValue(2013, 7, 18, 0, 0, 0);
 122
 123                 // Creates an all day event
 124                 CalEvent event;
 125                 event.SetSubject(L"All day event");
 126
 127                 event.SetAllDayEvent(true);
 128                 event.SetStartAndEndTime(startWallTime, endWallTime);
 129         }
 130  *
 131  * @endcode
 132  */
 133 class _OSP_EXPORT_ CalEvent
 134         : public Record
 135 {
 136
 137 public:
 138         /**
 139          * This is the default constructor for this class.
 140          *
 141          * @since       2.0
 142          */
 143         CalEvent(void);
 144
 145         /**
 146          * Copying of objects using this copy constructor is allowed.
 147          *
 148          * @since       2.0
 149          *
 150          * @param[in]   rhs             An instance of %CalEvent to copy
 151          */
 152         CalEvent(const CalEvent& rhs);
 153
 154         /**
 155          * This destructor overrides Tizen::Social::Record::~Record().
 156          *
 157          * @since       2.0
 158          */
 159         virtual ~CalEvent(void);
 160
 161         /**
 162          * Compares the specified Tizen::Base::Object with the current %CalEvent instance.
 163          *
 164          * @since       2.0
 165          *
 166          * @return              @c true if the specified object equals the current %CalEvent instance, @n
 167          *                              else @c false
 168          * @param[in]   rhs     The object instance to compare with the current object
 169          * @see                 GetHashCode()
 170          */
 171         virtual bool Equals(const Tizen::Base::Object& rhs) const;
 172
 173         /**
 174          * Gets the hash value of the current instance.
 175          *
 176          * @since       2.0
 177          *
 178          * @return              The hash value of the current instance
 179          */
 180         virtual int GetHashCode(void) const;
 181
 182         /**
 183          * @if OSPDEPREC
 184          * Checks whether this instance is a %CalEvent instance. @n
 185          * A one-time calendar event has only one instance and a recurring calendar event has more than one instance. @n
 186          * Each instance of %CalEvent has its own recurrence ID.
 187          *
 188          * @brief <i> [Deprecated] </i>
 189          * @deprecated  This method is deprecated because %CalEvent class is not used for an event instance any more. @n
 190          * Instead of using the %CalEvent class, it is recommended to use the CalEventInstance class for an event instance.
 191          * @since       2.0
 192          *
 193          * @return              @c true if this instance is a %CalEvent instance, @n
 194          *                              else @c false
 195          * @endif
 196          */
 197         bool IsInstance(void) const;
 198
 199         /**
 200          * @if OSPDEPREC
 201          * Checks whether the calendar event has a recurring pattern.
 202          *
 203          * @brief <i> [Deprecated] </i>
 204          * @deprecated  This method is deprecated because %CalEvent class is not used for an event instance any more. @n
 205          * Instead of using the %CalEvent class, it is recommended to use the CalEventInstance class for an event instance.
 206          * @since       2.0
 207          *
 208          * @return              @c true if the calendar event has a recurring pattern, @n
 209          *                              else @c false
 210          * @endif
 211          */
 212         bool IsRecurring(void) const;
 213
 214         /**
 215          * @if OSPDEPREC
 216          * Gets the original calendar event ID. @n
 217          * The %CalEvent instance has an original @c CalEventId, that is a record ID of its entry.
 218          *
 219          * @brief <i> [Deprecated] </i>
 220          * @deprecated  This method is deprecated because %CalEvent class is not used for an event instance any more. @n
 221          * Instead of using the %CalEvent class, it is recommended to use the CalEventInstance class for an event instance.
 222          * @since       2.0
 223          *
 224          * @return      The original calendar event ID, @n
 225          *                      else #INVALID_RECORD_ID if the record ID is invalid
 226          * @endif
 227          */
 228         RecordId GetOriginalCalEventId(void) const;
 229
 230         /**
 231          * Checks whether the calendar event is an all day event.
 232          *
 233          * @since       2.0
 234          *
 235          * @return              @c true if the calendar event is an all day event, @n
 236          *                              else @c false
 237          */
 238         bool IsAllDayEvent(void) const;
 239
 240         /**
 241          * Sets the calendar event as an all day event.
 242          *
 243          * @since       2.0
 244          *
 245          * @param[in]   isAllDayEvent   Set to @c true to make the calendar event an all day event, @n
 246          *                                                              else @c false
 247          */
 248         void SetAllDayEvent(bool isAllDayEvent);
 249
 250         /**
 251          * @if OSPDEPREC
 252          * Gets the globally unique ID. @n
 253          * UID: globally Unique Identifier (vCalendar 1.0)
 254          *
 255          * @brief <i> [Deprecated] </i>
 256          * @deprecated  This method is deprecated because a string value cannot be handled. @n
 257          * Instead of using this method, it is recommended to use GetUid().
 258          * @since       2.0
 259          *
 260          * @return              The globally unique ID
 261          * @exception   E_SUCCESS                               The method is successful.
 262          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 263          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 264          * @endif
 265          */
 266         Tizen::Base::ByteBuffer* GetUIDN(void) const;
 267
 268         /**
 269          * @if OSPDEPREC
 270          * Sets the globally unique ID. @n
 271          * UID: globally Unique Identifier (vCalendar 1.0)
 272          *
 273          * @brief <i> [Deprecated] </i>
 274          * @deprecated  This method is deprecated because a string value cannot be handled. @n
 275          * Instead of using this method, it is recommended to use SetUid().
 276          * @since       2.0
 277          *
 278          * @return              An error code
 279          * @param[in]   pUid                                    The globally unique ID
 280          * @exception   E_SUCCESS                               The method is successful.
 281          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 282          * @endif
 283          */
 284         result SetUID(const Tizen::Base::ByteBuffer* pUid);
 285
 286         /**
 287          * Gets the globally unique ID. @n
 288          * UID: globally Unique Identifier (vCalendar 1.0)
 289          *
 290          * @since       2.0
 291          *
 292          * @return              The globally unique ID
 293          */
 294         Tizen::Base::String GetUid(void) const;
 295
 296         /**
 297          * Sets the globally unique ID. @n
 298          * UID: globally Unique Identifier (vCalendar 1.0)
 299          *
 300          * @since       2.0
 301          *
 302          * @param[in]   uid                                     The globally unique ID
 303          */
 304         void SetUid(const Tizen::Base::String& uid);
 305
 306         /**
 307          * Gets the calendar event status. @n
 308          * The default status is #EVENT_STATUS_NONE.
 309          *
 310          * @since       2.0
 311          *
 312          * @return              The calendar event status
 313          * @see                 EventStatus
 314          */
 315         EventStatus GetStatus(void) const;
 316
 317         /**
 318          * Sets the calendar event status.
 319          *
 320          * @since       2.0
 321          *
 322          * @param[in]   status          The status
 323          * @see                 EventStatus
 324          */
 325         void SetStatus(EventStatus status);
 326
 327         /**
 328          * Gets the busy status. @n
 329          * The default busy status is #BUSY_STATUS_BUSY.
 330          *
 331          * @since       2.0
 332          *
 333          * @return              The busy status
 334          * @see                 BusyStatus
 335          */
 336         BusyStatus GetBusyStatus(void) const;
 337
 338         /**
 339          * Sets the busy status.
 340          *
 341          * @since       2.0
 342          *
 343          * @param[in]   busyStatus              The busy status
 344          * @see                 BusyStatus
 345          */
 346         void SetBusyStatus(BusyStatus busyStatus);
 347
 348         /**
 349          * Gets the priority level of the calendar event. @n
 350          * The default priority level is #EVENT_PRIORITY_LOW.
 351          *
 352          * @since       2.0
 353          *
 354          * @return              The priority level
 355          *
 356          */
 357         EventPriority GetPriority(void) const;
 358
 359         /**
 360          * Sets the priority level of the calendar event.
 361          *
 362          * @since       2.0
 363          *
 364          * @param[in]   priority        The priority level to set
 365          *
 366          */
 367         void SetPriority(EventPriority priority);
 368
 369         /**
 370          * Adds an attendee.
 371          *
 372          * @brief <i> [Compatibility] </i>
 373          * @since       2.0
 374          * @compatibility       This method has compatibility issues with %Tizen API versions @b prior @b to @b 2.1. @n
 375          *                                      For more information, see @ref CompCalEventAddAttendeePage "here".
 376          *
 377          * @return              An error code
 378          * @param[in]   attendee                        The attendee to add @n
 379          *                                                                      The specified @c attendee must have an email address.
 380          * @exception   E_SUCCESS                       The method is successful.
 381          * @exception   E_INVALID_ARG           The specified @c attendee is invalid. @b Since @b 2.1
 382          * @exception   E_OBJ_ALREADY_EXIST     An attendee with the same email address already exists.
 383          */
 384         result AddAttendee(const Attendee& attendee);
 385
 386         /**
 387          * @page        CompCalEventAddAttendeePage Compatibility for AddAttendee()
 388          * @section     CompCalEventAddAttendeePageIssueSection Issues
 389          *                      Implementation of this method in %Tizen API versions prior to 2.1 has the following issue: @n
 390          *                      - If the email of @c attendee is empty, @c E_OBJ_ALREADY_EXIST is returned.
 391          *
 392          * @section     CompCalEventAddAttendeePageSolutionSection Resolutions
 393          *                      The issue mentioned above is resolved in %Tizen API version 2.1.
 394          *                      - If the email of @c attendee is empty, @c E_INVALID_ARG is returned.
 395          */
 396
 397         /**
 398          * Removes an attendee.
 399          *
 400          * @since       2.0
 401          *
 402          * @return              An error code
 403          * @param[in]   attendee                        The attendee to remove @n
 404          *                                                                      The specified @c attendee must have an email address.
 405          * @exception   E_SUCCESS                       The method is successful.
 406          * @exception   E_OBJ_NOT_FOUND         An attendee with the same email address is not found.
 407          */
 408         result RemoveAttendee(const Attendee& attendee);
 409
 410         /**
 411          * Gets the list of attendees.
 412          *
 413          * @since       2.0
 414          *
 415          * @return              The list of attendees
 416          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 417          * @see                 Attendee
 418          */
 419         Tizen::Base::Collection::IList* GetAllAttendeesN(void) const;
 420
 421         /**
 422          * Gets the time zone.
 423          *
 424          * @since       2.0
 425          *
 426          * @return              The time zone based on the time zone ID and the start time of the %CalEvent instance
 427          * @see                 Tizen::Locales::TimeZone::GetTimeZone(const Tizen::Base::String&, const Tizen::Base::DateTime&, Tizen::Locales::TimeZone&)
 428          */
 429         Tizen::Locales::TimeZone GetTimeZone(void) const;
 430
 431         /**
 432          * Sets the time zone. @n
 433          * Recurrence is calculated based on the time zone, thus the time zone must be set before setting a recurrence.
 434          * If the time zone is not set, it is considered as Greenwich Mean Time (GMT).
 435          *
 436          * @since       2.0
 437          *
 438          * @return              An error code
 439          * @param[in]   timeZone                        The time zone to set
 440          * @exception   E_SUCCESS                       The method is successful.
 441          * @exception   E_FAILURE                       The method has failed.
 442          * @remarks
 443          *                              - As all day events are not affected by a time zone, it is recommended not to set the time zone.
 444          *                              - Only the time zone ID of the @c timeZone is set to the %CalEvent instance, and the other properties are ignored.
 445          */
 446         result SetTimeZone(const Tizen::Locales::TimeZone& timeZone);
 447
 448         /**
 449          * @if OSPDEPREC
 450          * Gets the recurrence ID. @n
 451          * The %GetRecurrenceId() method works only for the %CalEvent instances.
 452          *
 453          * @brief <i> [Deprecated] </i>
 454          * @deprecated  This method is deprecated because the %CalEvent class is not used for an event instance any more. @n
 455          * Instead of using the %CalEvent class, it is recommended to use the CalEventInstance class for an event instance.
 456          * @since       2.0
 457          *
 458          * @return              The recurrence ID
 459          * @exception   E_SUCCESS                               The method is successful.
 460          * @exception   E_INVALID_STATE                 The instance is a %CalEvent instance that does not have a recurrence ID.
 461          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 462          * @endif
 463          */
 464         RecurrenceId GetRecurrenceId(void) const;
 465
 466         /**
 467          * Gets the subject of the calendar event.
 468          *
 469          * @since       2.0
 470          *
 471          * @return              The subject, @n
 472          *                              else @c null if there is no subject value
 473          */
 474         Tizen::Base::String GetSubject(void) const;
 475
 476         /**
 477          * Gets the description of the calendar event.
 478          *
 479          * @since       2.0
 480          *
 481          * @return              The description
 482          */
 483         Tizen::Base::String GetDescription(void) const;
 484
 485         /**
 486          * Gets the start date and time of the calendar event.
 487          *
 488          * @since       2.0
 489          *
 490          * @return              An instance of Tizen::Base::DateTime that represents the start date and time
 491          */
 492         Tizen::Base::DateTime GetStartTime(void) const;
 493
 494         /**
 495          * Gets the end date and time of the calendar event.
 496          *
 497          * @since       2.0
 498          *
 499          * @return              An instance of Tizen::Base::DateTime that represents the end date and time
 500          */
 501         Tizen::Base::DateTime GetEndTime(void) const;
 502
 503         /**
 504          * Gets the location of the calendar event.
 505          *
 506          * @since       2.0
 507          *
 508          * @return              The location
 509          */
 510         Tizen::Base::String GetLocation(void) const;
 511
 512         /**
 513          * @if OSPDEPREC
 514          * Gets the category of the calendar event.
 515          *
 516          * @brief <i> [Deprecated] </i>
 517          * @deprecated  This method is deprecated because the category of the event is not used any more.
 518          * @since       2.0
 519          *
 520          * @return              The category of the calendar event
 521          * @endif
 522          */
 523         EventCategory GetCategory(void) const;
 524
 525         /**
 526          * Gets the sensitivity of the calendar event. @n
 527          * The default value is #SENSITIVITY_PUBLIC.
 528          *
 529          * @since       2.0
 530          *
 531          * @return              The sensitivity of the calendar event
 532          */
 533         RecordSensitivity GetSensitivity(void) const;
 534
 535
 536         /**
 537          * @if OSPDEPREC
 538          * Gets the reminder for the calendar event.
 539          *
 540          * @brief <i> [Deprecated] </i>
 541          * @deprecated          This method is deprecated. Instead of using this method, it is recommended to use GetAllReminders().
 542          * @since       2.0
 543          *
 544          * @return              A pointer to an instance of Reminder, @n
 545          *                              else @c null if the reminder is not set
 546          * @endif
 547          */
 548         const Reminder* GetReminder(void) const;
 549
 550         /**
 551          * Gets the recurrence of the calendar event.
 552          *
 553          * @since       2.0
 554          *
 555          * @return              A pointer to an instance of Recurrence, @n
 556          *                              else @c null if the event is not a recurring event
 557          */
 558         const Recurrence* GetRecurrence(void) const;
 559
 560         /**
 561          * Gets the last updated date and time of the calendar event.
 562          *
 563          * @since       2.0
 564          *
 565          * @return              The last updated date and time
 566          */
 567         Tizen::Base::DateTime GetLastRevisedTime(void) const;
 568
 569         /**
 570          * Sets the subject of the calendar event.
 571          *
 572          * @if OSPCOMPAT
 573          * @brief <i> [Compatibility] </i>
 574          * @endif
 575          * @since       2.0
 576          * @if OSPCOMPAT
 577          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 578          *                                      For more information, see @ref CompCalEventSetSubjectPage "here".
 579          * @endif
 580          *
 581          * @return              An error code
 582          * @param[in]   subject                         The subject of the calendar event
 583          * @exception   E_SUCCESS                       The method is successful.
 584          */
 585         result SetSubject(const Tizen::Base::String& subject);
 586
 587         /**
 588          * @if OSPCOMPAT
 589          * @page        CompCalEventSetSubjectPage Compatibility for SetSubject()
 590          * @section     CompCalEventSetSubjectPageIssueSection Issues
 591          *          Implementing this method in OSP compatible applications has the following issues: @n
 592          *                      -# If the length of the subject to be set is greater than @c 100 characters, @c E_INVALID_ARG is returned.
 593          *
 594          * @section     CompCalEventSetSubjectPageSolutionSection Resolutions
 595          *                      This issue has been resolved in Tizen. @n
 596          *                      -# There is no limit for the length of the subject.
 597          * @endif
 598          */
 599
 600         /**
 601          * Sets the description of the current calendar event.
 602          *
 603          * @if OSPCOMPAT
 604          * @brief <i> [Compatibility] </i>
 605          * @endif
 606          * @since       2.0
 607          * @if OSPCOMPAT
 608          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 609          *                                      For more information, see @ref CompCalEventSetDescriptionPage "here".
 610          * @endif
 611          *
 612          * @return              An error code
 613          * @param[in]   description                     The description of the event
 614          * @exception   E_SUCCESS                       The method is successful.
 615          */
 616         result SetDescription(const Tizen::Base::String& description);
 617
 618         /**
 619          * @if OSPCOMPAT
 620          * @page        CompCalEventSetDescriptionPage Compatibility for SetDescription()
 621          * @section     CompCalEventSetDescriptionPageIssueSection Issues
 622          *          Implementing this method in OSP compatible applications has the following issues: @n
 623          *                      -# If the length of the description to be set is greater than @c 1000 characters, @c E_INVALID_ARG is returned.
 624          *
 625          * @section     CompCalEventSetDescriptionPageSolutionSection Resolutions
 626          *                      This issue has been resolved in Tizen. @n
 627          *                      -# There is no limit for the length of the description.
 628          * @endif
 629          */
 630
 631         /**
 632          * Sets the start and end date and time of the calendar event. @n
 633          * If the start date and time is not fixed, the default date and time are set. @n
 634          * The default start date and time is the current date and time. @n
 635          * The start date and time must be earlier than or equal to the end date and time. @n
 636          * If the recurrence date is already set, this method returns an exception.
 637          *
 638          * @since       2.0
 639          *
 640          * @return              An error code
 641          * @param[in]   startDateTime                   The start date and time @n Any value with a unit that is less than a second is ignored.
 642          * @param[in]   endDateTime                             The end date and time @n Any value with a unit that is less than a second is ignored.
 643          * @exception   E_SUCCESS                               The method is successful.
 644          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred:
 645          *                                                                              - The specified @c endDateTime value is earlier than the specified @c startDateTime value.
 646          *                                                                              - The specified @c startDateTime or @c endDateTime is out of the valid range. @n
 647          *                                                                              The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().
 648          * @exception   E_INVALID_CONDITION             The recurrence date is already set.
 649          * @remarks
 650          *                              - The start and end time of all day events created from the base applications is the local time of the location where
 651          *                              they are added. @n
 652          *                              All the other events are in Coordinated Universal Time (UTC). @n
 653          *                              In order to integrate it with the base applications, set the start and end time properly according to the above guidelines. @n
 654          *                              If the seconds value of the start time is set, the alarm will not be fired.
 655          *                              - There is no automatic time conversion based on the time zone property of the calendar event.
 656          */
 657         result SetStartAndEndTime(const Tizen::Base::DateTime& startDateTime, const Tizen::Base::DateTime& endDateTime);
 658
 659         /**
 660          * Sets the location of the current calendar event.
 661          *
 662          * @if OSPCOMPAT
 663          * @brief <i> [Compatibility] </i>
 664          * @endif
 665          * @since       2.0
 666          * @if OSPCOMPAT
 667          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 668          *                                      For more information, see @ref CompCalEventSetLocationPage "here".
 669          * @endif
 670          *
 671          * @return              An error code
 672          * @param[in]   location                        The location of the event
 673          * @exception   E_SUCCESS                       The method is successful.
 674          */
 675         result SetLocation(const Tizen::Base::String& location);
 676
 677         /**
 678          * @if OSPCOMPAT
 679          * @page        CompCalEventSetLocationPage Compatibility for SetLocation()
 680          * @section     CompCalEventSetLocationPageIssueSection Issues
 681          *          Implementing this method in OSP compatible applications has the following issues: @n
 682          *                      -# If the length of the location to be set is greater than @c 100 characters, @c E_INVALID_ARG is returned.
 683          *
 684          * @section     CompCalEventSetLocationPageSolutionSection Resolutions
 685          *                      This issue has been resolved in Tizen. @n
 686          *                      -# There is no limit for the length of the location.
 687          * @endif
 688          */
 689
 690         /**
 691          * @cond OSPDEPREC
 692          * Sets the category of the calendar event. @n
 693          * If the category is not set, the default category (#EVENT_CATEGORY_APPOINTMENT) is set.
 694          *
 695          * @if OSPCOMPAT
 696          * @brief <i> [Deprecated] [Compatibility] </i>
 697          * @endif
 698          * @deprecated  This method is deprecated because the category of the event is not used any more.
 699          * @since       2.0
 700          * @if OSPCOMPAT
 701          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 702          *                                      For more information, see @ref CompCalEventSetCategoryPage "here".
 703          * @endif
 704          *
 705          * @param[in]   category                        The category of the event
 706          * @remarks             The start and end time of the anniversary and all day events created from the base applications, is the local time of the location where
 707          *                              they are added.
 708          *                              All the other events are Coordinated Universal Time (UTC).
 709          *                              In order to integrate it with the base applications, set the start and end time properly according to the above guidelines.
 710          * @endcond
 711          */
 712         void SetCategory(EventCategory category);
 713
 714         /**
 715          * @if OSPCOMPAT
 716          * @page                CompCalEventSetCategoryPage             Compatibility for SetCategory()
 717          * @section             CompCalEventSetCategoryPageIssueSection Issues
 718          *                              Implementing this method in OSP compatible applications has the following issues: @n
 719          *
 720          *                              -# When the anniversary category is set to the event, it is handled as an all day event even though the all day event property is not set.
 721          *
 722          * @section             CompCalEventSetCategoryPageSolutionSection Resolutions
 723          *
 724          *  This issue has been resolved in Tizen. @n
 725          *  -# The category property is deprecated and it is not used any more.
 726          *  In Tizen, the all day event property is set simultaneously when the anniversary category is set to the event.
 727          *  If an application tries to change the all day event property of the anniversary event to @c false, it is not changed.
 728          * @endif
 729          */
 730
 731         /**
 732          * Sets the sensitivity of the calendar event.
 733          *
 734          * @since       2.0
 735          *
 736          * @param[in]   sensitivity             The sensitivity of the calendar event
 737          */
 738         void SetSensitivity(RecordSensitivity sensitivity);
 739
 740         /**
 741          * Sets the coordinates.
 742          *
 743          * @since       2.0
 744          *
 745          * @return              An error code
 746          * @param[in]   latitude                        The latitude within the range @n The valid range is [-90.0, 90.0].
 747          * @param[in]   longitude                       The longitude within the range @n The valid range is [-180.0, 180.0].
 748          * @exception   E_SUCCESS                       The method is successful.
 749          * @exception   E_INVALID_ARG           The specified @c latitude or @c longitude is outside the valid range.
 750          */
 751         result SetCoordinates(double latitude, double longitude);
 752
 753         /**
 754          * Gets the coordinates.
 755          *
 756          * @since       2.0
 757          *
 758          * @return              An error code
 759          * @param[out]  latitude                The latitude
 760          * @param[out]  longitude               The longitude
 761          */
 762         void GetCoordinates(double& latitude, double& longitude) const;
 763
 764         /**
 765          * @if OSPDEPREC
 766          * Sets the reminder of the calendar event.
 767          *
 768          * @brief <i> [Deprecated] </i>
 769          * @deprecated          This method is deprecated. Instead of using this method, it is recommended to use AddReminder() and RemoveReminderAt().
 770          * @since       2.0
 771          *
 772          * @return              An error code
 773          * @param[in]   pReminder                               The reminder to set, @n
 774          *                                                                              else @c null to remove the previous reminder
 775          * @exception   E_SUCCESS                               The method is successful.
 776          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 777          * @endif
 778          */
 779         result SetReminder(const Reminder* pReminder);
 780
 781         /**
 782          * Sets the recurrence of the calendar event. @n
 783          * The recurrence rule date must be equal to the start date of the event. @n
 784          * If the event start date is different than the recurrence rule date, the event start date is set to match the recurrence rule date. @n
 785          * For example, if an event start date is 17/02/2010, that is Wednesday and the recurrence rule date is Thursday of every week,
 786          * the event start date changes to 18/02/2010, after this method is called. @n
 787          * Note that the start/end date and the time zone must be set before setting a recurrence.
 788          *
 789          * @if OSPCOMPAT
 790          * @brief <i> [Compatibility] </i>
 791          * @endif
 792          * @since       2.0
 793          * @if OSPCOMPAT
 794          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 795          *                For more information, see @ref CompCalEventSetRecurrencePage "here".
 796          * @endif
 797          *
 798          * @return              An error code
 799          * @param[in]   pRecurrence                             The recurrence to set, @n
 800          *                                                                              else @c null to remove the previous recurrence
 801          * @exception   E_SUCCESS                               The method is successful.
 802          * @exception   E_INVALID_STATE                 The current event is a %CalEvent instance that has a recurrence ID.
 803          * @exception   E_INVALID_CONDITION             Either of the following conditions has occurred:
 804          *                                                                              - The recurrence rule date is earlier than the start date and time of the event.
 805          *                                                                              - The recurrence rule is invalid.
 806          *                                                                              - The duration of the event is too long. @n
 807          *                                                                              It must be shorter than the (interval x frequency) days set for the recurrence rule.
 808          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred:
 809          *                                                                              - When the frequency is #FREQ_WEEKLY, DayOfWeek is not set.
 810          *                                                                              - When the frequency is #FREQ_MONTHLY, neither DayOfMonth nor DayOfWeek and WeekOfMonth are set.
 811          *                                                                              - When the frequency is #FREQ_YEARLY, neither DayOfMonth and MonthOfYear nor DayOfWeek,
 812          *                                                                                WeekOfMonth and MonthOfYear are set.
 813          *                                                                              - When the frequency is #FREQ_YEARLY and MonthOfYear is @c 2, DayOfMonth is greater than @c 29 (> 29).
 814          *                                                                              - When the frequency is #FREQ_YEARLY and MonthOfYear is @c 4, @c 6, @c 9 or @c 11,
 815          *                                                                                DayOfMonth is greater than @c 30 (> 30).
 816          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 817          * @remarks             If the until property of the recurrence is set too far from the event's start date, @n
 818          *                              too many recurring events are generated. It is the same when the value of the recurrence count is large. @n
 819          *                              The system limits the count of the recurring events that are generated by the recurrence rule of an event. @n
 820          *                              In this case, some recurring events that exceed the system limitation cannot be retrieved.
 821          *
 822          * The following example demonstrates how to use the %SetRecurrence() method.
 823          * @code
 824                 MyClass::SetEventRecurrence(void)
 825                 {
 826                         result r = E_SUCCESS;
 827                         Recurrence* pRecurrence = new Recurrence();
 828
 829                         pRecurrence->SetFrequency(FREQ_WEEKLY);
 830                         pRecurrence->SetDayOfWeek(CAL_MONDAY);
 831
 832                         r = __pCalEvent->SetRecurrence(pRecurrence);
 833
 834                         delete pRecurrence;
 835                 }
 836          * @endcode
 837          */
 838         result SetRecurrence(const Recurrence* pRecurrence);
 839
 840         /**
 841          * @if OSPCOMPAT
 842          * @page        CompCalEventSetRecurrencePage Compatibility for SetRecurrence()
 843          * @section     CompCalEventSetRecurrencePageIssueSection Issues
 844          *           Implementing this method in OSP compatible applications has the following issues: @n
 845          *                      - If the category is anniversary and the frequency of recurrence is not yearly, @c E_TYPE_MISMATCH exception is returned. @n
 846          *                       Yearly frequency is only accepted for the anniversary category.
 847          *
 848          * @section     CompCalEventSetRecurrencePageSolutionSection Resolutions
 849          *                      This issue has been resolved in Tizen. @n
 850          *                      -# All recurrence frequencies are accepted because the category of the event is not used any more.
 851          * @endif
 852          */
 853
 854         /**
 855          * Adds a reminder.
 856          *
 857          * @since       2.0
 858          *
 859          * @return              An error code
 860          * @param[in]   reminder                        The reminder to add
 861          * @exception   E_SUCCESS                       The method is successful.
 862          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 863          */
 864         result AddReminder(const Reminder& reminder);
 865
 866         /**
 867          * Removes a reminder at the index.
 868          *
 869          * @since       2.0
 870          *
 871          * @return              An error code
 872          * @param[in]   index                           The index of the reminder to remove
 873          * @exception   E_SUCCESS                       The method is successful.
 874          * @exception   E_OUT_OF_RANGE          Either of the following conditions has occurred:
 875          *                                                                      - The specified @c index is either greater than or equal to the number of reminders.
 876          *                                                                      - The specified @c index is less than @c 0.
 877          */
 878         result RemoveReminderAt(int index);
 879
 880         /**
 881          * Gets the list of reminders.
 882          *
 883          * @since       2.0
 884          *
 885          * @return              The list that contains Reminder instances, @n
 886          *                              else an empty list if there are no reminders
 887          */
 888         const Tizen::Base::Collection::IList& GetAllReminders(void) const;
 889
 890         /**
 891          * Gets the ID of the calendar to which this event belongs.
 892          *
 893          * @since       2.0
 894          *
 895          * @return              The calendar Id
 896          */
 897         RecordId GetCalendarId(void) const;
 898
 899         /**
 900          * Gets the base event ID.
 901          * This method returns the ID of the base recurring event for which this event is a recurrence exception.
 902          *
 903          * @since       2.1
 904          *
 905          * @return              The base event ID, if this event is an exception
 906          *                              else #INVALID_RECORD_ID
 907          */
 908         RecordId GetBaseEventId(void) const;
 909
 910         /**
 911          * Copying of objects using this copy assignment operator is allowed.
 912          *
 913          * @since       2.0
 914          *
 915          * @param[in]   rhs             An instance of %CalEvent to copy
 916          */
 917         CalEvent& operator =(const CalEvent& rhs);
 918
 919 private:
 920         friend class _CalEventImpl;
 921         class _CalEventImpl* __pCalEventImpl;
 922 };      // CalEvent
 923
 924 }}      // Tizen::Social
 925
 926 #endif // _FSCL_CAL_EVENT_H_