2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
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
8 // http://www.apache.org/licenses/LICENSE-2.0
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.
17 * @file FSclCalEvent.h
18 * @brief This is the header file for the %CalEvent class.
20 * This header file contains the declarations of the %CalEvent class.
22 #ifndef _FSCL_CAL_EVENT_H_
23 #define _FSCL_CAL_EVENT_H_
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>
37 namespace Tizen { namespace Locales
42 namespace Tizen { namespace Social
47 * @brief This class provides methods to manage the information of a calendar book event.
51 * @final This class is not intended for extension.
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.
57 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/social/calevent.htm">Calendar Events</a>.
59 * The following example demonstrates how to use the %CalEvent class.
66 using namespace Tizen::Base;
67 using namespace Tizen::Social;
68 using namespace Tizen::Locales;
71 CreateCalEventWithTimeZone(void)
73 DateTime startWallTime;
75 DateTime startUtcTime;
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);
82 // Gets the system time zone
83 LocaleManager localeManager;
84 localeManager.Construct();
86 TimeZone timeZone = localeManager.GetSystemTimeZone();
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);
96 event.SetTimeZone(timeZone);
97 event.SetStartAndEndTime(startUtcTime, endUtcTime);
103 class _OSP_EXPORT_ CalEvent
109 * This is the default constructor for this class.
116 * Copying of objects using this copy constructor is allowed.
120 * @param[in] rhs An instance of %CalEvent
122 CalEvent(const CalEvent& rhs);
125 * This destructor overrides Tizen::Social::Record::~Record().
129 virtual ~CalEvent(void);
132 * Compares the input Tizen::Base::Object with the calling %CalEvent instance.
136 * @return @c true if the input object equals the calling %CalEvent instance, @n
138 * @param[in] rhs The object instance to compare with the calling object
141 virtual bool Equals(const Tizen::Base::Object& rhs) const;
144 * Gets the hash value of the current instance.
148 * @return The hash value of the current instance
150 virtual int GetHashCode(void) const;
154 * Checks whether this instance is a %CalEvent instance. @n
155 * A one-time calendar event has only one instance and a recurring calendar event has more than one instance. @n
156 * Each instance of %CalEvent has its own recurrence ID.
158 * @brief <i> [Deprecated] </i>
159 * @deprecated This method is deprecated because %CalEvent class is not used for event instance any more. @n
160 * Instead of using the %CalEvent class, it is recommended to use the CalEventInstance class for event instance.
163 * @return @c true if this instance is a %CalEvent instance, @n
167 bool IsInstance(void) const;
171 * Checks whether the calendar event has a recurring pattern.
173 * @brief <i> [Deprecated] </i>
174 * @deprecated This method is deprecated because %CalEvent class is not used for event instance any more. @n
175 * Instead of using the %CalEvent class, it is recommended to use the CalEventInstance class for event instance.
178 * @return @c true if the calendar event has a recurring pattern, @n
182 bool IsRecurring(void) const;
186 * Gets the original calendar event ID. @n
187 * The %CalEvent instance has an original @c CalEventId, that is a record ID of its entry.
189 * @brief <i> [Deprecated] </i>
190 * @deprecated This method is deprecated because %CalEvent class is not used for event instance any more. @n
191 * Instead of using the %CalEvent class, it is recommended to use the CalEventInstance class for event instance.
194 * @return The original calendar event ID, @n
195 * else #INVALID_RECORD_ID if the record ID is invalid
198 RecordId GetOriginalCalEventId(void) const;
201 * Checks whether the calendar event is an all day event.
205 * @return @c true if calendar event is an all day event, @n
208 bool IsAllDayEvent(void) const;
211 * Sets the calendar event as an all day event.
215 * @param[in] isAllDayEvent Set to @c true to make the calendar event an all day event, @n
218 void SetAllDayEvent(bool isAllDayEvent);
222 * Gets the globally unique ID. @n
223 * UID: globally Unique Identifier (vCalendar 1.0)
225 * @brief <i> [Deprecated] </i>
226 * @deprecated This method is deprecated because string value cannot be handled. @n
227 * Instead of using this method, it is recommended to use GetUid().
230 * @return The globally unique ID
231 * @exception E_SUCCESS The method is successful.
232 * @exception E_OUT_OF_MEMORY The memory is insufficient.
233 * @remarks The specific error code can be accessed using the GetLastResult() method.
236 Tizen::Base::ByteBuffer* GetUIDN(void) const;
240 * Sets the globally unique ID. @n
241 * UID: globally Unique Identifier (vCalendar 1.0)
243 * @brief <i> [Deprecated] </i>
244 * @deprecated This method is deprecated because string value cannot be handled. @n
245 * Instead of using this method, it is recommended to use SetUid().
248 * @return An error code
249 * @param[in] pUid The globally unique ID
250 * @exception E_SUCCESS The method is successful.
251 * @exception E_OUT_OF_MEMORY The memory is insufficient.
254 result SetUID(const Tizen::Base::ByteBuffer* pUid);
257 * Gets the globally unique ID. @n
258 * UID: globally Unique Identifier (vCalendar 1.0)
262 * @return The globally unique ID
264 Tizen::Base::String GetUid(void) const;
267 * Sets the globally unique ID. @n
268 * UID: globally Unique Identifier (vCalendar 1.0)
272 * @param[in] uid The globally unique ID
274 void SetUid(const Tizen::Base::String& uid);
277 * Gets the calendar event status. @n
278 * The default status is #EVENT_STATUS_NONE.
282 * @return The calendar event status
285 EventStatus GetStatus(void) const;
288 * Sets the calendar event status.
292 * @param[in] status The status
295 void SetStatus(EventStatus status);
298 * Gets the busy status. @n
299 * The default busy status is #BUSY_STATUS_BUSY.
303 * @return The busy status
306 BusyStatus GetBusyStatus(void) const;
309 * Sets the busy status.
313 * @param[in] busyStatus The busy status
316 void SetBusyStatus(BusyStatus busyStatus);
319 * Gets the priority level of the calendar event. @n
320 * The default priority level is #EVENT_PRIORITY_LOW.
324 * @return The priority level
327 EventPriority GetPriority(void) const;
330 * Sets the priority level of the calendar event.
334 * @param[in] priority The priority level to set
337 void SetPriority(EventPriority priority);
342 * @brief <i> [Compatibility] </i>
344 * @compatibility This method has compatibility issues with %Tizen API versions @b prior @b to @b 2.1. @n
345 * For more information, see @ref CompCalEventAddAttendeePage "here".
347 * @return An error code
348 * @param[in] attendee The attendee to add @n
349 * The specified @c attendee must have an email address.
350 * @exception E_SUCCESS The method is successful.
351 * @exception E_INVALID_ARG The specified @c attendee is invalid. @b Since @b 2.1
352 * @exception E_OBJ_ALREADY_EXIST An attendee with the same email address already exists.
354 result AddAttendee(const Attendee& attendee);
357 * @page CompCalEventAddAttendeePage Compatibility for AddAttendee()
358 * @section CompCalEventAddAttendeePageIssueSection Issues
359 * Implementation of this method in %Tizen API versions prior to 2.1 has the following issue: @n
360 * - If the email of @c attendee is empty, the @c E_OBJ_ALREADY_EXIST is returned.
362 * @section CompCalEventAddAttendeePageSolutionSection Resolutions
363 * The issue mentioned above is resolved in %Tizen API version 2.1.
364 * - If the email of @c attendee is empty, the @c E_INVALID_ARG is returned.
368 * Removes an attendee.
372 * @return An error code
373 * @param[in] attendee The attendee to remove @n
374 * The specified @c attendee must have an email address.
375 * @exception E_SUCCESS The method is successful.
376 * @exception E_OBJ_NOT_FOUND An attendee that has the same email address is not found.
378 result RemoveAttendee(const Attendee& attendee);
381 * Gets a list of all the attendees.
385 * @return A list of the attendees
386 * @remarks The specific error code can be accessed using the GetLastResult() method.
389 Tizen::Base::Collection::IList* GetAllAttendeesN(void) const;
392 * Gets the time zone.
396 * @return The time zone
397 * @see Tizen::Locales::TimeZone
399 Tizen::Locales::TimeZone GetTimeZone(void) const;
402 * Sets the time zone. @n
403 * Recurrence is calculated based on the time zone, thus the time zone must be set before setting a recurrence.
404 * If the time zone is not set, it will be considered as Greenwich Mean Time (GMT) 0.
408 * @return An error code
409 * @param[in] timeZone The time zone to set
410 * @exception E_SUCCESS The method is successful.
411 * @exception E_FAILURE The method has failed.
412 * @remarks As anniversaries and all day events are not affected by a time zone, it is recommended not to set the time zone.
413 * @see Tizen::Locales::TimeZone
415 result SetTimeZone(const Tizen::Locales::TimeZone& timeZone);
419 * Gets the recurrence ID. @n
420 * The %GetRecurrenceId() method works only for the %CalEvent instances.
422 * @brief <i> [Deprecated] </i>
423 * @deprecated This method is deprecated because %CalEvent class is not used for event instance any more. @n
424 * Instead of using the %CalEvent class, it is recommended to use the CalEventInstance class for event instance.
427 * @return The recurrence ID
428 * @exception E_SUCCESS The method is successful.
429 * @exception E_INVALID_STATE The instance is a %CalEvent instance that does not have a recurrence ID.
430 * @remarks The specific error code can be accessed using the GetLastResult() method.
433 RecurrenceId GetRecurrenceId(void) const;
436 * Gets the subject of the calendar event.
440 * @return The subject, @n
441 * else @c null if there is no subject value
443 Tizen::Base::String GetSubject(void) const;
446 * Gets the description of the calendar event.
450 * @return The description
452 Tizen::Base::String GetDescription(void) const;
455 * Gets the start date and time of the calendar event.
459 * @return An instance of Tizen::Base::DateTime representing the start date and time
461 Tizen::Base::DateTime GetStartTime(void) const;
464 * Gets the end date and time of the calendar event.
468 * @return An instance of Tizen::Base::DateTime representing the end date and time
470 Tizen::Base::DateTime GetEndTime(void) const;
473 * Gets the location of the calendar event.
477 * @return The location
479 Tizen::Base::String GetLocation(void) const;
483 * Gets the category of the calendar event.
485 * @brief <i> [Deprecated] </i>
486 * @deprecated This method is deprecated because the category of event is not used any more.
489 * @return The category of the calendar event
492 EventCategory GetCategory(void) const;
495 * Gets the sensitivity of the calendar event. @n
496 * The default value is #SENSITIVITY_PUBLIC.
500 * @return The sensitivity of the calendar event
502 RecordSensitivity GetSensitivity(void) const;
507 * Gets the reminder for the calendar event.
509 * @brief <i> [Deprecated] </i>
510 * @deprecated This method is deprecated. Instead of using this method, it is recommended to use GetAllReminders().
513 * @return A pointer to an instance of Reminder, @n
514 * else @c null if the reminder is not set
517 const Reminder* GetReminder(void) const;
520 * Gets the recurrence of the calendar event.
524 * @return A pointer to an instance of Recurrence, @n
525 * else @c null if the event is not a recurring event
527 const Recurrence* GetRecurrence(void) const;
530 * Gets the last updated date and time of the calendar event.
534 * @return The last updated date and time
536 Tizen::Base::DateTime GetLastRevisedTime(void) const;
539 * Sets the subject of the calendar event.
542 * @brief <i> [Compatibility] </i>
546 * @compatibility This method has compatibility issues with OSP compatible applications. @n
547 * For more information, see @ref CompCalEventSetSubjectPage "here".
550 * @return An error code
551 * @param[in] subject The subject of the calendar event
552 * @exception E_SUCCESS The method is successful.
554 result SetSubject(const Tizen::Base::String& subject);
558 * @page CompCalEventSetSubjectPage Compatibility for SetSubject()
559 * @section CompCalEventSetSubjectPageIssueSection Issues
560 * Implementing this method in OSP compatible applications has the following issues: @n
561 * -# If the length of the subject to be set is greater than 100 characters, E_INVALID_ARG is returned.
563 * @section CompCalEventSetSubjectPageSolutionSection Resolutions
564 * This issue has been resolved in Tizen. @n
565 * -# There is no limit for the length of the subject.
570 * Sets the description of the current calendar event.
573 * @brief <i> [Compatibility] </i>
577 * @compatibility This method has compatibility issues with OSP compatible applications. @n
578 * For more information, see @ref CompCalEventSetDescriptionPage "here".
581 * @return An error code
582 * @param[in] description The description of the event
583 * @exception E_SUCCESS The method is successful.
585 result SetDescription(const Tizen::Base::String& description);
589 * @page CompCalEventSetDescriptionPage Compatibility for SetDescription()
590 * @section CompCalEventSetDescriptionPageIssueSection Issues
591 * Implementing this method in OSP compatible applications has the following issues: @n
592 * -# If the length of the description to be set is greater than 1000 characters, E_INVALID_ARG is returned.
594 * @section CompCalEventSetDescriptionPageSolutionSection Resolutions
595 * This issue has been resolved in Tizen. @n
596 * -# There is no limit for the length of the description.
601 * Sets the start and end date and time of the calendar event. @n
602 * If the start date and time is not fixed, the default date and time are set. @n
603 * The default start date and time is the current date and time. @n
604 * The start date and time must be earlier than or equal to the end date and time. @n
605 * If the recurrence date is already set, this method returns an exception.
609 * @return An error code
610 * @param[in] startDateTime The start date and time. @n Any value with a unit that is less than a second is ignored.
611 * @param[in] endDateTime The end date and time. @n Any value with a unit that is less than a second is ignored.
612 * @exception E_SUCCESS The method is successful.
613 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
614 * - The specified @c endDateTime value is earlier than the specified @c startDateTime value.
615 * - The @c startDateTime or @c endDateTime is out of the valid range. @n
616 * The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().
617 * @exception E_INVALID_CONDITION The recurrence date is already set.
618 * @remarks The start and end time of all day events created from the base applications is the local time of the location where
620 * All the other events are Coordinated Universal Time (UTC).
621 * In order to integrate it with the base applications, set the start and end time properly according to the above guidelines.
622 * If the seconds value of the start time is set, the alarm will not be fired.
623 * There is no automatic time conversion based on the time zone property of the calendar event.
625 result SetStartAndEndTime(const Tizen::Base::DateTime& startDateTime, const Tizen::Base::DateTime& endDateTime);
628 * Sets the location of the current calendar event.
631 * @brief <i> [Compatibility] </i>
635 * @compatibility This method has compatibility issues with OSP compatible applications. @n
636 * For more information, see @ref CompCalEventSetLocationPage "here".
639 * @return An error code
640 * @param[in] location The location of the event
641 * @exception E_SUCCESS The method is successful.
643 result SetLocation(const Tizen::Base::String& location);
647 * @page CompCalEventSetLocationPage Compatibility for SetLocation()
648 * @section CompCalEventSetLocationPageIssueSection Issues
649 * Implementing this method in OSP compatible applications has the following issues: @n
650 * -# If the length of the location to be set is greater than 100 characters, E_INVALID_ARG is returned.
652 * @section CompCalEventSetLocationPageSolutionSection Resolutions
653 * This issue has been resolved in Tizen. @n
654 * -# There is no limit for the length of the location.
660 * Sets the category of the calendar event. @n
661 * If the category is not set, the default category (#EVENT_CATEGORY_APPOINTMENT) is set.
664 * @brief <i> [Deprecated] [Compatibility] </i>
666 * @deprecated This method is deprecated because the category of event is not used any more.
669 * @compatibility This method has compatibility issues with OSP compatible applications. @n
670 * For more information, see @ref CompCalEventSetCategoryPage "here".
673 * @param[in] category The category of the event
674 * @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
676 * All the other events are Coordinated Universal Time (UTC).
677 * In order to integrate it with the base applications, set the start and end time properly according to the above guidelines.
680 void SetCategory(EventCategory category);
684 * @page CompCalEventSetCategoryPage Compatibility for SetCategory()
685 * @section CompCalEventSetCategoryPageIssueSection Issues
686 * Implementing this method in OSP compatible applications has the following issues: @n
688 * -# 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.
690 * @section CompCalEventSetCategoryPageSolutionSection Resolutions
692 * This issue has been resolved in Tizen. @n
693 * -# The category property is deprecated and it is not used any more.
694 * In Tizen, the all day event property will be set simultaneously when the anniversary category is set to the event.
695 * If an application tries to change the all day event property of the anniversary event to @c false, it will not be changed.
700 * Sets the sensitivity of the calendar event.
704 * @param[in] sensitivity The sensitivity of the calendar event
706 void SetSensitivity(RecordSensitivity sensitivity);
709 * Sets the coordinates.
713 * @return An error code
714 * @param[in] latitude The latitude in the range @n The valid range is [-90.0, 90.0].
715 * @param[in] longitude The longitude in the range @n The valid range is [-180.0, 180.0].
716 * @exception E_SUCCESS The method is successful.
717 * @exception E_INVALID_ARG The @c latitude or @c longitude is out of the valid range.
719 result SetCoordinates(double latitude, double longitude);
722 * Gets the coordinates.
726 * @return An error code
727 * @param[out] latitude The latitude
728 * @param[out] longitude The longitude
730 void GetCoordinates(double& latitude, double& longitude) const;
734 * Sets the reminder of the calendar event.
736 * @brief <i> [Deprecated] </i>
737 * @deprecated This method is deprecated. Instead of using this method, it is recommended to use AddReminder() and RemoveReminderAt().
740 * @return An error code
741 * @param[in] pReminder The reminder to set, @n
742 * else @c null to remove the previous reminder
743 * @exception E_SUCCESS The method is successful.
744 * @exception E_OUT_OF_MEMORY The memory is insufficient.
747 result SetReminder(const Reminder* pReminder);
750 * Sets the recurrence of the calendar event. @n
751 * The recurrence rule date must be equal to the start date of the event. @n
752 * 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
753 * For example, if an event start date is 17/02/2010, that is Wednesday and the recurrence rule date is Thursday of every week,
754 * the event start date changes to 18/02/2010, after this method is called. @n
755 * Note that the start/end date and the time zone must be set before setting a recurrence.
758 * @brief <i> [Compatibility] </i>
762 * @compatibility This method has compatibility issues with OSP compatible applications. @n
763 * For more information, see @ref CompCalEventSetRecurrencePage "here".
766 * @return An error code
767 * @param[in] pRecurrence The recurrence to set, @n
768 * else @c null to remove the previous recurrence
769 * @exception E_SUCCESS The method is successful.
770 * @exception E_INVALID_STATE The current event is a %CalEvent instance that has a recurrence ID.
771 * @exception E_INVALID_CONDITION Either of the following conditions has occurred: @n
772 * - The recurrence rule date is earlier than the start date and time of the event. @n
773 * - The recurrence rule is invalid. @n
774 * - The duration of the event is too long. @n
775 * It must be shorter than the (interval x frequency) days set for the recurrence rule.
776 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
777 * - When the frequency is #FREQ_WEEKLY, DayOfWeek is not set. @n
778 * - When the frequency is #FREQ_MONTHLY, neither DayOfMonth nor DayOfWeek and WeekOfMonth are not set. @n
779 * - When the frequency is #FREQ_YEARLY, neither DayOfMonth and MonthOfYear nor DayOfWeek,
780 * WeekOfMonth and MonthOfYear are not set. @n
781 * - When the frequency is #FREQ_YEARLY and MonthOfYear is 2, DayOfMonth is greater than 29 (> 29). @n
782 * - When the frequency is #FREQ_YEARLY and MonthOfYear is 4 or 6 or 9 or 11,
783 * DayOfMonth is greater than 30 (> 30).
784 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
785 * @remarks If the until property of the recurrence is set with too distant future from the event's start date, @n
786 * too many recurring events are generated. It is the same when the value of recurrence count is big. @n
787 * The system limits the count of the recurring events that are generated by recurrence rule of an event. @n
788 * In this case, some recurring events that exceed the system limitation cannot be retrieved.
790 * The following example demonstrates how to use the %SetRecurrence() method.
792 MyClass::SetEventRecurrence(void)
794 result r = E_SUCCESS;
795 Recurrence* pRecurrence = new Recurrence();
797 pRecurrence->SetFrequency(FREQ_WEEKLY);
798 pRecurrence->SetDayOfWeek(CAL_MONDAY);
800 r = __pCalEvent->SetRecurrence(pRecurrence);
806 result SetRecurrence(const Recurrence* pRecurrence);
810 * @page CompCalEventSetRecurrencePage Compatibility for SetRecurrence()
811 * @section CompCalEventSetRecurrencePageIssueSection Issues
812 * Implementing this method in OSP compatible applications has the following issues: @n
813 * - If the category is anniversary and the frequency of recurrence is not yearly, E_TYPE_MISMATCH exception is occurred. @n
814 * Yearly frequency is only accepted for anniversary category.
816 * @section CompCalEventSetRecurrencePageSolutionSection Resolutions
817 * This issue has been resolved in Tizen. @n
818 * -# All recurrence frequency will be accepted because the category of event is not used any more.
827 * @return An error code
828 * @param[in] reminder The reminder to add
829 * @exception E_SUCCESS The method is successful.
830 * @exception E_OUT_OF_MEMORY The memory is insufficient.
832 result AddReminder(const Reminder& reminder);
835 * Removes a reminder at the index.
839 * @return An error code
840 * @param[in] index The index of reminder to remove
841 * @exception E_SUCCESS The method is successful.
842 * @exception E_OUT_OF_RANGE The index is either equal to or greater than the number of reminders or less than @c 0.
844 result RemoveReminderAt(int index);
847 * Gets a list of all the reminders.
851 * @return A list containing the Reminder instances, @n
852 * else an empty list if there are no reminders
854 const Tizen::Base::Collection::IList& GetAllReminders(void) const;
857 * Gets the ID of the calendar to which this event belongs.
861 * @return The calendar Id
863 RecordId GetCalendarId(void) const;
866 * Gets the base event ID.
867 * This method return the ID of the base recurring event for which this event is a recurrence exception.
871 * @return The base event ID, if this event is an exception
872 * else #INVALID_RECORD_ID
874 RecordId GetBaseEventId(void) const;
877 * Copying of objects using this copy assignment operator is allowed.
881 * @param[in] rhs An instance of %CalEvent
883 CalEvent& operator =(const CalEvent& rhs);
886 friend class _CalEventImpl;
887 class _CalEventImpl* __pCalEventImpl;
892 #endif // _FSCL_CAL_EVENT_H_