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.
18 * @brief This is the header file for the %CalTodo class.
20 * This header file contains the declarations of the %CalTodo class.
22 #ifndef _FSCL_CAL_TODO_H_
23 #define _FSCL_CAL_TODO_H_
25 #include <FBaseDataType.h>
26 #include <FSclTypes.h>
27 #include <FSclRecord.h>
28 #include <FSclRecurrence.h>
30 namespace Tizen { namespace Base
41 namespace Tizen { namespace Social
48 * @brief This class represents the calendar book to-do information.
52 * @final This class is not intended for extension.
54 * The %CalTodo class is a subset of vTodo. An instance of %CalTodo includes the subject, description, start date, due date, location, sensitivity,
55 * priority, and status.
56 * This class represents the information of a calendar book to-do.
58 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/social/caltodo.htm">Calendar Tasks</a>.
61 class _OSP_EXPORT_ CalTodo
66 * This is the default constructor for this class.
73 * Copying of objects using this copy constructor is allowed.
77 * @param[in] rhs An instance of %CalTodo
79 CalTodo(const CalTodo& rhs);
82 * This destructor overrides Tizen::Social::Record::~Record().
86 virtual ~CalTodo(void);
89 * Compares the input Tizen::Base::Object with the calling %CalTodo instance.
93 * @return @c true if the input object equals the calling %CalTodo instance, @n
95 * @param[in] rhs The object instance to compare with the calling object
98 virtual bool Equals(const Tizen::Base::Object& rhs) const;
101 * Gets the hash value of the current instance.
105 * @return The hash value of the current instance
107 virtual int GetHashCode(void) const;
110 * Gets the subject of the current instance of %CalTodo.
114 * @return The subject
116 Tizen::Base::String GetSubject(void) const;
119 * Gets the description of the current instance of %CalTodo.
123 * @return The description
125 Tizen::Base::String GetDescription(void) const;
128 * Gets the start date of the current instance of %CalTodo.
132 * @return The start date, @n
133 * the minimum value of Tizen::Base::DateTime, if the start date has been not set
134 * @exception E_SUCCESS The method is successful.
135 * @exception E_DATA_NOT_FOUND The start date has been not set.
136 * @remarks The specific error code can be accessed using the GetLastResult() method.
137 * @remarks The minimum value can be acquired using Tizen::Base::DateTime::GetMinValue().
139 Tizen::Base::DateTime GetStartDate(void) const;
142 * Gets the due date of the current instance of %CalTodo.
146 * @return The due date, @n
147 * the minimum value of Tizen::Base::DateTime, if the due date has been not set
148 * @exception E_SUCCESS The method is successful.
149 * @exception E_DATA_NOT_FOUND The due date has been not set.
150 * @remarks The specific error code can be accessed using the GetLastResult() method.
151 * @remarks The minimum value can be acquired using Tizen::Base::DateTime::GetMinValue().
153 Tizen::Base::DateTime GetDueDate(void) const;
156 * Gets the priority level of the current instance of %CalTodo. @n
157 * The default priority level is #TODO_PRIORITY_LOW.
161 * @return The priority level
163 TodoPriority GetPriority(void) const;
166 * Gets the status of the current instance of %CalTodo. @n
167 * The default status is #TODO_STATUS_NONE.
171 * @return The to-do status
173 TodoStatus GetStatus(void) const;
176 * Gets the sensitivity of the current instance of %CalTodo. @n
177 * The default value is #SENSITIVITY_PUBLIC.
181 * @return The to-do sensitivity
183 RecordSensitivity GetSensitivity(void) const;
186 * Gets the last updated date and time of the current instance of %CalTodo.
190 * @return The last updated date and time
192 Tizen::Base::DateTime GetLastRevisedTime(void) const;
195 * Sets the subject of the current instance of %CalTodo.
198 * @brief <i> [Compatibility] </i>
202 * @compatibility This method has compatibility issues with OSP compatible applications. @n
203 * For more information, see @ref CompCalTodoSetSubjectPage "here".
206 * @return An error code
207 * @param[in] subject The to-do subject
208 * @exception E_SUCCESS The method is successful.
210 result SetSubject(const Tizen::Base::String& subject);
214 * @page CompCalTodoSetSubjectPage Compatibility for SetSubject()
215 * @section CompCalTodoSetSubjectPageIssueSection Issues
216 * Implementing this method in OSP compatible applications has the following issues: @n
217 * -# If the length of the subject to be set is greater than 100 characters, E_INVALID_ARG is returned.
219 * @section CompCalTodoSetSubjectPageSolutionSection Resolutions
220 * This issue has been resolved in Tizen. @n
221 * -# There is no limit for the length of the subject.
226 * Sets the description of the current instance of %CalTodo.
229 * @brief <i> [Compatibility] </i>
233 * @compatibility This method has compatibility issues with OSP compatible applications. @n
234 * For more information, see @ref CompCalTodoSetDescriptionPage "here".
237 * @return An error code
238 * @param[in] description The to-do description, @n
239 * else @c null to remove the existing value
240 * @exception E_SUCCESS The method is successful.
242 result SetDescription(const Tizen::Base::String& description);
246 * @page CompCalTodoSetDescriptionPage Compatibility for SetDescription()
247 * @section CompCalTodoSetDescriptionPageIssueSection Issues
248 * Implementing this method in OSP compatible applications has the following issues: @n
249 * -# If the length of the description to be set is greater than 1000 characters, E_INVALID_ARG is returned.
251 * @section CompCalTodoSetDescriptionPageSolutionSection Resolutions
252 * This issue has been resolved in Tizen. @n
253 * -# There is no limit for the length of the description.
259 * Sets the start date and due date for the current instance of %CalTodo. @n
260 * The due date must be later than or equal to the start date.
263 * @brief <i> [Deprecated] [Compatibility] </i>
265 * @deprecated This method is deprecated. Instead of using this method, it is recommended to use SetStartDate() and SetDueDate().
268 * @compatibility This method has compatibility issues with OSP compatible applications. @n
269 * For more information, see @ref CompCalTodoSetStartAndDueDatePage "here".
272 * @return An error code
273 * @param[in] startDate The start date. @n Any value with a unit that is less than a second is ignored.
274 * @param[in] dueDate The due date. @n Any value with a unit that is less than a second is ignored.
275 * @exception E_SUCCESS The method is successful.
276 * @exception E_INVALID_ARG Either of the following conditions has occurred: @n
277 * - The specified @c dueDate is earlier than the specified @c startDate.
278 * - The @c startDate or @c dueDate is not a valid range. @n
279 * The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().
282 result SetStartAndDueDate(const Tizen::Base::DateTime& startDate, const Tizen::Base::DateTime& dueDate);
286 * @page CompCalTodoSetStartAndDueDatePage Compatibility for SetStartAndDueDate()
287 * @section CompCalTodoSetStartAndDueDatePageIssueSection Issues
288 * Implementing this method in OSP compatible applications has the following issues: @n
289 * -# The start and due date cannot be unset. And if the SetStartAndDueDate() is not called, the default start and due date @n
290 * are set to the system time when the to-do is constructed.
292 * @section CompCalTodoSetStartAndDueDatePageSolutionSection Resolutions
293 * This issue has been resolved in Tizen. @n
294 * -# The default start and due date of the to-do is unset.
299 * Sets the start date for the current instance of %CalTodo. @n
300 * If the @c startDate is minimum value of Tizen::Base::DateTime, the start date is changed to unset. @n
301 * And if the start date is later than due date, the due date will be changed to unset.
305 * @return An error code
306 * @param[in] startDate The start date. @n Any value with a unit that is less than a second is ignored.
307 * @exception E_SUCCESS The method is successful. @n
308 * Either @c startDate is between Calendarbook::GetMaxDateTime() and Calendarbook::GetMinDateTime(), or
309 * @c startDate is the minimum value of Tizen::Base::DateTime to unset the start date.
310 * @exception E_INVALID_ARG The specified @c start date is invalid.
311 * @remarks The minimum value can be acquired using Tizen::Base::DateTime::GetMinValue().
313 result SetStartDate(const Tizen::Base::DateTime& startDate);
316 * Sets the end date for the current instance of %CalTodo. @n
317 * If the @c dueDate is minimum value of Tizen::Base::DateTime, the due date is changed to unset. @n
318 * And if the due date is earlier than start date, the start date will be changed to unset.
322 * @return An error code
323 * @param[in] dueDate The due date. @n Any value with a unit that is less than a second is ignored.
324 * @exception E_SUCCESS The method is successful. @n
325 * Either @c dueDate is between Calendarbook::GetMaxDateTime() and Calendarbook::GetMinDateTime(), or
326 * @c dueDate is the minimum value of Tizen::Base::DateTime to unset the due date.
327 * @exception E_INVALID_ARG The specified @c due date is invalid.
328 * @remarks The minimum value can be acquired using Tizen::Base::DateTime::GetMinValue().
330 result SetDueDate(const Tizen::Base::DateTime& dueDate);
334 * Sets the priority level of the current instance of %CalTodo.
338 * @param[in] priority The priority level to set
340 void SetPriority(TodoPriority priority);
343 * Sets the status of the current instance of %CalTodo.
347 * @param[in] status The status to set
349 void SetStatus(TodoStatus status);
352 * Sets the sensitivity of the current instance of %CalTodo.
356 * @param[in] sensitivity The sensitivity to set
358 void SetSensitivity(RecordSensitivity sensitivity);
361 * Sets the location of the current calendar event.
365 * @return An error code
366 * @param[in] location The location of the event
368 void SetLocation(const Tizen::Base::String& location);
371 * Gets the location of the calendar event.
375 * @return The location
377 Tizen::Base::String GetLocation(void) const;
380 * Sets the coordinates.
384 * @return An error code
385 * @param[in] latitude The latitude in the range @n The valid range is [-90.0, 90.0].
386 * @param[in] longitude The longitude in the range @n The valid range is [-180.0, 180.0].
387 * @exception E_SUCCESS The method is successful.
388 * @exception E_INVALID_ARG The @c latitude or @c longitude is out of the valid range.
390 result SetCoordinates(double latitude, double longitude);
393 * Gets the coordinates.
397 * @return An error code
398 * @param[out] latitude The latitude
399 * @param[out] longitude The longitude
402 void GetCoordinates(double& latitude, double& longitude) const;
409 * @return An error code
410 * @param[in] reminder The reminder to add
411 * @exception E_SUCCESS The method is successful.
412 * @exception E_OUT_OF_MEMORY The memory is insufficient.
414 result AddReminder(const Reminder& reminder);
417 * Removes a reminder at the index.
421 * @return An error code
422 * @param[in] index The index of reminder to remove
423 * @exception E_SUCCESS The method is successful.
424 * @exception E_OUT_OF_RANGE The index is either equal to or greater than the number of reminders or less than @c 0.
426 result RemoveReminderAt(int index);
429 * Gets a list of all the reminders.
433 * @return A list containing the Reminder instances, @n
434 * else an empty list if there are no reminders
436 const Tizen::Base::Collection::IList& GetAllReminders(void) const;
439 * Gets the ID of the calendar to which this to-do belongs.
443 * @return The calendar ID
445 RecordId GetCalendarId(void) const;
448 * Copying of objects using this copy assignment operator is allowed.
452 * @param[in] rhs An instance of %CalTodo
454 CalTodo& operator =(const CalTodo& rhs);
457 friend class _CalTodoImpl;
458 class _CalTodoImpl* __pCalTodoImpl;
463 #endif // _FSCL_CAL_TODO_H_