inc/FSclCalendarbook.h

   1 // \r
   2 // Open Service Platform\r
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd. \r
   4 // \r
   5 // Licensed under the Apache License, Version 2.0 (the License);\r
   6 // you may not use this file except in compliance with the License.\r
   7 // You may obtain a copy of the License at\r
   8 //\r
   9 //     http://www.apache.org/licenses/LICENSE-2.0\r
  10 //\r
  11 // Unless required by applicable law or agreed to in writing, software\r
  12 // distributed under the License is distributed on an "AS IS" BASIS,\r
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  14 // See the License for the specific language governing permissions and\r
  15 // limitations under the License.\r
  16 //\r
  17 /**\r
  18  * @file                FSclCalendarbook.h\r
  19  * @brief               This is the header file for the %Calendarbook class.\r
  20  *\r
  21  * This header file contains the declarations of the %Calendarbook class.\r
  22  */\r
  23 #ifndef _FSCL_CALENDARBOOK_H_\r
  24 #define _FSCL_CALENDARBOOK_H_\r
  25 \r
  26 #include <FBaseObject.h>\r
  27 #include <FBaseDataType.h>\r
  28 #include <FSclTypes.h>\r
  29 #include <FSclCalEvent.h>\r
  30 #include <FSclCalTodo.h>\r
  31 #include <FSclIRecordEventListener.h>\r
  32 #include <FSclIRecordListener.h>\r
  33 \r
  34 namespace Tizen { namespace Base\r
  35 {\r
  36 class String;\r
  37 class DateTime;\r
  38 namespace Collection\r
  39 {\r
  40 class IList;\r
  41 }\r
  42 }}\r
  43 \r
  44 namespace Tizen { namespace Locales\r
  45 {\r
  46 class TimeZone;\r
  47 }}\r
  48 \r
  49 \r
  50 namespace Tizen { namespace Social\r
  51 {\r
  52 \r
  53 class ICalendarbookEventListener;\r
  54 class Calendar;\r
  55 class CalEventInstance;\r
  56 class CalendarbookFilter;\r
  57 \r
  58 /**\r
  59  * @class       Calendarbook\r
  60  * @brief       This class manages the calendar data such as events, to-dos, and calendars.\r
  61  *\r
  62  * @since       2.0\r
  63  *\r
  64  * @final       This class is not intended for extension.\r
  65  *\r
  66  * The %Calendarbook class manages the calendar data such as events, to-dos, and calendars.\r
  67  * The calendar book is a centralized database that is used by multiple applications to store events and to-do information.\r
  68  * A calendar book represents the methods to read, add, remove, and update the events, to-do lists, and calendars stored in the device.\r
  69  * The users must be notified of changes in the calendar book as multiple applications can share, change, or remove the data.\r
  70  *\r
  71  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/social/calendarbook_namespace.htm">Calendar book</a>.\r
  72  *\r
  73  * The following example demonstrates how to use the %Calendarbook class to add calendarbook event.\r
  74  * @code\r
  75 \r
  76         #include <FSocial.h>\r
  77         #include <FLocales.h>\r
  78 \r
  79         using namespace Tizen::Social;\r
  80         using namespace Tizen::Base;\r
  81         using namespace Tizen::Locales;\r
  82 \r
  83         void\r
  84         MyCalendarbook::AddEventExample(void)\r
  85         {\r
  86                 result r = E_SUCCESS;\r
  87 \r
  88                 DateTime startWallTime;\r
  89                 DateTime endWallTime;\r
  90                 DateTime startUtcTime;\r
  91                 DateTime endUtcTime;\r
  92 \r
  93                 // Suppose a user set 2012/7/17 12:00:00 ~ 2012/7/17 14:00:00 in wall time for start/end time\r
  94                 startWallTime.SetValue(2012, 7, 17, 12, 0, 0);\r
  95                 endWallTime.SetValue(2012, 7, 17, 14, 0, 0);\r
  96 \r
  97                 // Gets the system time zone\r
  98                 LocaleManager localeManager;\r
  99                 localeManager.Construct();\r
 100 \r
 101                 TimeZone timeZone = localeManager.GetSystemTimeZone();\r
 102 \r
 103                 // Converts the wall time to UTC time before set start and end time of the event\r
 104                 startUtcTime = timeZone.WallTimeToUtcTime(startWallTime);\r
 105                 endUtcTime = timeZone.WallTimeToUtcTime(endWallTime);\r
 106 \r
 107                 // Creates a CalEvent instance\r
 108                 CalEvent newEvent;\r
 109                 newEvent.SetSubject(L"Daily event");\r
 110                 newEvent.SetStartAndEndTime(startUtcTime, endUtcTime);\r
 111 \r
 112                 Recurrence dailyRecurrence;\r
 113                 dailyRecurrence.SetFrequency(FREQ_DAILY);\r
 114                 dailyRecurrence.SetCounts(10);\r
 115 \r
 116                 newEvent.SetRecurrence(&dailyRecurrence);\r
 117 \r
 118                 // Creates a Calendarbook instance\r
 119                 Calendarbook* pCalendarbook = new Calendarbook();\r
 120                 r = pCalendarbook->Construct();\r
 121                 if (IsFailed(r))\r
 122                 {\r
 123                         AppLogException("initializing the calendar book has failed");\r
 124                         delete pCalendarbook;\r
 125                         return;\r
 126                 }\r
 127 \r
 128                 // Adds the event\r
 129                 r = pCalendarbook->AddEvent(newEvent);\r
 130                 if (IsFailed(r))\r
 131                 {\r
 132                         AppLogException("AddEvent() has failed");\r
 133                         delete pCalendarbook;\r
 134                         return;\r
 135                 }\r
 136 \r
 137                 delete pCalendarbook;\r
 138         }\r
 139 \r
 140  * @endcode\r
 141  *\r
 142  * The following example demonstrates how to use the %Calendarbook class to update calendarbook event.\r
 143  * @code\r
 144 \r
 145         #include <FSocial.h>\r
 146         #include <FLocales.h>\r
 147 \r
 148         using namespace Tizen::Social;\r
 149         using namespace Tizen::Base;\r
 150         using namespace Tizen::Locales;\r
 151 \r
 152         void\r
 153         MyCalendarbook::UpdateEventExample(void)\r
 154         {\r
 155                 result r = E_SUCCESS;\r
 156 \r
 157                 // This specificEventId should have been set as already added event record ID.\r
 158                 RecordId specificEventId = 0;\r
 159 \r
 160                 DateTime changedStartWallTime;\r
 161                 DateTime changedEndWallTime;\r
 162                 DateTime changedStartUtcTime;\r
 163                 DateTime changedEndUtcTime;\r
 164 \r
 165                 // Suppose a user set 2012/7/18 12:00:00 ~ 2012/7/18 14:00:00 in wall time for start/end time.\r
 166                 changedStartWallTime.SetValue(2012, 7, 18, 12, 0, 0);\r
 167                 changedEndWallTime.SetValue(2012, 7, 18, 14, 0, 0);\r
 168 \r
 169                 // Gets the system time zone.\r
 170                 LocaleManager localeManager;\r
 171                 localeManager.Construct();\r
 172 \r
 173                 TimeZone timeZone = localeManager.GetSystemTimeZone();\r
 174 \r
 175                 // Converts the wall time to UTC time before set start and end time of the event.\r
 176                 changedStartUtcTime = timeZone.WallTimeToUtcTime(changedStartWallTime);\r
 177                 changedEndUtcTime = timeZone.WallTimeToUtcTime(changedEndWallTime);\r
 178 \r
 179                 // Creates Calendarbook instance.\r
 180                 Calendarbook* pCalendarbook = new Calendarbook();\r
 181                 r = pCalendarbook->Construct();\r
 182                 if (IsFailed(r))\r
 183                 {\r
 184                         AppLogException("initializing the calendar book has failed");\r
 185                         delete pCalendarbook;\r
 186                         return;\r
 187                 }\r
 188 \r
 189                 // Retrieves CalEvent instance.\r
 190                 CalEvent* pEvent = pCalendarbook->GetEventN(specificEventId);\r
 191                 if (pEvent == null)\r
 192                 {\r
 193                         AppLogException("Getting the event has failed");\r
 194                         delete pCalendarbook;\r
 195                         return;\r
 196                 }\r
 197 \r
 198                 Recurrence recurrence(*pEvent->GetRecurrence());\r
 199                 pEvent->SetRecurrence(null);\r
 200                 pEvent->SetStartAndEndTime(changedStartUtcTime, changedEndUtcTime);\r
 201                 pEvent->SetRecurrence(&recurrence);\r
 202 \r
 203                 // Updates the event.\r
 204                 r = pCalendarbook->UpdateEvent(*pEvent);\r
 205                 if (IsFailed(r))\r
 206                 {\r
 207                         AppLogException("UpdateEvent() has failed");\r
 208                         delete pEvent;\r
 209                         delete pCalendarbook;\r
 210                         return;\r
 211                 }\r
 212 \r
 213                 delete pEvent;\r
 214                 delete pCalendarbook;\r
 215         }\r
 216 \r
 217  * @endcode\r
 218  *\r
 219  * The following example demonstrates how to use the %Calendarbook class to retrieve event instance list.\r
 220  * @code\r
 221 \r
 222         #include <FSocial.h>\r
 223         #include <FLocales.h>\r
 224 \r
 225         using namespace Tizen::Social;\r
 226         using namespace Tizen::Base;\r
 227         using namespace Tizen::Locales;\r
 228         using namespace Tizen::Base::Collection;\r
 229 \r
 230         void\r
 231         MyCalendarbook::RetrieveEventInstanceExample(void)\r
 232         {\r
 233                 result r = E_SUCCESS;\r
 234 \r
 235                 DateTime startRange;\r
 236                 DateTime endRange;\r
 237                 IList* pEventInstanceList = null;\r
 238 \r
 239                 DateTime startRangeWallTime;\r
 240                 DateTime endRangeWallTime;\r
 241                 DateTime startRangeUtcTime;\r
 242                 DateTime endRangeUtcTime;\r
 243 \r
 244                 // Suppose a user set 2012/7/1 00:00:00 ~ 2012/7/31 23:59:59 in wall time for start/end time.\r
 245                 startRangeWallTime.SetValue(2012, 7, 1, 0, 0, 0);\r
 246                 endRangeWallTime.SetValue(2012, 7, 31, 23, 59, 59);\r
 247 \r
 248                 // Gets the system time zone.\r
 249                 LocaleManager localeManager;\r
 250                 localeManager.Construct();\r
 251 \r
 252                 TimeZone timeZone = localeManager.GetSystemTimeZone();\r
 253 \r
 254                 // Converts the wall time to UTC time before set start and end time of the event.\r
 255                 startRangeUtcTime = timeZone.WallTimeToUtcTime(startRangeWallTime);\r
 256                 endRangeUtcTime = timeZone.WallTimeToUtcTime(endRangeWallTime);\r
 257 \r
 258                 // Creates Calendarbook instance.\r
 259                 Calendarbook* pCalendarbook = new Calendarbook();\r
 260                 r = pCalendarbook->Construct();\r
 261                 if (IsFailed(r))\r
 262                 {\r
 263                         AppLogException("initializing the calendar book has failed");\r
 264                         delete pCalendarbook;\r
 265                         return;\r
 266                 }\r
 267 \r
 268                 // Gets the event instances.\r
 269                 CalendarbookFilter filter(CB_FI_TYPE_NON_ALL_DAY_EVENT_INSTANCE);\r
 270                 filter.AppendDateTime(FI_CONJ_OP_NONE, EVENT_INST_FI_PR_END_TIME, FI_CMP_OP_GREATER_THAN, startRangeUtcTime);\r
 271                 filter.AppendDateTime(FI_CONJ_OP_AND, EVENT_INST_FI_PR_START_TIME, FI_CMP_OP_LESS_THAN, endRangeUtcTime);\r
 272 \r
 273                 pEventInstanceList = pCalendarbook->SearchN(filter, EVENT_INST_FI_PR_START_TIME, SORT_ORDER_ASCENDING);\r
 274                 if (pEventInstanceList == null)\r
 275                 {\r
 276                         AppLogException("SearchN() is failed");\r
 277                         delete pCalendarbook;\r
 278                         return;\r
 279                 }\r
 280 \r
 281                 IEnumerator* pEnum = pEventInstanceList->GetEnumeratorN();\r
 282                 while (pEnum->MoveNext() == E_SUCCESS)\r
 283                 {\r
 284                         CalEventInstance* pEventInstance = static_cast<CalEventInstance*>(pEnum->GetCurrent());\r
 285 \r
 286                         // Reads the properties of pEventInstance.\r
 287                         // ...\r
 288                 }\r
 289                 delete pEnum;\r
 290 \r
 291                 // Removes the first event instance of the list.\r
 292                 CalEventInstance* pExcludingEventInstance = static_cast<CalEventInstance*>(pEventInstanceList->GetAt(0));\r
 293                 r = pCalendarbook->RemoveEventInstance(*pExcludingEventInstance);\r
 294                 if (IsFailed(r))\r
 295                 {\r
 296                         AppLogException("RemoveEventInstance() has failed");\r
 297                         pEventInstanceList->RemoveAll(true);\r
 298                         delete pEventInstanceList;\r
 299                         delete pCalendarbook;\r
 300                         return;\r
 301                 }\r
 302 \r
 303                 pEventInstanceList->RemoveAll(true);\r
 304                 delete pEventInstanceList;\r
 305                 delete pCalendarbook;\r
 306         }\r
 307 \r
 308  * @endcode\r
 309  */\r
 310 \r
 311 class _OSP_EXPORT_ Calendarbook\r
 312         : public Tizen::Base::Object\r
 313 {\r
 314 public:\r
 315 \r
 316         /**\r
 317          * The object is not fully constructed after this constructor is called. For full construction, @n\r
 318          * the Construct() method must be called right after calling this constructor.\r
 319          *\r
 320          * @since       2.0\r
 321          */\r
 322         Calendarbook(void);\r
 323 \r
 324         /**\r
 325          * This destructor overrides Tizen::Base::Object::~Object().\r
 326          *\r
 327          * @since       2.0\r
 328          */\r
 329         virtual ~Calendarbook(void);\r
 330 \r
 331         /**\r
 332          * @if OSPDEPREC\r
 333          * Initializes this instance of %Calendarbook with the specified event listener.\r
 334          *\r
 335          * @brief <i> [Deprecated] </i>\r
 336          * @deprecated  This method is deprecated. Instead of using this method, it is recommended to use Construct(ICalendarbookEventListener*).\r
 337          * @since       2.0\r
 338          *\r
 339          * @return              An error code\r
 340          * @param[in]   pListener                               The event listener to register, @n\r
 341          *                                                                              else @c null if an event listener need not be registered\r
 342          * @exception   E_SUCCESS                               The method is successful.\r
 343          * @exception   E_SYSTEM                                A system error has occurred.\r
 344          * @endif\r
 345          */\r
 346         result Construct(IRecordEventListener* pListener);\r
 347 \r
 348         /**\r
 349          * Initializes this instance of %Calendarbook.\r
 350          *\r
 351          * @since       2.0\r
 352          *\r
 353          * @return              An error code\r
 354          * @exception   E_SUCCESS                               The method is successful.\r
 355          * @exception   E_SYSTEM                                A system error has occurred.\r
 356          */\r
 357         result Construct(void);\r
 358 \r
 359         /**\r
 360          * Initializes this instance of %Calendarbook with the specified event listener.\r
 361          *\r
 362          * @since       2.0\r
 363          *\r
 364          * @return              An error code\r
 365          * @param[in]   listener                                The event listener to register\r
 366          * @exception   E_SUCCESS                               The method is successful.\r
 367          * @exception   E_SYSTEM                                A system error has occurred.\r
 368          */\r
 369         result Construct(ICalendarbookEventListener& listener);\r
 370 \r
 371         /**\r
 372          * Adds an event of the default calendar to the calendar book. @n\r
 373          * After adding the event successfully, the event has a valid record ID.\r
 374          *\r
 375          * @since       2.0\r
 376          * @privlevel   public\r
 377          * @privilege   %http://tizen.org/privilege/calendar.write\r
 378          *\r
 379          * @return              An error code\r
 380          * @param[in,out]       event                                   The event to add\r
 381          * @exception   E_SUCCESS                               The method is successful.\r
 382          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 383          * @exception   E_INVALID_ARG                   The specified @c event is invalid.\r
 384          * @exception   E_STORAGE_FULL                  The storage is insufficient.\r
 385          * @exception   E_SYSTEM                                A system error has occurred.\r
 386          */\r
 387         result AddEvent(CalEvent& event);\r
 388 \r
 389         /**\r
 390          * Adds an event of the specific calendar to the calendar book. @n\r
 391          * After adding the event successfully, the event has a valid record ID.\r
 392          *\r
 393          * @since       2.0\r
 394          * @privlevel   public\r
 395          * @privilege   %http://tizen.org/privilege/calendar.write\r
 396          *\r
 397          * @return              An error code\r
 398          * @param[in,out]       event                                   The event to add\r
 399          * @param[in]   calendarId                              The calendar ID\r
 400          * @exception   E_SUCCESS                               The method is successful.\r
 401          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 402          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
 403          *                                                                              - The specified @c event is invalid. @n\r
 404          *                                                                      - The specified @c calendarId is invalid. @n\r
 405          *                                                                      - The specified calendar is created for CALENDAR_ITEM_TYPE_TODO.\r
 406          * @exception   E_OBJ_NOT_FOUND                 The specified calendar is not found.\r
 407          * @exception   E_STORAGE_FULL                  The storage is insufficient.\r
 408          * @exception   E_SYSTEM                                A system error has occurred.\r
 409          */\r
 410         result AddEvent(CalEvent& event, RecordId calendarId);\r
 411 \r
 412         /**\r
 413          * Adds a to-do of the default calendar to the calendar book. @n\r
 414          * After adding the to-do item successfully, the item has a valid record ID.\r
 415          *\r
 416          * @since       2.0\r
 417          * @privlevel   public\r
 418          * @privilege   %http://tizen.org/privilege/calendar.write\r
 419          *\r
 420          * @return              An error code\r
 421          * @param[in,out]       todo                                    The to-do to add\r
 422          * @exception   E_SUCCESS                               The method is successful.\r
 423          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 424          * @exception   E_INVALID_ARG                   The specified @c todo is invalid.\r
 425          * @exception   E_STORAGE_FULL                  The storage is insufficient.\r
 426          * @exception   E_SYSTEM                                A system error has occurred.\r
 427          */\r
 428         result AddTodo(CalTodo& todo);\r
 429 \r
 430         /**\r
 431          * Adds a to-do of the specific calendar to the calendar book. @n\r
 432          * After adding the to-do item successfully, the item has a valid record ID.\r
 433          *\r
 434          * @since       2.0\r
 435          * @privlevel   public\r
 436          * @privilege   %http://tizen.org/privilege/calendar.write\r
 437          *\r
 438          * @return              An error code\r
 439          * @param[in,out]       todo                                    The to-do to add\r
 440          * @param[in]   calendarId                              The calendar ID\r
 441          * @exception   E_SUCCESS                               The method is successful.\r
 442          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 443          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
 444          *                                                                      - The specified @c todo is invalid. @n\r
 445          *                                                                      - The specified @c calendarId is invalid. @n\r
 446          *                                                                      - The specified calendar is created for CALENDAR_ITEM_TYPE_EVENT.\r
 447          * @exception   E_OBJ_NOT_FOUND                 The specified calendar is not found.\r
 448          * @exception   E_STORAGE_FULL                  The storage is insufficient.\r
 449          * @exception   E_SYSTEM                                A system error has occurred.\r
 450          */\r
 451         result AddTodo(CalTodo& todo, RecordId calendarId);\r
 452 \r
 453         /**\r
 454          * Removes the specified calendar event from this calendar book. @n\r
 455          * After removing the event successfully, the event has #INVALID_RECORD_ID.\r
 456          *\r
 457          * @since       2.0\r
 458          * @privlevel   public\r
 459          * @privilege   %http://tizen.org/privilege/calendar.write\r
 460          *\r
 461          * @return              An error code\r
 462          * @param[in]   event                           The calendar event to remove\r
 463          * @exception   E_SUCCESS                               The method is successful.\r
 464          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 465          * @exception   E_INVALID_ARG                   The specified @c recordId is #INVALID_RECORD_ID.\r
 466          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 467          * @exception   E_INVALID_OPERATION             This method cannot be used for the recurrence exception of the recurring event. @n\r
 468          *                                                                              RemoveEventInstance() should be used instead of this method. @b Since: @b 2.1\r
 469          * @exception   E_SYSTEM                                A system error has occurred.\r
 470          */\r
 471         result RemoveEvent(CalEvent& event);\r
 472 \r
 473         /**\r
 474          * Removes the specified calendar event from this calendar book.\r
 475          *\r
 476          * @since       2.0\r
 477          * @privlevel   public\r
 478          * @privilege   %http://tizen.org/privilege/calendar.write\r
 479          *\r
 480          * @return              An error code\r
 481          * @param[in]   eventId                                 The calendar event ID to remove\r
 482          * @exception   E_SUCCESS                               The method is successful.\r
 483          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 484          * @exception   E_INVALID_ARG                   The specified @c eventId is #INVALID_RECORD_ID.\r
 485          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 486          * @exception   E_INVALID_OPERATION             This method cannot be used for the recurrence exception of the recurring event. @n\r
 487          *                                                                              RemoveEventInstance() should be used instead of this method. @b Since: @b 2.1\r
 488          * @exception   E_SYSTEM                                A system error has occurred.\r
 489          */\r
 490         result RemoveEvent(RecordId eventId);\r
 491 \r
 492         /**\r
 493          * Removes the specified CalTodo instance from the calendar book. @n\r
 494          * After removing the to-do item successfully, the item has #INVALID_RECORD_ID.\r
 495          *\r
 496          * @since       2.0\r
 497          * @privlevel   public\r
 498          * @privilege   %http://tizen.org/privilege/calendar.write\r
 499          *\r
 500          * @return              An error code\r
 501          * @param[in]   todo                                    The CalTodo ID to remove\r
 502          * @exception   E_SUCCESS                               The method is successful.\r
 503          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 504          * @exception   E_INVALID_ARG                   The specified @c recordId is #INVALID_RECORD_ID.\r
 505          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 506          * @exception   E_SYSTEM                                A system error has occurred.\r
 507          */\r
 508         result RemoveTodo(CalTodo& todo);\r
 509 \r
 510         /**\r
 511          * Removes the specified CalTodo instance from the calendar book.\r
 512          *\r
 513          * @since       2.0\r
 514          * @privlevel   public\r
 515          * @privilege   %http://tizen.org/privilege/calendar.write\r
 516          *\r
 517          * @return              An error code\r
 518          * @param[in]   todoId                                  The CalTodo ID to remove\r
 519          * @exception   E_SUCCESS                               The method is successful.\r
 520          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 521          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.\r
 522          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 523          * @exception   E_SYSTEM                                A system error has occurred.\r
 524          */\r
 525         result RemoveTodo(RecordId todoId);\r
 526 \r
 527         /**\r
 528          * Updates the specified calendar event to the internal data storage.\r
 529          *\r
 530          * @since       2.0\r
 531          * @privlevel   public\r
 532          * @privilege   %http://tizen.org/privilege/calendar.write\r
 533          *\r
 534          * @return              An error code\r
 535          * @param[in]   event                           The CalEvent instance to update\r
 536          * @exception   E_SUCCESS                               The method is successful.\r
 537          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 538          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
 539          *                                                                              - The specified @c recordId is #INVALID_RECORD_ID. @n\r
 540          *                                                                              - The specified @c event is not #RECORD_TYPE_EVENT. @n\r
 541          *                                                                              - The specified @c event is not an entry type instance. @n\r
 542          *                                                                              - The date of the event is invalid. @n\r
 543          *                                                                              The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().\r
 544          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 545          * @exception   E_INVALID_OPERATION             This method cannot be used for the recurrence exception of the recurring event. @n\r
 546          *                                                                              UpdateEventInstance() should be used instead of this method. @b Since: @b 2.1\r
 547          * @exception   E_SYSTEM                                A system error has occurred.\r
 548          */\r
 549         result UpdateEvent(const CalEvent& event);\r
 550 \r
 551         /**\r
 552          * Updates the specified CalTodo instance on the internal data storage.\r
 553          *\r
 554          * @since       2.0\r
 555          * @privlevel   public\r
 556          * @privilege   %http://tizen.org/privilege/calendar.write\r
 557          *\r
 558          * @return              An error code\r
 559          * @param[in]   todo                                    The CalTodo instance to update\r
 560          * @exception   E_SUCCESS                               The method is successful.\r
 561          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 562          * @exception   E_INVALID_ARG                   The specified @c recordId is #INVALID_RECORD_ID, or the date of the to-do item is invalid. @n\r
 563          *                                                                              The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().\r
 564          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 565          * @exception   E_SYSTEM                                A system error has occurred.\r
 566          */\r
 567         result UpdateTodo(const CalTodo& todo);\r
 568 \r
 569         /**\r
 570          * Gets the specified event ID that is matched with the RecordId.\r
 571          *\r
 572          * @since       2.0\r
 573          * @privlevel   public\r
 574          * @privilege   %http://tizen.org/privilege/calendar.read\r
 575          *\r
 576          * @return              The matched event\r
 577          * @param[in]   eventId                                 The event ID to find\r
 578          * @exception   E_SUCCESS                               The method is successful.\r
 579          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 580          * @exception   E_INVALID_ARG                   The specified @c eventId is invalid.\r
 581          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 582          * @exception   E_SYSTEM                                A system error has occurred.\r
 583          * @remarks                     The specific error code can be accessed using the GetLastResult() method.\r
 584          */\r
 585         CalEvent* GetEventN(RecordId eventId) const;\r
 586 \r
 587         /**\r
 588          * Gets the specified to-do after matching it with the specified record ID.\r
 589          *\r
 590          * @since       2.0\r
 591          * @privlevel   public\r
 592          * @privilege   %http://tizen.org/privilege/calendar.read\r
 593          *\r
 594          * @return              The matched to-do\r
 595          * @param[in]   todoId                                  The ID of the to-do to find\r
 596          * @exception   E_SUCCESS                               The method is successful.\r
 597          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 598          * @exception   E_INVALID_ARG                   The specified @c todoId is invalid.\r
 599          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 600          * @exception   E_SYSTEM                                A system error has occurred.\r
 601          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 602          *\r
 603          */\r
 604         CalTodo* GetTodoN(RecordId todoId) const;\r
 605 \r
 606         /**\r
 607          * Gets all the to-do items in the specified time range. @n\r
 608          * To-do items, whose due date is within the retrieving range, is retrieved.\r
 609          *\r
 610          * @if OSPCOMPAT\r
 611          * @brief <i> [Compatibility] </i>\r
 612          * @endif\r
 613          * @since       2.0\r
 614          * @if OSPCOMPAT\r
 615          * @compatibility This method has compatibility issues with OSP compatible applications. @n\r
 616          *                For more information, see @ref CompCalendarbookGetTodosNPage "here".\r
 617          * @endif\r
 618          * @privlevel   public\r
 619          * @privilege   %http://tizen.org/privilege/calendar.read\r
 620          *\r
 621          * @return              A list of all the matched CalTodo instances, @n\r
 622          *                              else an empty list if there is no matched to-do item @n\r
 623          *                              The items are sorted by due date.\r
 624          * @param[in]   start                                   The start of the time range\r
 625          * @param[in]   end                                             The end of the time range\r
 626          * @param[in]   pageNo                                  The page number of the result list @n\r
 627          *                                                                              It starts from @c 1.\r
 628          * @param[in]   countPerPage                    The desired maximum count of the result items per page\r
 629          * @param[in]   status                                  The to-do status @n\r
 630          *                                                                              If a specific status is set, the to-dos that have the specified status are returned. @n\r
 631          *                                                                              The default status value is #TODO_STATUS_ALL, which means all the statuses are returned.\r
 632          * @param[in]   priority                                The to-do priority @n\r
 633          *                                                                              If a specific priority is set, the to-dos that have the specified priority are returned. @n\r
 634          *                                                                              The default priority value is #TODO_PRIORITY_ALL that means all the priorities are returned.\r
 635          * @exception   E_SUCCESS                               The method is successful.\r
 636          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 637          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
 638          *                                                                              - The specified @c pageNo or @c countPerPage is less than @c 1. @n\r
 639          *                                                                              - The start time is later than the end date. @n\r
 640          *                                                                              - The start or end time is not in a valid range. @n\r
 641          *                                                                               The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().\r
 642          * @exception   E_SYSTEM                                A system error has occurred.\r
 643          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 644          */\r
 645         Tizen::Base::Collection::IList* GetTodosN(const Tizen::Base::DateTime& start, const Tizen::Base::DateTime& end, int pageNo, int countPerPage, unsigned long status = TODO_STATUS_ALL,\r
 646                                                         unsigned long priority = TODO_PRIORITY_ALL) const;\r
 647 \r
 648         /**\r
 649          * @if OSPCOMPAT\r
 650          * @page        CompCalendarbookGetTodosNPage Compatibility for GetTodosN()\r
 651          * @section     CompCalendarbookGetTodosNPageIssueSection Issues\r
 652          *           Implementing this method in OSP compatible applications has the following issues:   @n\r
 653          *                      -# If the start date of a to-do is not in the time range of start/end parameters, @n\r
 654          *                      the to-do is not retrieved even though the due date is in the time range.\r
 655          *\r
 656          * @section     CompCalendarbookGetTodosNPageSolutionSection Resolutions\r
 657          *                      This issue has been resolved in Tizen.  @n\r
 658          *                      -# The to-do will be retrieved if the due date is in the range of start/end parameters.\r
 659          * @endif\r
 660          */\r
 661 \r
 662         /**\r
 663          * Gets the total number of to-do items in the specified time range. @n\r
 664          * To-do items, whose due date is within the retrieving range, is counted.\r
 665          *\r
 666          * @if OSPCOMPAT\r
 667          * @brief <i> [Compatibility] </i>\r
 668          * @endif\r
 669          * @since       2.0\r
 670          * @if OSPCOMPAT\r
 671          * @compatibility This method has compatibility issues with OSP compatible applications. @n\r
 672          *                For more information, see @ref CompCalendarbookGetTodoCountPage "here".\r
 673          * @endif\r
 674          * @privlevel   public\r
 675          * @privilege   %http://tizen.org/privilege/calendar.read\r
 676          *\r
 677          * @return              The total number of to-dos, @n\r
 678          *                                                                              else @c -1 if an exception occurs\r
 679          * @param[in]   start                                   The start of the time range\r
 680          * @param[in]   end                                             The end of the time range\r
 681          * @param[in]   status                                  The to-do status @n\r
 682          *                                                                              If a specific status is set, the to-dos that have the specified status are returned. @n\r
 683          *                                                                              The default status value is #TODO_STATUS_ALL, which means all the statuses are returned.\r
 684          * @param[in]   priority                                The to-do priority @n\r
 685          *                                                                              If a specific priority is set, the to-dos that have the specified priority are returned. @n\r
 686          *                                                                              The default priority value is #TODO_PRIORITY_ALL that means all the priorities are returned.\r
 687          * @exception   E_SUCCESS                               The method is successful.\r
 688          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 689          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
 690          *                                                                              - The start time is later than the end date. @n\r
 691          *                                                                              - The start or end time is not in a valid range. @n\r
 692          *                                                                              The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().\r
 693          * @exception   E_SYSTEM                                A system error has occurred.\r
 694          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 695          */\r
 696         int GetTodoCount(const Tizen::Base::DateTime& start, const Tizen::Base::DateTime& end, unsigned long status = TODO_STATUS_ALL, unsigned long priority = TODO_PRIORITY_ALL) const;\r
 697 \r
 698         /**\r
 699          * @if OSPCOMPAT\r
 700          * @page        CompCalendarbookGetTodoCountPage Compatibility for GetTodoCount()\r
 701          * @section     CompCalendarbookGetTodoCountPageIssueSection Issues\r
 702          *           Implementing this method in OSP compatible applications has the following issues:   @n\r
 703          *                      -# If the start date of a to-do is not in the time range of start/end parameters, @n\r
 704          *                      the to-do is not counted even though the due date is in the time range.\r
 705          *\r
 706          * @section     CompCalendarbookGetTodoCountPageSolutionSection Resolutions\r
 707          *                      This issue has been resolved in Tizen.  @n\r
 708          *                      -# The to-do will be counted if the due date is in the range of start/end parameters.\r
 709          * @endif\r
 710          */\r
 711 \r
 712         /**\r
 713          * @if OSPDEPREC\r
 714          * Gets the CalEvent instances that are within the specified time range. @n\r
 715          * The all day events are retrieved by their start and end dates in the local time zone, while all other events are retrieved by their\r
 716          * start and end times in Coordinated Universal Time (UTC).\r
 717          *\r
 718          * @brief <i> [Deprecated] </i>\r
 719          * @deprecated  This method is deprecated. Instead of using this method, it is recommended to use GetInstancesOfAllDayEventsN() or GetInstancesOfNonAllDayEventsN().\r
 720          * @since       2.0\r
 721          * @privlevel   public\r
 722          * @privilege   %http://tizen.org/privilege/calendar.read\r
 723          *\r
 724          * @return              A list containing all of the matched CalEvent instances, @n\r
 725          *                              else an empty list if there are no matched instances or @c null if an exception occurs @n\r
 726          *                              The results are listed in the following order: all day events, and other events. @n\r
 727          *                              The results with the same property of all day event are ordered by their start time.\r
 728          * @param[in]   start                           The start of the time range\r
 729          * @param[in]   end                                     The end of the time range\r
 730          * @param[in]   timeZone                        The time zone of the specified start and end times\r
 731          * @param[in]   pageNo                          The page number of the result list @n\r
 732          *                                                                      It starts from @c 1.\r
 733          * @param[in]   countPerPage            The desired maximum count of the result items per page\r
 734          * @param[in]   category                        The event category @n\r
 735          *                                                                      If a specific category is set, the events that have the specified category are returned. @n\r
 736          *                                                                      The default category value is #EVENT_CATEGORY_ALL, which means all the categories are returned.\r
 737          * @exception   E_SUCCESS                       The method is successful.\r
 738          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.\r
 739          * @exception   E_INVALID_ARG           Either of the following conditions has occurred: @n\r
 740          *                                                                      - The specified @c pageNo or @c countPerPage is less than @c 1. @n\r
 741          *                                                                      - The specified @c category is invalid. @n\r
 742          *                                                                      - The start time is later than the end date. @n\r
 743          *                                                                      - The start or end time is not in a valid range. @n\r
 744          *                                                                      The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().\r
 745          * @exception   E_SYSTEM                        A system error has occurred.\r
 746          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 747          * @endif\r
 748          */\r
 749         Tizen::Base::Collection::IList* GetEventInstancesN(const Tizen::Base::DateTime& start, const Tizen::Base::DateTime& end,\r
 750                                                                          const Tizen::Locales::TimeZone& timeZone, int pageNo, int countPerPage,\r
 751                                                                          unsigned long category = EVENT_CATEGORY_ALL) const;\r
 752 \r
 753         /**\r
 754          * @if OSPDEPREC\r
 755          * Gets the CalEvent instances that are within the specified time range. @n\r
 756          * The all day events are retrieved by their start and end dates in the local time zone, while all other events are retrieved by their\r
 757          * start and end times in Coordinated Universal Time (UTC).\r
 758          *\r
 759          * Although GetEventInstancesN() retrieves the data synchronously, this method returns data asynchronously using\r
 760          * RecordListener::OnEventInstancesReceivedN(). @n\r
 761          * It is highly recommended to use the asynchronous method because getting the event instances may take a long time.\r
 762          *\r
 763          * @brief <i> [Deprecated] </i>\r
 764          * @deprecated  This method is deprecated. Instead of using this method, it is recommended to use GetInstancesOfAllDayEventsN() or GetInstancesOfNonAllDayEventsN().\r
 765          * @since       2.0\r
 766          * @privlevel   public\r
 767          * @privilege   %http://tizen.org/privilege/calendar.read\r
 768          *\r
 769          * @return              An error code\r
 770          * @param[in]   start                                   The start of the time range\r
 771          * @param[in]   end                                     The end of the time range\r
 772          * @param[in]   timeZone                                The time zone of the specified start and end times\r
 773          * @param[in]   pageNo                                  The page number of the result list @n\r
 774          *                                                                      It starts from @c 1.\r
 775          * @param[in]   countPerPage                    The desired maximum count of the result items per page\r
 776          * @param[in]   category                                The event category @n\r
 777          *                                                                      If a specific category is set, the events that have the specified @c category are returned. @n\r
 778          *                                                                      The default category value is #EVENT_CATEGORY_ALL, which means all the categories are returned.\r
 779          * @param[out]  reqId                           The ID of the request\r
 780          * @param[in]   listener                                The listener for receiving the responses of the request\r
 781          * @exception   E_SUCCESS                               The method is successful.\r
 782          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 783          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
 784          *                                                                      - The specified @c pageNo or @c countPerPage is less than @c 1. @n\r
 785          *                                                                      - The specified @c category is invalid. @n\r
 786          *                                                                      - The start time is later than the end date. @n\r
 787          *                                                                      - The start or end time is not in a valid range. @n\r
 788          *                                                                      The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().\r
 789          * @exception   E_SYSTEM                                A system error has occurred.\r
 790          * @remarks             IRecordListener::OnRecordsReceivedN(), Calendarbook::GetEventInstancesN()\r
 791          * @endif\r
 792          */\r
 793         result GetEventInstances(const Tizen::Base::DateTime& start, const Tizen::Base::DateTime& end,\r
 794                                                                         const Tizen::Locales::TimeZone& timeZone, int pageNo, int countPerPage, unsigned long category,\r
 795                                                                         RequestId& reqId,\r
 796                                                                         const IRecordListener& listener) const;\r
 797 \r
 798         /**\r
 799          * Gets all events.\r
 800          *\r
 801          * @since       2.0\r
 802          * @privlevel   public\r
 803          * @privilege   %http://tizen.org/privilege/calendar.read\r
 804          *\r
 805          * @return              A list containing all the CalEvent instances, @n\r
 806          *                              else an empty list if there are no events or @c null if an exception occurs @n\r
 807          *                              The results are listed in the order of their event ID.\r
 808          * @exception   E_SUCCESS                               The method is successful.\r
 809          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 810          * @exception   E_SYSTEM                                A system error has occurred.\r
 811          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 812          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
 813          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
 814          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
 815          */\r
 816         Tizen::Base::Collection::IList* GetAllEventsN(void) const;\r
 817 \r
 818         /**\r
 819          * Gets all to-dos.\r
 820          *\r
 821          * @since       2.0\r
 822          * @privlevel   public\r
 823          * @privilege   %http://tizen.org/privilege/calendar.read\r
 824          *\r
 825          * @return              A list containing all the CalTodo instances, @n\r
 826          *                              else an empty list if there are no to-dos or @c null if an exception occurs @n\r
 827          *                              The results are listed in the order of their to-do ID.\r
 828          * @exception   E_SUCCESS                               The method is successful.\r
 829          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 830          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 831          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 832          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
 833          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
 834          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
 835          */\r
 836         Tizen::Base::Collection::IList* GetAllTodosN(void) const;\r
 837 \r
 838         /**\r
 839          * Gets all calendars.\r
 840          *\r
 841          * @since       2.0\r
 842          * @privlevel   public\r
 843          * @privilege   %http://tizen.org/privilege/calendar.read\r
 844          *\r
 845          * @return              A list containing all the Calendar instances, @n\r
 846          *                              else an empty list if there are no calendars or @c null if an exception occurs @n\r
 847          *                              The results are listed in the order of their calendar ID.\r
 848          * @exception   E_SUCCESS                               The method is successful.\r
 849          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 850          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 851          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 852          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
 853          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
 854          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
 855          */\r
 856         Tizen::Base::Collection::IList* GetAllCalendarsN(void) const;\r
 857 \r
 858         /**\r
 859          * Gets information of all the changed events since the version.\r
 860          *\r
 861          * @since       2.0\r
 862          * @privlevel   public\r
 863          * @privilege   %http://tizen.org/privilege/calendar.read\r
 864          *\r
 865          * @return              A list containing the CalEventChangeInfo instances, @n\r
 866          *                              else an empty list if there are no events or @c null if an exception occurs @n\r
 867          *                              The results are listed in the order of their version.\r
 868          * @param[in]   version                                 The version\r
 869          * @param[out]  latestVersion                   The latest change version among the changed events\r
 870          * @exception   E_SUCCESS                               The method is successful.\r
 871          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 872          * @exception   E_INVALID_ARG                   The specified @c version is invalid.\r
 873          * @exception   E_SYSTEM                                A system error has occurred.\r
 874          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 875          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
 876          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
 877          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
 878          */\r
 879         Tizen::Base::Collection::IList* GetChangedEventsAfterN(int version, int& latestVersion) const;\r
 880 \r
 881         /**\r
 882          * Gets information of all the changed to-dos since the version.\r
 883          *\r
 884          * @since       2.0\r
 885          * @privlevel   public\r
 886          * @privilege   %http://tizen.org/privilege/calendar.read\r
 887          *\r
 888          * @return              A list containing the CalTodoChangeInfo instances, @n\r
 889          *                              else an empty list if there are no to-dos or @c null if an exception occurs @n\r
 890          *                              The results are listed in the order of their version.\r
 891          * @param[in]   version                                 The version\r
 892          * @param[out]  latestVersion                   The latest change version among the changed to-dos\r
 893          * @exception   E_SUCCESS                               The method is successful.\r
 894          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 895          * @exception   E_INVALID_ARG                   The specified @c version is invalid.\r
 896          * @exception   E_SYSTEM                                A system error has occurred.\r
 897          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 898          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
 899          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
 900          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
 901          */\r
 902         Tizen::Base::Collection::IList* GetChangedTodosAfterN(int version, int& latestVersion) const;\r
 903 \r
 904         /**\r
 905          * Adds a calendar. @n\r
 906          * After adding the calendar to the database successfully, the calendar has a valid calendar ID.\r
 907          *\r
 908          * @since       2.0\r
 909          * @privlevel   public\r
 910          * @privilege   %http://tizen.org/privilege/calendar.write\r
 911          *\r
 912          * @return              An error code\r
 913          * @param[in,out]       calendar                                The calendar to add\r
 914          * @exception   E_SUCCESS                               The method is successful.\r
 915          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 916          * @exception   E_INVALID_ARG                   The record ID of the calendar is not #INVALID_RECORD_ID.\r
 917          * @exception   E_STORAGE_FULL                  The storage is insufficient.\r
 918          * @exception   E_SYSTEM                                A system error has occurred.\r
 919          */\r
 920         result AddCalendar(Calendar& calendar);\r
 921 \r
 922         /**\r
 923          * Adds a calendar that is associated with the specified account. @n\r
 924          * After adding the calendar to the database successfully, the calendar has a valid calendar ID.\r
 925          *\r
 926          * @since       2.0\r
 927          * @privlevel   public\r
 928          * @privilege   %http://tizen.org/privilege/calendar.write\r
 929          *\r
 930          * @return              An error code\r
 931          * @param[in,out]       calendar                        The calendar to add\r
 932          * @param[in]   accountId                               The account Id\r
 933          * @exception   E_SUCCESS                               The method is successful.\r
 934          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 935          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
 936          *                                                                              - The record ID of the calendar is not #INVALID_RECORD_ID. @n\r
 937          *                                                                              - The specified @c accountId is invalid.\r
 938          * @exception   E_OBJ_NOT_FOUND                 The specified account is not found.\r
 939          * @exception   E_STORAGE_FULL                  The storage is insufficient.\r
 940          * @exception   E_SYSTEM                                A system error has occurred.\r
 941          */\r
 942         result AddCalendar(Calendar& calendar, AccountId accountId);\r
 943 \r
 944         /**\r
 945          * Removes the specified calendar.\r
 946          *\r
 947          * @since       2.0\r
 948          * @privlevel   public\r
 949          * @privilege   %http://tizen.org/privilege/calendar.write\r
 950          *\r
 951          * @return              An error code\r
 952          * @param[in]   calendarId                              The calendar ID to remove\r
 953          * @exception   E_SUCCESS                               The method is successful.\r
 954          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 955          * @exception   E_INVALID_ARG                   The specified @c calendarId is invalid, or\r
 956          *                                                                                      the calendar represents default calendar.\r
 957          * @exception   E_OBJ_NOT_FOUND                 The specified calendar is not found.\r
 958          * @exception   E_SYSTEM                                A system error has occurred.\r
 959          */\r
 960         result RemoveCalendar(RecordId calendarId);\r
 961 \r
 962         /**\r
 963          * Updates the specified calendar.\r
 964          *\r
 965          * @since       2.0\r
 966          * @privlevel   public\r
 967          * @privilege   %http://tizen.org/privilege/calendar.write\r
 968          *\r
 969          * @return              An error code\r
 970          * @param[in]   calendar                                The Calendar instance to update\r
 971          * @exception   E_SUCCESS                               The method is successful.\r
 972          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 973          * @exception   E_INVALID_ARG                   The calendar's recordId is #INVALID_RECORD_ID, or\r
 974          *                                                                              the calendar represents default calendar.\r
 975          * @exception   E_OBJ_NOT_FOUND                 The specified calendar is not found.\r
 976          * @exception   E_SYSTEM                                A system error has occurred.\r
 977          */\r
 978         result UpdateCalendar(const Calendar& calendar);\r
 979 \r
 980         /**\r
 981          * Gets the calendar with the specified calendar ID.\r
 982          *\r
 983          * @since       2.0\r
 984          * @privlevel   public\r
 985          * @privilege   %http://tizen.org/privilege/calendar.read\r
 986          *\r
 987          * @return              The matched calendar, @n \r
 988          *              else @c null if an exception occurs\r
 989          * @param[in]   calendarId                              The calendar ID\r
 990          * @exception   E_SUCCESS                               The method is successful.\r
 991          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 992          * @exception   E_INVALID_ARG                                   The specified @c calendarId is invalid.\r
 993          * @exception   E_OBJ_NOT_FOUND                 The specified calendar is not found.\r
 994          * @exception   E_SYSTEM                                A system error has occurred.\r
 995          * @remarks                     The specific error code can be accessed using the GetLastResult() method.\r
 996          */\r
 997         Calendar* GetCalendarN(RecordId calendarId) const;\r
 998 \r
 999         /**\r
1000          * Removes an instance of the recurring event. @n\r
1001          * If the event instance has been removed successfully, its start date is added as an exception date to the recurrence of its original event.\r
1002          *\r
1003          * @since       2.0\r
1004          * @privlevel   public\r
1005          * @privilege   %http://tizen.org/privilege/calendar.write\r
1006          *\r
1007          * @return              An error code\r
1008          * @param[in]   eventInstance                   The event instance to remove @n\r
1009          *                                                                              The @c eventInstance must be an instance of the recurring event.\r
1010          * @exception   E_SUCCESS                               The method is successful.\r
1011          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
1012          * @exception   E_INVALID_ARG                   The instance is invalid.\r
1013          * @exception   E_OBJ_NOT_FOUND                 The original event of the @eventInstance is not found.\r
1014          * @exception   E_SYSTEM                                A system error has occurred.\r
1015          * @remarks             The instance's start time is added to the recurrence of original event as exception date.\r
1016          */\r
1017         result RemoveEventInstance(const CalEventInstance& eventInstance);\r
1018 \r
1019         /**\r
1020          * Update the specified recurring event instance(@ref CalEventInstance). This method can be used for defining exception of the recurring event. @n\r
1021          * In order to update an event instance, you should use copy of its original event(@ref CalEventInstance::GetOriginalEventId()). @n\r
1022          * You can modify the properties of copy of the original event and use it as the second parameter of this method. @n\r
1023          * (The start/end time of the original event should be set with the start/end time of the event instance.) @n\r
1024          * This method adds the modified copy of the original event as a new event. Therefore the new event id will be assigned to it through @c event's record id @n\r
1025          * and its existing event id inside the modified copy of the original event will become the base event id of the new event. @n\r
1026          * However this method only updates the properties of the event, not add a new event, once added.\r
1027          *\r
1028          * @code\r
1029 \r
1030                 void UpdateRecurringEventInstance(const CalEventInstance& eventInstance)\r
1031                 {\r
1032                         CalEvent* pEvent = pCalendarbook->GetEventN(eventInstance.GetOriginalEventId());\r
1033                         if (pEvent == null)\r
1034                         {\r
1035                                 AppLogException("GetEventN() has failed");\r
1036                                 return;\r
1037                         }\r
1038 \r
1039                         // Sets the start time and end time\r
1040                         pEvent->SetStartAndEndTime(eventInstance.GetStartTime(), eventInstance.GetEndTime());\r
1041 \r
1042                         // Modifies the properties\r
1043                         pEvent->SetLocation(L"Meeting room on 11th floor");\r
1044 \r
1045                         // Updates the instance\r
1046                         result r = pCalendarbook->UpdateEventInstance(eventInstance, *pEvent);\r
1047                         if (IsFailed(r))\r
1048                         {\r
1049                                 AppLogException("UpdateEventInstance() has failed");\r
1050                                 delete pEvent;\r
1051                                 return;\r
1052                         }\r
1053 \r
1054                         delete pEvent;\r
1055                 }\r
1056 \r
1057          * @endcode\r
1058          *\r
1059          * @since       2.1\r
1060          * @privlevel   public\r
1061          * @privilege   %http://tizen.org/privilege/calendar.write\r
1062          *\r
1063          * @return              An error code\r
1064          * @param[in]   eventInstance                   The event instance to update @n\r
1065          *                                                                              The @c eventInstance must be an instance of the recurring event.\r
1066          * @param[in,out]       event                           The modified copy of the original event @n\r
1067          * @exception   E_SUCCESS                               The method is successful.\r
1068          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
1069          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
1070          *                                                                              - The instance is invalid. @n\r
1071          *                                                                              - @c event is not referring to the original event.\r
1072          * @exception   E_OBJ_NOT_FOUND                 The original event of the @c eventInstance is not found.\r
1073          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
1074          */\r
1075         result UpdateEventInstance(const CalEventInstance& eventInstance, CalEvent& event);\r
1076 \r
1077         /**\r
1078          * Gets the latest version of calendarbook.\r
1079          *\r
1080          * @since       2.0\r
1081          * @privlevel   public\r
1082          * @privilege   %http://tizen.org/privilege/calendar.read\r
1083          *\r
1084          * @return              The latest version\r
1085          * @exception   E_SUCCESS                               The method is successful.\r
1086          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
1087          * @exception   E_SYSTEM                                A system error has occurred.\r
1088          * @remarks                     The specific error code can be accessed using the GetLastResult() method.\r
1089          */\r
1090         int GetLatestVersion(void) const;\r
1091 \r
1092         /**\r
1093          * Searches items of the calendarbook with the filter. @n\r
1094          * The filter specifies the item type and condition for searching.\r
1095          * The searched results are ordered by the @c propertySortedBy and @c sortOrder.\r
1096          * If the @c offset is M and the @c maxCount are N, then the first M items are omitted from the result set returned by the searching operation and the next N items are returned.\r
1097          *\r
1098          * @since       2.0\r
1099          * @privlevel   public\r
1100          * @privilege   %http://tizen.org/privilege/calendar.read\r
1101          *\r
1102          * @return              A list of searched results (the list of CalEvent, CalTodo, Calendar, or CalEventInstance), @n\r
1103          *                                              else an empty list if there is no searched result or @c null if an exception occurs\r
1104          * @param[in]   filter          The filter that specifies the search condition @n If the filter is empty, all items that are specified by the type of this filter will be searched.\r
1105          * @param[in]   propertySortedBy                The property for sorting @n The searched results are ordered by the values of this property.\r
1106          * @param[in]   sortOrder               The order for sorting\r
1107          * @param[in]   offset                  The offset of the searched results @n If this value is @c 0, it will be ignored.\r
1108          * @param[in]   maxCount                The maximum count of the searched results @n If this value is @c 0, it will be ignored.\r
1109          * @exception   E_SUCCESS                                               The method is successful.\r
1110          * @exception   E_PRIVILEGE_DENIED                              The application does not have the privilege to call this method.\r
1111          * @exception   E_INVALID_ARG                           The specified @c offset or @c maxCount is less than 0, or the @c propertySortedBy is not an element of the enumerator that corresponds with the type of the specified @c filter.\r
1112          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.\r
1113          * @remarks                             The specific error code can be accessed using the GetLastResult() method.\r
1114          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
1115          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
1116          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
1117           * @see EventFilterProperty\r
1118           * @see TodoFilterProperty\r
1119           * @see CalendarFilterProperty\r
1120           * @see EventInstanceFilterProperty\r
1121          */\r
1122         Tizen::Base::Collection::IList* SearchN(const CalendarbookFilter& filter, unsigned long propertySortedBy = 0, Tizen::Base::SortOrder sortOrder = Tizen::Base::SORT_ORDER_NONE,\r
1123                         int offset = 0, int maxCount = 0) const;\r
1124 \r
1125         /**\r
1126          * Gets the matched item count of the search results with the filter. @n\r
1127          * The filter specifies the item type and condition for searching.\r
1128          *\r
1129          * @since       2.0\r
1130          * @privlevel   public\r
1131          * @privilege   %http://tizen.org/privilege/calendar.read\r
1132          *\r
1133          * @return              The count of the searched results\r
1134          * @param[in]   filter  The filter that specifies the search condition @n If the filter is empty, all items that are specified by the type of this filter will be searched.\r
1135          * @exception   E_SUCCESS                                               The method is successful.\r
1136          * @exception   E_PRIVILEGE_DENIED                              The application does not have the privilege to call this method.\r
1137          * @exception   E_SYSTEM                                                The method cannot proceed due to a severe system error.\r
1138          * @remarks                     The specific error code can be accessed using the GetLastResult() method.\r
1139          */\r
1140         int GetMatchedItemCount(const CalendarbookFilter& filter) const;\r
1141 \r
1142         /**\r
1143          * Parses the events from specific vCalendar file. @n\r
1144          * This method supports to parse for vCalendar version 1.0 and 2.0 (iCalendar).\r
1145          *\r
1146          * @since       2.0\r
1147          *\r
1148          * @return              A list containing the CalEvent instances, @n\r
1149          *                              else an empty list if there are no events or @c null if an exception occurs\r
1150          * @param[in]   vCalFilePath                    The path of the vCalendar file\r
1151          * @exception   E_SUCCESS                               The method is successful.\r
1152          * @exception   E_INVALID_ARG                   The specified @c vCalFilePath is invalid.\r
1153          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.\r
1154          * @exception   E_FILE_NOT_FOUND                The specified vCalendar file is not found.\r
1155          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
1156          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
1157          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
1158          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
1159          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
1160          */\r
1161         static Tizen::Base::Collection::IList* ParseEventsFromVcalendarN(const Tizen::Base::String& vCalFilePath);\r
1162 \r
1163         /**\r
1164          * Parses the to-dos from specific vCalendar file. @n\r
1165          * This method supports to parse for vCalendar version 1.0 and 2.0 (iCalendar).\r
1166          *\r
1167          * @since       2.0\r
1168          *\r
1169          * @return              A list containing the CalTodo instances, @n\r
1170          *                              else an empty list if there are no to-dos or @c null if an exception occurs\r
1171          * @param[in]   vCalFilePath                    The path of the vCalendar file\r
1172          * @exception   E_SUCCESS                               The method is successful.\r
1173          * @exception   E_INVALID_ARG                   The specified @c vCalFilePath is invalid.\r
1174          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.\r
1175          * @exception   E_FILE_NOT_FOUND                The specified vCalendar file is not found.\r
1176          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
1177          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
1178          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
1179          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
1180          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
1181          */\r
1182         static Tizen::Base::Collection::IList* ParseTodosFromVcalendarN(const Tizen::Base::String& vCalFilePath);\r
1183 \r
1184         /**\r
1185          * Exports the events to vCalendar 2.0 (iCalendar) file.\r
1186          *\r
1187          * @since       2.0\r
1188          *\r
1189          * @return              An error code\r
1190          * @param[in]   eventList                               The event list to export @n The list should contain CalEvent instances.\r
1191          * @param[in]   vCalFilePath                    The vCalendar file path\r
1192          * @exception   E_SUCCESS                               The method is successful.\r
1193          * @exception   E_INVALID_ARG                   The specified @c eventList is invalid or\r
1194          *                                                                              the specified @c vCalFilePath is invalid.\r
1195          * @exception   E_ILLEGAL_ACCESS                Access of vCalFilePath is denied due to insufficient permission.\r
1196          * @exception   E_FILE_ALREADY_EXIST    The vCalendar file already exists.\r
1197          * @exception   E_STORAGE_FULL                  The disk space is full.\r
1198          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
1199          */\r
1200         static result ExportEventsToVcalendar(const Tizen::Base::Collection::IList& eventList, const Tizen::Base::String& vCalFilePath);\r
1201 \r
1202         /**\r
1203          * Exports the to-dos to vCalendar 2.0 (iCalendar) file.\r
1204          *\r
1205          * @since       2.0\r
1206          *\r
1207          * @return              An error code\r
1208          * @param[in]   todoList                                The to-do list to export @n The list should contain CalTodo instances.\r
1209          * @param[in]   vCalFilePath                    The vCalendar file path\r
1210          * @exception   E_SUCCESS                               The method is successful.\r
1211          * @exception   E_INVALID_ARG                   The specified @c todoList is invalid or\r
1212          *                                                                              the specified @c vCalFilePath is invalid.\r
1213          * @exception   E_ILLEGAL_ACCESS                Access of vCalFilePath is denied due to insufficient permission.\r
1214          * @exception   E_FILE_ALREADY_EXIST    The vCalendar file already exists.\r
1215          * @exception   E_STORAGE_FULL                  The disk space is full.\r
1216          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
1217          */\r
1218         static result ExportTodosToVcalendar(const Tizen::Base::Collection::IList& todoList, const Tizen::Base::String& vCalFilePath);\r
1219 \r
1220         /**\r
1221          * Gets the maximum allowable date and time in the calendarbook (that is, "December 31 2100 23:59:59").\r
1222          *\r
1223          * @since       2.0\r
1224          *\r
1225          * @return              An instance of Tizen::Base::DateTime\r
1226          */\r
1227         static Tizen::Base::DateTime GetMaxDateTime(void);\r
1228 \r
1229         /**\r
1230          * Gets the minimum allowable date and time in the calendarbook (that is, "January 1 1900 00:00:00").\r
1231          *\r
1232          * @since       2.0\r
1233          *\r
1234          * @return              An instance of Tizen::Base::DateTime\r
1235          */\r
1236         static Tizen::Base::DateTime GetMinDateTime(void);\r
1237 \r
1238 private:\r
1239         /**\r
1240          * The implementation of this copy constructor is intentionally blank and declared as private @n\r
1241          * to prohibit copying of objects.\r
1242          *\r
1243          * @since       2.0\r
1244          */\r
1245         Calendarbook(const Calendarbook& rhs);\r
1246 \r
1247         /**\r
1248          * The implementation of this copy assignment operator is intentionally blank and declared as private @n\r
1249          * to prohibit copying of objects.\r
1250          *\r
1251          * @since       2.0\r
1252          */\r
1253         Calendarbook& operator =(const Calendarbook& rhs);\r
1254 \r
1255 private:\r
1256         friend class _CalendarbookImpl;\r
1257         class _CalendarbookImpl* __pCalendarbookImpl;\r
1258 };      // Calendarbook\r
1259 \r
1260 }}      // Tizen::Social\r
1261 \r
1262 \r
1263 #endif // _FSCL_CALENDARBOOK_H_\r