inc/FSclCalTodo.h

   1 //
   2 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   3 //
   4 // Licensed under the Apache License, Version 2.0 (the License);
   5 // you may not use this file except in compliance with the License.
   6 // You may obtain a copy of the License at
   7 //
   8 //     http://www.apache.org/licenses/LICENSE-2.0
   9 //
  10 // Unless required by applicable law or agreed to in writing, software
  11 // distributed under the License is distributed on an "AS IS" BASIS,
  12 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13 // See the License for the specific language governing permissions and
  14 // limitations under the License.
  15 //
  16 /**
  17  * @file                FSclCalTodo.h
  18  * @brief               This is the header file for the %CalTodo class.
  19  *
  20  * This header file contains the declarations of the %CalTodo class.
  21  */
  22 #ifndef _FSCL_CAL_TODO_H_
  23 #define _FSCL_CAL_TODO_H_
  24
  25 #include <FBaseDataType.h>
  26 #include <FSclTypes.h>
  27 #include <FSclRecord.h>
  28 #include <FSclRecurrence.h>
  29
  30 namespace Tizen { namespace Base
  31 {
  32 class String;
  33 class DateTime;
  34
  35 namespace Collection
  36 {
  37 class IList;
  38 }
  39 }}
  40
  41 namespace Tizen { namespace Social
  42 {
  43
  44 class Reminder;
  45
  46 /**
  47  *      @class  CalTodo
  48  *      @brief  This class represents the calendar book to-do information.
  49  *
  50  * @since       2.0
  51  *
  52  *      @final  This class is not intended for extension.
  53  *
  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.
  57  *
  58  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/social/caltodo.htm">Calendar Tasks</a>.
  59  *
  60  */
  61 class _OSP_EXPORT_ CalTodo
  62         : public Record
  63 {
  64 public:
  65         /**
  66          * This is the default constructor for this class.
  67          *
  68          * @since       2.0
  69          */
  70         CalTodo(void);
  71
  72         /**
  73          * Copying of objects using this copy constructor is allowed.
  74          *
  75          * @since       2.0
  76          *
  77          * @param[in]   rhs             An instance of %CalTodo
  78          */
  79         CalTodo(const CalTodo& rhs);
  80
  81         /**
  82          * This destructor overrides Tizen::Social::Record::~Record().
  83          *
  84          * @since       2.0
  85          */
  86         virtual ~CalTodo(void);
  87
  88         /**
  89          * Compares the input Tizen::Base::Object with the calling %CalTodo instance.
  90          *
  91          * @since       2.0
  92          *
  93          * @return              @c true if the input object equals the calling %CalTodo instance, @n
  94          *                              else @c false
  95          * @param[in]   rhs     The object instance to compare with the calling object
  96          * @see                 GetHashCode()
  97          */
  98         virtual bool Equals(const Tizen::Base::Object& rhs) const;
  99
 100         /**
 101          * Gets the hash value of the current instance.
 102          *
 103          * @since       2.0
 104          *
 105          * @return              The hash value of the current instance
 106          */
 107         virtual int GetHashCode(void) const;
 108
 109         /**
 110          * Gets the subject of the current instance of %CalTodo.
 111          *
 112          * @since       2.0
 113          *
 114          * @return              The subject
 115          */
 116         Tizen::Base::String GetSubject(void) const;
 117
 118         /**
 119          * Gets the description of the current instance of %CalTodo.
 120          *
 121          * @since       2.0
 122          *
 123          * @return       The description
 124          */
 125         Tizen::Base::String GetDescription(void) const;
 126
 127         /**
 128          * Gets the start date of the current instance of %CalTodo.
 129          *
 130          * @since       2.0
 131          *
 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().
 138          */
 139         Tizen::Base::DateTime GetStartDate(void) const;
 140
 141         /**
 142          * Gets the due date of the current instance of %CalTodo.
 143          *
 144          * @since       2.0
 145          *
 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().
 152          */
 153         Tizen::Base::DateTime GetDueDate(void) const;
 154
 155         /**
 156          * Gets the priority level of the current instance of %CalTodo. @n
 157          * The default priority level is #TODO_PRIORITY_LOW.
 158          *
 159          * @since       2.0
 160          *
 161          * @return              The priority level
 162          */
 163         TodoPriority GetPriority(void) const;
 164
 165         /**
 166          * Gets the status of the current instance of %CalTodo. @n
 167          * The default status is #TODO_STATUS_NONE.
 168          *
 169          * @since       2.0
 170          *
 171          * @return              The to-do status
 172          */
 173         TodoStatus GetStatus(void) const;
 174
 175         /**
 176          * Gets the sensitivity of the current instance of %CalTodo. @n
 177          * The default value is #SENSITIVITY_PUBLIC.
 178          *
 179          * @since       2.0
 180          *
 181          * @return              The to-do sensitivity
 182          */
 183         RecordSensitivity GetSensitivity(void) const;
 184
 185         /**
 186          * Gets the last updated date and time of the current instance of %CalTodo.
 187          *
 188          * @since       2.0
 189          *
 190          * @return              The last updated date and time
 191          */
 192         Tizen::Base::DateTime GetLastRevisedTime(void) const;
 193
 194         /**
 195          * Sets the subject of the current instance of %CalTodo.
 196          *
 197          * @if OSPCOMPAT
 198          * @brief <i> [Compatibility] </i>
 199          * @endif
 200          * @since       2.0
 201          * @if OSPCOMPAT
 202          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 203          *                                      For more information, see @ref CompCalTodoSetSubjectPage "here".
 204          * @endif
 205          *
 206          * @return              An error code
 207          * @param[in]   subject                         The to-do subject
 208          * @exception   E_SUCCESS                       The method is successful.
 209          */
 210         result SetSubject(const Tizen::Base::String& subject);
 211
 212         /**
 213          * @if OSPCOMPAT
 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.
 218          *
 219          * @section     CompCalTodoSetSubjectPageSolutionSection Resolutions
 220          *                      This issue has been resolved in Tizen. @n
 221          *                      -# There is no limit for the length of the subject.
 222          * @endif
 223          */
 224
 225         /**
 226          * Sets the description of the current instance of %CalTodo.
 227          *
 228          * @if OSPCOMPAT
 229          * @brief <i> [Compatibility] </i>
 230          * @endif
 231          * @since       2.0
 232          * @if OSPCOMPAT
 233          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 234          *                                      For more information, see @ref CompCalTodoSetDescriptionPage "here".
 235          * @endif
 236          *
 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.
 241          */
 242         result SetDescription(const Tizen::Base::String& description);
 243
 244         /**
 245          * @if OSPCOMPAT
 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.
 250          *
 251          * @section     CompCalTodoSetDescriptionPageSolutionSection Resolutions
 252          *                      This issue has been resolved in Tizen. @n
 253          *                      -# There is no limit for the length of the description.
 254          * @endif
 255          */
 256
 257         /**
 258          * @{
 259          * @if OSPDEPREC
 260          * Sets the start date and due date for the current instance of %CalTodo. @n
 261          * The due date must be later than or equal to the start date.
 262          *
 263          * @if OSPCOMPAT
 264          * @brief <i> [Deprecated] [Compatibility] </i>
 265          * @endif
 266          * @deprecated  This method is deprecated. Instead of using this method, it is recommended to use SetStartDate() and SetDueDate().
 267          * @since       2.0
 268          * @if OSPCOMPAT
 269          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 270          *                              For more information, see @ref CompCalTodoSetStartAndDueDatePage "here".
 271          * @endif
 272          *
 273          * @return              An error code
 274          * @param[in]   startDate                       The start date. @n Any value with a unit that is less than a second is ignored.
 275          * @param[in]   dueDate                 The due date. @n Any value with a unit that is less than a second is ignored.
 276          * @exception   E_SUCCESS               The method is successful.
 277          * @exception   E_INVALID_ARG           Either of the following conditions has occurred: @n
 278          *                                                                      - The specified @c dueDate is earlier than the specified @c startDate.
 279          *                                                                      - The @c startDate or @c dueDate is not a valid range. @n
 280          *                                                                      The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().
 281          * @endif
 282          * @}
 283          */
 284         result SetStartAndDueDate(const Tizen::Base::DateTime& startDate, const Tizen::Base::DateTime& dueDate);
 285
 286         /**
 287          * @if OSPCOMPAT
 288          * @page        CompCalTodoSetStartAndDueDatePage Compatibility for SetStartAndDueDate()
 289          * @section     CompCalTodoSetStartAndDueDatePageIssueSection Issues
 290          *              Implementing this method in OSP compatible applications has the following issues: @n
 291          *                      -# The start and due date cannot be unset. And if the SetStartAndDueDate() is not called, the default start and due date @n
 292          *                      are set to the system time when the to-do is constructed.
 293          *
 294          * @section     CompCalTodoSetStartAndDueDatePageSolutionSection Resolutions
 295          *                      This issue has been resolved in Tizen. @n
 296          *                      -# The default start and due date of the to-do is unset.
 297          * @endif
 298          */
 299
 300         /**
 301          * Sets the start date for the current instance of %CalTodo. @n
 302          * If the @c startDate is minimum value of Tizen::Base::DateTime, the start date is changed to unset. @n
 303          * And if the start date is later than due date, the due date will be changed to unset.
 304          *
 305          * @since       2.0
 306          *
 307          * @return              An error code
 308          * @param[in]   startDate                       The start date. @n Any value with a unit that is less than a second is ignored.
 309          * @exception   E_SUCCESS               The method is successful. @n
 310          *                                                              Either @c startDate is between Calendarbook::GetMaxDateTime() and Calendarbook::GetMinDateTime(), or
 311          *                                                              @c startDate is the minimum value of Tizen::Base::DateTime to unset the start date.
 312          * @exception   E_INVALID_ARG   The specified @c start date is invalid.
 313          * @remarks             The minimum value can be acquired using Tizen::Base::DateTime::GetMinValue().
 314          */
 315         result SetStartDate(const Tizen::Base::DateTime& startDate);
 316
 317         /**
 318          * Sets the end date for the current instance of %CalTodo. @n
 319          * If the @c dueDate is minimum value of Tizen::Base::DateTime, the due date is changed to unset. @n
 320          * And if the due date is earlier than start date, the start date will be changed to unset.
 321          *
 322          * @since       2.0
 323          *
 324          * @return              An error code
 325          * @param[in]   dueDate                 The due date. @n Any value with a unit that is less than a second is ignored.
 326          * @exception   E_SUCCESS               The method is successful. @n
 327          *                                                              Either @c dueDate is between Calendarbook::GetMaxDateTime() and Calendarbook::GetMinDateTime(), or
 328          *                                                              @c dueDate is the minimum value of Tizen::Base::DateTime to unset the due date.
 329          * @exception   E_INVALID_ARG   The specified @c due date is invalid.
 330          * @remarks             The minimum value can be acquired using Tizen::Base::DateTime::GetMinValue().
 331          */
 332         result SetDueDate(const Tizen::Base::DateTime& dueDate);
 333
 334
 335         /**
 336          * Sets the priority level of the current instance of %CalTodo.
 337          *
 338          * @since       2.0
 339          *
 340          * @param[in]   priority                The priority level to set
 341          */
 342         void SetPriority(TodoPriority priority);
 343
 344         /**
 345          * Sets the status of the current instance of %CalTodo.
 346          *
 347          * @since       2.0
 348          *
 349          * @param[in]   status                  The status to set
 350          */
 351         void SetStatus(TodoStatus status);
 352
 353         /**
 354          * Sets the sensitivity of the current instance of %CalTodo.
 355          *
 356          * @since       2.0
 357          *
 358          * @param[in]   sensitivity             The sensitivity to set
 359          */
 360         void SetSensitivity(RecordSensitivity sensitivity);
 361
 362         /**
 363          * Sets the location of the current calendar event.
 364          *
 365          * @since       2.0
 366          *
 367          * @return              An error code
 368          * @param[in]   location                        The location of the event
 369          */
 370         void SetLocation(const Tizen::Base::String& location);
 371
 372         /**
 373          * Gets the location of the calendar event.
 374          *
 375          * @since       2.0
 376          *
 377          * @return              The location
 378          */
 379         Tizen::Base::String GetLocation(void) const;
 380
 381         /**
 382          * Sets the coordinates.
 383          *
 384          * @since       2.0
 385          *
 386          * @return              An error code
 387          * @param[in]   latitude                The latitude in the range @n The valid range is [-90.0, 90.0].
 388          * @param[in]   longitude               The longitude in the range @n The valid range is [-180.0, 180.0].
 389          * @exception   E_SUCCESS               The method is successful.
 390          * @exception   E_INVALID_ARG           The @c latitude or @c longitude is out of the valid range.
 391          */
 392         result SetCoordinates(double latitude, double longitude);
 393
 394         /**
 395          * Gets the coordinates.
 396          *
 397          * @since       2.0
 398          *
 399          * @return              An error code
 400          * @param[out]  latitude                The latitude
 401          * @param[out]  longitude               The longitude
 402          */
 403
 404         void GetCoordinates(double& latitude, double& longitude) const;
 405
 406         /**
 407          * Adds a reminder.
 408          *
 409          * @since       2.0
 410          *
 411          * @return              An error code
 412          * @param[in]   reminder                        The reminder to add
 413          * @exception   E_SUCCESS                       The method is successful.
 414          * @exception   E_OUT_OF_MEMORY         The memory is insufficient.
 415          */
 416         result AddReminder(const Reminder& reminder);
 417
 418         /**
 419          * Removes a reminder at the index.
 420          *
 421          * @since       2.0
 422          *
 423          * @return              An error code
 424          * @param[in]   index                           The index of reminder to remove
 425          * @exception   E_SUCCESS                       The method is successful.
 426          * @exception   E_OUT_OF_RANGE          The index is either equal to or greater than the number of reminders or less than @c 0.
 427          */
 428         result RemoveReminderAt(int index);
 429
 430         /**
 431          * Gets a list of all the reminders.
 432          *
 433          * @since       2.0
 434          *
 435          * @return              A list containing the Reminder instances, @n
 436          *                              else an empty list if there are no reminders
 437          */
 438         const Tizen::Base::Collection::IList& GetAllReminders(void) const;
 439
 440         /**
 441          * Gets the ID of the calendar to which this to-do belongs.
 442          *
 443          * @since       2.0
 444          *
 445          * @return              The calendar ID
 446          */
 447         RecordId GetCalendarId(void) const;
 448
 449         /**
 450          * Copying of objects using this copy assignment operator is allowed.
 451          *
 452          * @since       2.0
 453          *
 454          * @param[in]   rhs             An instance of %CalTodo
 455          */
 456         CalTodo& operator =(const CalTodo& rhs);
 457
 458 private:
 459         friend class _CalTodoImpl;
 460         class _CalTodoImpl* __pCalTodoImpl;
 461 };      // CalTodo
 462
 463 }}      // Tizen::Social
 464
 465 #endif // _FSCL_CAL_TODO_H_