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.
661 * Sets the category of the calendar event. @n
662 * If the category is not set, the default category (#EVENT_CATEGORY_APPOINTMENT) is set.
665 * @brief <i> [Deprecated] [Compatibility] </i>
667 * @deprecated This method is deprecated because the category of event is not used any more.
670 * @compatibility This method has compatibility issues with OSP compatible applications. @n
671 * For more information, see @ref CompCalEventSetCategoryPage "here".
674 * @param[in] category The category of the event
675 * @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 * All the other events are Coordinated Universal Time (UTC).
678 * In order to integrate it with the base applications, set the start and end time properly according to the above guidelines.
682 void SetCategory(EventCategory category);
686 * @page CompCalEventSetCategoryPage Compatibility for SetCategory()
687 * @section CompCalEventSetCategoryPageIssueSection Issues
688 * Implementing this method in OSP compatible applications has the following issues: @n
690 * -# 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 * @section CompCalEventSetCategoryPageSolutionSection Resolutions
694 * This issue has been resolved in Tizen. @n
695 * -# The category property is deprecated and it is not used any more.
696 * In Tizen, the all day event property will be set simultaneously when the anniversary category is set to the event.
697 * If an application tries to change the all day event property of the anniversary event to @c false, it will not be changed.
702 * Sets the sensitivity of the calendar event.
706 * @param[in] sensitivity The sensitivity of the calendar event
708 void SetSensitivity(RecordSensitivity sensitivity);
711 * Sets the coordinates.
715 * @return An error code
716 * @param[in] latitude The latitude in the range @n The valid range is [-90.0, 90.0].
717 * @param[in] longitude The longitude in the range @n The valid range is [-180.0, 180.0].
718 * @exception E_SUCCESS The method is successful.
719 * @exception E_INVALID_ARG The @c latitude or @c longitude is out of the valid range.
721 result SetCoordinates(double latitude, double longitude);
724 * Gets the coordinates.
728 * @return An error code
729 * @param[out] latitude The latitude
730 * @param[out] longitude The longitude
732 void GetCoordinates(double& latitude, double& longitude) const;
736 * Sets the reminder of the calendar event.
738 * @brief <i> [Deprecated] </i>
739 * @deprecated This method is deprecated. Instead of using this method, it is recommended to use AddReminder() and RemoveReminderAt().
742 * @return An error code
743 * @param[in] pReminder The reminder to set, @n
744 * else @c null to remove the previous reminder
745 * @exception E_SUCCESS The method is successful.
746 * @exception E_OUT_OF_MEMORY The memory is insufficient.
749 result SetReminder(const Reminder* pReminder);
752 * Sets the recurrence of the calendar event. @n
753 * The recurrence rule date must be equal to the start date of the event. @n
754 * 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
755 * For example, if an event start date is 17/02/2010, that is Wednesday and the recurrence rule date is Thursday of every week,
756 * the event start date changes to 18/02/2010, after this method is called. @n
757 * Note that the start/end date and the time zone must be set before setting a recurrence.
760 * @brief <i> [Compatibility] </i>
764 * @compatibility This method has compatibility issues with OSP compatible applications. @n
765 * For more information, see @ref CompCalEventSetRecurrencePage "here".
768 * @return An error code
769 * @param[in] pRecurrence The recurrence to set, @n
770 * else @c null to remove the previous recurrence
771 * @exception E_SUCCESS The method is successful.
772 * @exception E_INVALID_STATE The current event is a %CalEvent instance that has a recurrence ID.
773 * @exception E_INVALID_CONDITION Either of the following conditions has occurred: @n
774 * - The recurrence rule date is earlier than the start date and time of the event. @n
775 * - The recurrence rule is invalid. @n
776 * - The duration of the event is too long. @n
777 * It must be shorter than the (interval x frequency) days set for the recurrence rule.
778 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
779 * - When the frequency is #FREQ_WEEKLY, DayOfWeek is not set. @n
780 * - When the frequency is #FREQ_MONTHLY, neither DayOfMonth nor DayOfWeek and WeekOfMonth are not set. @n
781 * - When the frequency is #FREQ_YEARLY, neither DayOfMonth and MonthOfYear nor DayOfWeek,
782 * WeekOfMonth and MonthOfYear are not set. @n
783 * - When the frequency is #FREQ_YEARLY and MonthOfYear is 2, DayOfMonth is greater than 29 (> 29). @n
784 * - When the frequency is #FREQ_YEARLY and MonthOfYear is 4 or 6 or 9 or 11,
785 * DayOfMonth is greater than 30 (> 30).
786 * @exception E_SYSTEM The method cannot proceed due to a severe system error.
787 * @remarks If the until property of the recurrence is set with too distant future from the event's start date, @n
788 * too many recurring events are generated. It is the same when the value of recurrence count is big. @n
789 * The system limits the count of the recurring events that are generated by recurrence rule of an event. @n
790 * In this case, some recurring events that exceed the system limitation cannot be retrieved.
792 * The following example demonstrates how to use the %SetRecurrence() method.
794 MyClass::SetEventRecurrence(void)
796 result r = E_SUCCESS;
797 Recurrence* pRecurrence = new Recurrence();
799 pRecurrence->SetFrequency(FREQ_WEEKLY);
800 pRecurrence->SetDayOfWeek(CAL_MONDAY);
802 r = __pCalEvent->SetRecurrence(pRecurrence);
808 result SetRecurrence(const Recurrence* pRecurrence);
812 * @page CompCalEventSetRecurrencePage Compatibility for SetRecurrence()
813 * @section CompCalEventSetRecurrencePageIssueSection Issues
814 * Implementing this method in OSP compatible applications has the following issues: @n
815 * - If the category is anniversary and the frequency of recurrence is not yearly, E_TYPE_MISMATCH exception is occurred. @n
816 * Yearly frequency is only accepted for anniversary category.
818 * @section CompCalEventSetRecurrencePageSolutionSection Resolutions
819 * This issue has been resolved in Tizen. @n
820 * -# All recurrence frequency will be accepted because the category of event is not used any more.
829 * @return An error code
830 * @param[in] reminder The reminder to add
831 * @exception E_SUCCESS The method is successful.
832 * @exception E_OUT_OF_MEMORY The memory is insufficient.
834 result AddReminder(const Reminder& reminder);
837 * Removes a reminder at the index.
841 * @return An error code
842 * @param[in] index The index of reminder to remove
843 * @exception E_SUCCESS The method is successful.
844 * @exception E_OUT_OF_RANGE The index is either equal to or greater than the number of reminders or less than @c 0.
846 result RemoveReminderAt(int index);
849 * Gets a list of all the reminders.
853 * @return A list containing the Reminder instances, @n
854 * else an empty list if there are no reminders
856 const Tizen::Base::Collection::IList& GetAllReminders(void) const;
859 * Gets the ID of the calendar to which this event belongs.
863 * @return The calendar Id
865 RecordId GetCalendarId(void) const;
868 * Gets the base event ID.
869 * This method return the ID of the base recurring event for which this event is a recurrence exception.
873 * @return The base event ID, if this event is an exception
874 * else #INVALID_RECORD_ID
876 RecordId GetBaseEventId(void) const;
879 * Copying of objects using this copy assignment operator is allowed.
883 * @param[in] rhs An instance of %CalEvent
885 CalEvent& operator =(const CalEvent& rhs);
888 friend class _CalEventImpl;
889 class _CalEventImpl* __pCalEventImpl;
894 #endif // _FSCL_CAL_EVENT_H_