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