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          * @cond OSPDEPREC
 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.
 261          *
 262          * @if OSPCOMPAT
 263          * @brief <i> [Deprecated] [Compatibility] </i>
 264          * @endif
 265          * @deprecated  This method is deprecated. Instead of using this method, it is recommended to use SetStartDate() and SetDueDate().
 266          * @since       2.0
 267          * @if OSPCOMPAT
 268          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
 269          *                              For more information, see @ref CompCalTodoSetStartAndDueDatePage "here".
 270          * @endif
 271          *
 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().
 280          * @endcond
 281          */
 282         result SetStartAndDueDate(const Tizen::Base::DateTime& startDate, const Tizen::Base::DateTime& dueDate);
 283
 284         /**
 285          * @if OSPCOMPAT
 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.
 291          *
 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.
 295          * @endif
 296          */
 297
 298         /**
 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.
 302          *
 303          * @since       2.0
 304          *
 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().
 312          */
 313         result SetStartDate(const Tizen::Base::DateTime& startDate);
 314
 315         /**
 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.
 319          *
 320          * @since       2.0
 321          *
 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().
 329          */
 330         result SetDueDate(const Tizen::Base::DateTime& dueDate);
 331
 332
 333         /**
 334          * Sets the priority level of the current instance of %CalTodo.
 335          *
 336          * @since       2.0
 337          *
 338          * @param[in]   priority                The priority level to set
 339          */
 340         void SetPriority(TodoPriority priority);
 341
 342         /**
 343          * Sets the status of the current instance of %CalTodo.
 344          *
 345          * @since       2.0
 346          *
 347          * @param[in]   status                  The status to set
 348          */
 349         void SetStatus(TodoStatus status);
 350
 351         /**
 352          * Sets the sensitivity of the current instance of %CalTodo.
 353          *
 354          * @since       2.0
 355          *
 356          * @param[in]   sensitivity             The sensitivity to set
 357          */
 358         void SetSensitivity(RecordSensitivity sensitivity);
 359
 360         /**
 361          * Sets the location of the current calendar event.
 362          *
 363          * @since       2.0
 364          *
 365          * @return              An error code
 366          * @param[in]   location                        The location of the event
 367          */
 368         void SetLocation(const Tizen::Base::String& location);
 369
 370         /**
 371          * Gets the location of the calendar event.
 372          *
 373          * @since       2.0
 374          *
 375          * @return              The location
 376          */
 377         Tizen::Base::String GetLocation(void) const;
 378
 379         /**
 380          * Sets the coordinates.
 381          *
 382          * @since       2.0
 383          *
 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.
 389          */
 390         result SetCoordinates(double latitude, double longitude);
 391
 392         /**
 393          * Gets the coordinates.
 394          *
 395          * @since       2.0
 396          *
 397          * @return              An error code
 398          * @param[out]  latitude                The latitude
 399          * @param[out]  longitude               The longitude
 400          */
 401
 402         void GetCoordinates(double& latitude, double& longitude) const;
 403
 404         /**
 405          * Adds a reminder.
 406          *
 407          * @since       2.0
 408          *
 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.
 413          */
 414         result AddReminder(const Reminder& reminder);
 415
 416         /**
 417          * Removes a reminder at the index.
 418          *
 419          * @since       2.0
 420          *
 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.
 425          */
 426         result RemoveReminderAt(int index);
 427
 428         /**
 429          * Gets a list of all the reminders.
 430          *
 431          * @since       2.0
 432          *
 433          * @return              A list containing the Reminder instances, @n
 434          *                              else an empty list if there are no reminders
 435          */
 436         const Tizen::Base::Collection::IList& GetAllReminders(void) const;
 437
 438         /**
 439          * Gets the ID of the calendar to which this to-do belongs.
 440          *
 441          * @since       2.0
 442          *
 443          * @return              The calendar ID
 444          */
 445         RecordId GetCalendarId(void) const;
 446
 447         /**
 448          * Copying of objects using this copy assignment operator is allowed.
 449          *
 450          * @since       2.0
 451          *
 452          * @param[in]   rhs             An instance of %CalTodo
 453          */
 454         CalTodo& operator =(const CalTodo& rhs);
 455
 456 private:
 457         friend class _CalTodoImpl;
 458         class _CalTodoImpl* __pCalTodoImpl;
 459 };      // CalTodo
 460
 461 }}      // Tizen::Social
 462
 463 #endif // _FSCL_CAL_TODO_H_