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. @n\r
 318          * For full construction, 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                                The method cannot proceed due to a severe system error.\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                                The method cannot proceed due to a severe system error.\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                                The method cannot proceed due to a severe system error.\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_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 384          * @exception   E_INVALID_ARG                   The specified @c event is invalid.\r
 385          * @exception   E_STORAGE_FULL                  The storage is insufficient.\r
 386          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 387          */\r
 388         result AddEvent(CalEvent& event);\r
 389 \r
 390         /**\r
 391          * Adds an event of the specific calendar to the calendar book. @n\r
 392          * After adding the event successfully, the event has a valid record ID.\r
 393          *\r
 394          * @since       2.0\r
 395          * @privlevel   public\r
 396          * @privilege   %http://tizen.org/privilege/calendar.write\r
 397          *\r
 398          * @return              An error code\r
 399          * @param[in,out]       event                                   The event to add\r
 400          * @param[in]   calendarId                              The calendar ID\r
 401          * @exception   E_SUCCESS                               The method is successful.\r
 402          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 403          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 404          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
 405          *                                                                              - The specified @c event is invalid. @n\r
 406          *                                                                              - The specified @c calendarId is invalid. @n\r
 407          *                                                                              - The specified calendar is created for CALENDAR_ITEM_TYPE_TODO.\r
 408          * @exception   E_OBJ_NOT_FOUND                 The specified calendar is not found.\r
 409          * @exception   E_STORAGE_FULL                  The storage is insufficient.\r
 410          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 411          */\r
 412         result AddEvent(CalEvent& event, RecordId calendarId);\r
 413 \r
 414         /**\r
 415          * Adds a to-do of the default calendar to the calendar book. @n\r
 416          * After adding the to-do item successfully, the item has a valid record ID.\r
 417          *\r
 418          * @since       2.0\r
 419          * @privlevel   public\r
 420          * @privilege   %http://tizen.org/privilege/calendar.write\r
 421          *\r
 422          * @return              An error code\r
 423          * @param[in,out]       todo                                    The to-do to add\r
 424          * @exception   E_SUCCESS                               The method is successful.\r
 425          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 426          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 427          * @exception   E_INVALID_ARG                   The specified @c todo is invalid.\r
 428          * @exception   E_STORAGE_FULL                  The storage is insufficient.\r
 429          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 430          */\r
 431         result AddTodo(CalTodo& todo);\r
 432 \r
 433         /**\r
 434          * Adds a to-do of the specific calendar to the calendar book. @n\r
 435          * After adding the to-do item successfully, the item has a valid record ID.\r
 436          *\r
 437          * @since       2.0\r
 438          * @privlevel   public\r
 439          * @privilege   %http://tizen.org/privilege/calendar.write\r
 440          *\r
 441          * @return              An error code\r
 442          * @param[in,out]       todo                                    The to-do to add\r
 443          * @param[in]   calendarId                              The calendar ID\r
 444          * @exception   E_SUCCESS                               The method is successful.\r
 445          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 446          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 447          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
 448          *                                                                              - The specified @c todo is invalid. @n\r
 449          *                                                                              - The specified @c calendarId is invalid. @n\r
 450          *                                                                              - The specified calendar is created for CALENDAR_ITEM_TYPE_EVENT.\r
 451          * @exception   E_OBJ_NOT_FOUND                 The specified calendar is not found.\r
 452          * @exception   E_STORAGE_FULL                  The storage is insufficient.\r
 453          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 454          */\r
 455         result AddTodo(CalTodo& todo, RecordId calendarId);\r
 456 \r
 457         /**\r
 458          * Removes the specified calendar event from this calendar book. @n\r
 459          * After removing the event successfully, the event has #INVALID_RECORD_ID.\r
 460          *\r
 461          * @since       2.0\r
 462          * @privlevel   public\r
 463          * @privilege   %http://tizen.org/privilege/calendar.write\r
 464          *\r
 465          * @return              An error code\r
 466          * @param[in]   event                           The calendar event to remove\r
 467          * @exception   E_SUCCESS                               The method is successful.\r
 468          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 469          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 470          * @exception   E_INVALID_ARG                   The specified @c recordId is #INVALID_RECORD_ID.\r
 471          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 472          * @exception   E_INVALID_OPERATION             This method cannot be used for the recurrence exception of the recurring event. @n\r
 473          *                                                                              RemoveEventInstance() should be used instead of this method. @b Since: @b 2.1\r
 474          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 475          */\r
 476         result RemoveEvent(CalEvent& event);\r
 477 \r
 478         /**\r
 479          * Removes the specified calendar event from this calendar book.\r
 480          *\r
 481          * @since       2.0\r
 482          * @privlevel   public\r
 483          * @privilege   %http://tizen.org/privilege/calendar.write\r
 484          *\r
 485          * @return              An error code\r
 486          * @param[in]   eventId                                 The calendar event ID to remove\r
 487          * @exception   E_SUCCESS                               The method is successful.\r
 488          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 489          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 490          * @exception   E_INVALID_ARG                   The specified @c eventId is #INVALID_RECORD_ID.\r
 491          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 492          * @exception   E_INVALID_OPERATION             This method cannot be used for the recurrence exception of the recurring event. @n\r
 493          *                                                                              RemoveEventInstance() should be used instead of this method. @b Since: @b 2.1\r
 494          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 495          */\r
 496         result RemoveEvent(RecordId eventId);\r
 497 \r
 498         /**\r
 499          * Removes the specified CalTodo instance from the calendar book. @n\r
 500          * After removing the to-do item successfully, the item has #INVALID_RECORD_ID.\r
 501          *\r
 502          * @since       2.0\r
 503          * @privlevel   public\r
 504          * @privilege   %http://tizen.org/privilege/calendar.write\r
 505          *\r
 506          * @return              An error code\r
 507          * @param[in]   todo                                    The CalTodo ID to remove\r
 508          * @exception   E_SUCCESS                               The method is successful.\r
 509          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 510          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 511          * @exception   E_INVALID_ARG                   The specified @c recordId is #INVALID_RECORD_ID.\r
 512          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 513          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 514          */\r
 515         result RemoveTodo(CalTodo& todo);\r
 516 \r
 517         /**\r
 518          * Removes the specified CalTodo instance from the calendar book.\r
 519          *\r
 520          * @since       2.0\r
 521          * @privlevel   public\r
 522          * @privilege   %http://tizen.org/privilege/calendar.write\r
 523          *\r
 524          * @return              An error code\r
 525          * @param[in]   todoId                                  The CalTodo ID to remove\r
 526          * @exception   E_SUCCESS                               The method is successful.\r
 527          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 528          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 529          * @exception   E_INVALID_ARG                   The specified input parameter is invalid.\r
 530          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 531          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 532          */\r
 533         result RemoveTodo(RecordId todoId);\r
 534 \r
 535         /**\r
 536          * Updates the specified calendar event to the internal data storage.\r
 537          *\r
 538          * @since       2.0\r
 539          * @privlevel   public\r
 540          * @privilege   %http://tizen.org/privilege/calendar.write\r
 541          *\r
 542          * @return              An error code\r
 543          * @param[in]   event                           The CalEvent instance to update\r
 544          * @exception   E_SUCCESS                               The method is successful.\r
 545          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 546          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 547          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
 548          *                                                                              - The specified @c recordId is #INVALID_RECORD_ID. @n\r
 549          *                                                                              - The specified @c event is not #RECORD_TYPE_EVENT. @n\r
 550          *                                                                              - The specified @c event is not an entry type instance. @n\r
 551          *                                                                              - The date of the event is invalid. @n\r
 552          *                                                                              The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().\r
 553          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 554          * @exception   E_INVALID_OPERATION             This method cannot be used for the recurrence exception of the recurring event. @n\r
 555          *                                                                              UpdateEventInstance() should be used instead of this method. @b Since: @b 2.1\r
 556          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 557          */\r
 558         result UpdateEvent(const CalEvent& event);\r
 559 \r
 560         /**\r
 561          * Updates the specified CalTodo instance on the internal data storage.\r
 562          *\r
 563          * @since       2.0\r
 564          * @privlevel   public\r
 565          * @privilege   %http://tizen.org/privilege/calendar.write\r
 566          *\r
 567          * @return              An error code\r
 568          * @param[in]   todo                                    The CalTodo instance to update\r
 569          * @exception   E_SUCCESS                               The method is successful.\r
 570          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 571          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 572          * @exception   E_INVALID_ARG                   The specified @c recordId is #INVALID_RECORD_ID, or the date of the to-do item is invalid. @n\r
 573          *                                                                              The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().\r
 574          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 575          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 576          */\r
 577         result UpdateTodo(const CalTodo& todo);\r
 578 \r
 579         /**\r
 580          * Gets the specified event ID that is matched with the RecordId.\r
 581          *\r
 582          * @since       2.0\r
 583          * @privlevel   public\r
 584          * @privilege   %http://tizen.org/privilege/calendar.read\r
 585          *\r
 586          * @return              The matched event\r
 587          * @param[in]   eventId                                 The event ID to find\r
 588          * @exception   E_SUCCESS                               The method is successful.\r
 589          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 590          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 591          * @exception   E_INVALID_ARG                   The specified @c eventId is invalid.\r
 592          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 593          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 594          * @remarks                     The specific error code can be accessed using the GetLastResult() method.\r
 595          */\r
 596         CalEvent* GetEventN(RecordId eventId) const;\r
 597 \r
 598         /**\r
 599          * Gets the specified to-do after matching it with the specified record ID.\r
 600          *\r
 601          * @since       2.0\r
 602          * @privlevel   public\r
 603          * @privilege   %http://tizen.org/privilege/calendar.read\r
 604          *\r
 605          * @return              The matched to-do\r
 606          * @param[in]   todoId                                  The ID of the to-do to find\r
 607          * @exception   E_SUCCESS                               The method is successful.\r
 608          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 609          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 610          * @exception   E_INVALID_ARG                   The specified @c todoId is invalid.\r
 611          * @exception   E_OBJ_NOT_FOUND                 The specified record is not found.\r
 612          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 613          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 614          *\r
 615          */\r
 616         CalTodo* GetTodoN(RecordId todoId) const;\r
 617 \r
 618         /**\r
 619          * Gets all the to-do items in the specified time range. @n\r
 620          * To-do items, whose due date is within the retrieving range, is retrieved.\r
 621          *\r
 622          * @if OSPCOMPAT\r
 623          * @brief <i> [Compatibility] </i>\r
 624          * @endif\r
 625          * @since       2.0\r
 626          * @if OSPCOMPAT\r
 627          * @compatibility This method has compatibility issues with OSP compatible applications. @n\r
 628          *                For more information, see @ref CompCalendarbookGetTodosNPage "here".\r
 629          * @endif\r
 630          * @privlevel   public\r
 631          * @privilege   %http://tizen.org/privilege/calendar.read\r
 632          *\r
 633          * @return              A list of all the matched CalTodo instances, @n\r
 634          *                              else an empty list if there is no matched to-do item @n\r
 635          *                              The items are sorted by due date.\r
 636          * @param[in]   start                                   The start of the time range. @n Any value with a unit that is less than a second is ignored.\r
 637          * @param[in]   end                                             The end of the time range. @n Any value with a unit that is less than a second is ignored.\r
 638          * @param[in]   pageNo                                  The page number of the result list @n\r
 639          *                                                                              It starts from @c 1.\r
 640          * @param[in]   countPerPage                    The desired maximum count of the result items per page\r
 641          * @param[in]   status                                  The to-do status @n\r
 642          *                                                                              If a specific status is set, the to-dos that have the specified status are returned. @n\r
 643          *                                                                              The default status value is #TODO_STATUS_ALL, which means all the statuses are returned.\r
 644          * @param[in]   priority                                The to-do priority @n\r
 645          *                                                                              If a specific priority is set, the to-dos that have the specified priority are returned. @n\r
 646          *                                                                              The default priority value is #TODO_PRIORITY_ALL that means all the priorities are returned.\r
 647          * @exception   E_SUCCESS                               The method is successful.\r
 648          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 649          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 650          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
 651          *                                                                              - The specified @c pageNo or @c countPerPage is less than @c 1. @n\r
 652          *                                                                              - The start time is later than the end date. @n\r
 653          *                                                                              - The start or end time is out of the valid range. @n\r
 654          *                                                                               The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().\r
 655          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 656          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 657          */\r
 658         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
 659                                                         unsigned long priority = TODO_PRIORITY_ALL) const;\r
 660 \r
 661         /**\r
 662          * @if OSPCOMPAT\r
 663          * @page        CompCalendarbookGetTodosNPage Compatibility for GetTodosN()\r
 664          * @section     CompCalendarbookGetTodosNPageIssueSection Issues\r
 665          *           Implementing this method in OSP compatible applications has the following issues: @n\r
 666          *                      -# If the start date of a to-do is not in the time range of start/end parameters, @n\r
 667          *                      the to-do is not retrieved even though the due date is in the time range.\r
 668          *\r
 669          * @section     CompCalendarbookGetTodosNPageSolutionSection Resolutions\r
 670          *                      This issue has been resolved in Tizen. @n\r
 671          *                      -# The to-do will be retrieved if the due date is in the range of start/end parameters.\r
 672          * @endif\r
 673          */\r
 674 \r
 675         /**\r
 676          * Gets the total number of to-do items in the specified time range. @n\r
 677          * To-do items, whose due date is within the retrieving range, is counted.\r
 678          *\r
 679          * @if OSPCOMPAT\r
 680          * @brief <i> [Compatibility] </i>\r
 681          * @endif\r
 682          * @since       2.0\r
 683          * @if OSPCOMPAT\r
 684          * @compatibility This method has compatibility issues with OSP compatible applications. @n\r
 685          *                For more information, see @ref CompCalendarbookGetTodoCountPage "here".\r
 686          * @endif\r
 687          * @privlevel   public\r
 688          * @privilege   %http://tizen.org/privilege/calendar.read\r
 689          *\r
 690          * @return              The total number of to-dos, @n\r
 691          *                                                                              else @c -1 if an exception occurs\r
 692          * @param[in]   start                                   The start of the time range. @n Any value with a unit that is less than a second is ignored.\r
 693          * @param[in]   end                                             The end of the time range. @n Any value with a unit that is less than a second is ignored.\r
 694          * @param[in]   status                                  The to-do status @n\r
 695          *                                                                              If a specific status is set, the to-dos that have the specified status are returned. @n\r
 696          *                                                                              The default status value is #TODO_STATUS_ALL, which means all the statuses are returned.\r
 697          * @param[in]   priority                                The to-do priority @n\r
 698          *                                                                              If a specific priority is set, the to-dos that have the specified priority are returned. @n\r
 699          *                                                                              The default priority value is #TODO_PRIORITY_ALL that means all the priorities are returned.\r
 700          * @exception   E_SUCCESS                               The method is successful.\r
 701          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 702          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 703          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
 704          *                                                                              - The start time is later than the end date. @n\r
 705          *                                                                              - The start or end time is out of the valid range. @n\r
 706          *                                                                              The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().\r
 707          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 708          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 709          */\r
 710         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
 711 \r
 712         /**\r
 713          * @if OSPCOMPAT\r
 714          * @page        CompCalendarbookGetTodoCountPage Compatibility for GetTodoCount()\r
 715          * @section     CompCalendarbookGetTodoCountPageIssueSection Issues\r
 716          *           Implementing this method in OSP compatible applications has the following issues: @n\r
 717          *                      -# If the start date of a to-do is not in the time range of start/end parameters, @n\r
 718          *                      the to-do is not counted even though the due date is in the time range.\r
 719          *\r
 720          * @section     CompCalendarbookGetTodoCountPageSolutionSection Resolutions\r
 721          *                      This issue has been resolved in Tizen. @n\r
 722          *                      -# The to-do will be counted if the due date is in the range of start/end parameters.\r
 723          * @endif\r
 724          */\r
 725 \r
 726         /**\r
 727          * @if OSPDEPREC\r
 728          * Gets the CalEvent instances that are within the specified time range. @n\r
 729          * 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
 730          * start and end times in Coordinated Universal Time (UTC).\r
 731          *\r
 732          * @brief <i> [Deprecated] </i>\r
 733          * @deprecated  This method is deprecated. Instead of using this method, it is recommended to use GetInstancesOfAllDayEventsN() or GetInstancesOfNonAllDayEventsN().\r
 734          * @since       2.0\r
 735          * @privlevel   public\r
 736          * @privilege   %http://tizen.org/privilege/calendar.read\r
 737          *\r
 738          * @return              A list containing all of the matched CalEvent instances, @n\r
 739          *                              else an empty list if there are no matched instances, or @c null if an exception occurs @n\r
 740          *                              The results are listed in the following order: all day events, and other events. @n\r
 741          *                              The results with the same property of all day event are ordered by their start time.\r
 742          * @param[in]   start                           The start of the time range. @n Any value with a unit that is less than a second is ignored.\r
 743          * @param[in]   end                                     The end of the time range. @n Any value with a unit that is less than a second is ignored.\r
 744          * @param[in]   timeZone                        The time zone of the specified start and end times\r
 745          * @param[in]   pageNo                          The page number of the result list @n\r
 746          *                                                                      It starts from @c 1.\r
 747          * @param[in]   countPerPage            The desired maximum count of the result items per page\r
 748          * @param[in]   category                        The event category @n\r
 749          *                                                                      If a specific category is set, the events that have the specified category are returned. @n\r
 750          *                                                                      The default category value is #EVENT_CATEGORY_ALL, which means all the categories are returned.\r
 751          * @exception   E_SUCCESS                       The method is successful.\r
 752          * @exception   E_PRIVILEGE_DENIED      The application does not have the privilege to call this method.\r
 753          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 754          * @exception   E_INVALID_ARG           Either of the following conditions has occurred: @n\r
 755          *                                                                      - The specified @c pageNo or @c countPerPage is less than @c 1. @n\r
 756          *                                                                      - The specified @c category is invalid. @n\r
 757          *                                                                      - The start time is later than the end date. @n\r
 758          *                                                                      - The start or end time is out of the valid range. @n\r
 759          *                                                                      The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().\r
 760          * @exception   E_SYSTEM                        The method cannot proceed due to a severe system error.\r
 761          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 762          * @endif\r
 763          */\r
 764         Tizen::Base::Collection::IList* GetEventInstancesN(const Tizen::Base::DateTime& start, const Tizen::Base::DateTime& end,\r
 765                                                                          const Tizen::Locales::TimeZone& timeZone, int pageNo, int countPerPage,\r
 766                                                                          unsigned long category = EVENT_CATEGORY_ALL) const;\r
 767 \r
 768         /**\r
 769          * @if OSPDEPREC\r
 770          * Gets the CalEvent instances that are within the specified time range. @n\r
 771          * 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
 772          * start and end times in Coordinated Universal Time (UTC).\r
 773          *\r
 774          * Although GetEventInstancesN() retrieves the data synchronously, this method returns data asynchronously using\r
 775          * RecordListener::OnEventInstancesReceivedN(). @n\r
 776          * It is highly recommended to use the asynchronous method because getting the event instances may take a long time.\r
 777          *\r
 778          * @brief <i> [Deprecated] </i>\r
 779          * @deprecated  This method is deprecated. Instead of using this method, it is recommended to use GetInstancesOfAllDayEventsN() or GetInstancesOfNonAllDayEventsN().\r
 780          * @since       2.0\r
 781          * @privlevel   public\r
 782          * @privilege   %http://tizen.org/privilege/calendar.read\r
 783          *\r
 784          * @return              An error code\r
 785          * @param[in]   start                                   The start of the time range. @n Any value with a unit that is less than a second is ignored.\r
 786          * @param[in]   end                                     The end of the time range. @n Any value with a unit that is less than a second is ignored.\r
 787          * @param[in]   timeZone                                The time zone of the specified start and end times\r
 788          * @param[in]   pageNo                                  The page number of the result list @n\r
 789          *                                                                      It starts from @c 1.\r
 790          * @param[in]   countPerPage                    The desired maximum count of the result items per page\r
 791          * @param[in]   category                                The event category @n\r
 792          *                                                                      If a specific category is set, the events that have the specified @c category are returned. @n\r
 793          *                                                                      The default category value is #EVENT_CATEGORY_ALL, which means all the categories are returned.\r
 794          * @param[out]  reqId                           The ID of the request\r
 795          * @param[in]   listener                                The listener for receiving the responses of the request\r
 796          * @exception   E_SUCCESS                               The method is successful.\r
 797          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 798          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 799          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
 800          *                                                                      - The specified @c pageNo or @c countPerPage is less than @c 1. @n\r
 801          *                                                                      - The specified @c category is invalid. @n\r
 802          *                                                                      - The start time is later than the end date. @n\r
 803          *                                                                      - The start or end time is out of the valid range. @n\r
 804          *                                                                      The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().\r
 805          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 806          * @remarks             IRecordListener::OnRecordsReceivedN(), Calendarbook::GetEventInstancesN()\r
 807          * @endif\r
 808          */\r
 809         result GetEventInstances(const Tizen::Base::DateTime& start, const Tizen::Base::DateTime& end,\r
 810                                                                         const Tizen::Locales::TimeZone& timeZone, int pageNo, int countPerPage, unsigned long category,\r
 811                                                                         RequestId& reqId,\r
 812                                                                         const IRecordListener& listener) const;\r
 813 \r
 814         /**\r
 815          * Gets all events.\r
 816          *\r
 817          * @since       2.0\r
 818          * @privlevel   public\r
 819          * @privilege   %http://tizen.org/privilege/calendar.read\r
 820          *\r
 821          * @return              A list containing all the CalEvent instances, @n\r
 822          *                              else an empty list if there are no events, or @c null if an exception occurs @n\r
 823          *                              The results are listed in the order of their event ID.\r
 824          * @exception   E_SUCCESS                               The method is successful.\r
 825          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 826          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 827          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 828          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 829          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
 830          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
 831          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
 832          */\r
 833         Tizen::Base::Collection::IList* GetAllEventsN(void) const;\r
 834 \r
 835         /**\r
 836          * Gets all to-dos.\r
 837          *\r
 838          * @since       2.0\r
 839          * @privlevel   public\r
 840          * @privilege   %http://tizen.org/privilege/calendar.read\r
 841          *\r
 842          * @return              A list containing all the CalTodo instances, @n\r
 843          *                              else an empty list if there are no to-dos, or @c null if an exception occurs @n\r
 844          *                              The results are listed in the order of their to-do ID.\r
 845          * @exception   E_SUCCESS                               The method is successful.\r
 846          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 847          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 848          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 849          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 850          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
 851          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
 852          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
 853          */\r
 854         Tizen::Base::Collection::IList* GetAllTodosN(void) const;\r
 855 \r
 856         /**\r
 857          * Gets all calendars.\r
 858          *\r
 859          * @since       2.0\r
 860          * @privlevel   public\r
 861          * @privilege   %http://tizen.org/privilege/calendar.read\r
 862          *\r
 863          * @return              A list containing all the Calendar instances, @n\r
 864          *                              else an empty list if there are no calendars, or @c null if an exception occurs @n\r
 865          *                              The results are listed in the order of their calendar ID.\r
 866          * @exception   E_SUCCESS                               The method is successful.\r
 867          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 868          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 869          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 870          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 871          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
 872          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
 873          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
 874          */\r
 875         Tizen::Base::Collection::IList* GetAllCalendarsN(void) const;\r
 876 \r
 877         /**\r
 878          * Gets information of all the changed events since the version.\r
 879          *\r
 880          * @since       2.0\r
 881          * @privlevel   public\r
 882          * @privilege   %http://tizen.org/privilege/calendar.read\r
 883          *\r
 884          * @return              A list containing the CalEventChangeInfo instances, @n\r
 885          *                              else an empty list if there are no events, or @c null if an exception occurs @n\r
 886          *                              The results are listed in the order of their version.\r
 887          * @param[in]   version                                 The version\r
 888          * @param[out]  latestVersion                   The latest change version among the changed events\r
 889          * @exception   E_SUCCESS                               The method is successful.\r
 890          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 891          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 892          * @exception   E_INVALID_ARG                   The specified @c version is invalid.\r
 893          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 894          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 895          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
 896          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
 897          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
 898          */\r
 899         Tizen::Base::Collection::IList* GetChangedEventsAfterN(int version, int& latestVersion) const;\r
 900 \r
 901         /**\r
 902          * Gets information of all the changed to-dos since the version.\r
 903          *\r
 904          * @since       2.0\r
 905          * @privlevel   public\r
 906          * @privilege   %http://tizen.org/privilege/calendar.read\r
 907          *\r
 908          * @return              A list containing the CalTodoChangeInfo instances, @n\r
 909          *                              else an empty list if there are no to-dos, or @c null if an exception occurs @n\r
 910          *                              The results are listed in the order of their version.\r
 911          * @param[in]   version                                 The version\r
 912          * @param[out]  latestVersion                   The latest change version among the changed to-dos\r
 913          * @exception   E_SUCCESS                               The method is successful.\r
 914          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 915          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 916          * @exception   E_INVALID_ARG                   The specified @c version is invalid.\r
 917          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 918          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
 919          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
 920          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
 921          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
 922          */\r
 923         Tizen::Base::Collection::IList* GetChangedTodosAfterN(int version, int& latestVersion) const;\r
 924 \r
 925         /**\r
 926          * Adds a calendar. @n\r
 927          * After adding the calendar to the database successfully, the calendar has a valid calendar ID.\r
 928          *\r
 929          * @since       2.0\r
 930          * @privlevel   public\r
 931          * @privilege   %http://tizen.org/privilege/calendar.write\r
 932          *\r
 933          * @return              An error code\r
 934          * @param[in,out]       calendar                                The calendar to add\r
 935          * @exception   E_SUCCESS                               The method is successful.\r
 936          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 937          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 938          * @exception   E_INVALID_ARG                   The record ID of the calendar is not #INVALID_RECORD_ID.\r
 939          * @exception   E_STORAGE_FULL                  The storage is insufficient.\r
 940          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 941          */\r
 942         result AddCalendar(Calendar& calendar);\r
 943 \r
 944         /**\r
 945          * Adds a calendar that is associated with the specified account. @n\r
 946          * After adding the calendar to the database successfully, the calendar has a valid calendar ID.\r
 947          *\r
 948          * @since       2.0\r
 949          * @privlevel   public\r
 950          * @privilege   %http://tizen.org/privilege/calendar.write\r
 951          *\r
 952          * @return              An error code\r
 953          * @param[in,out]       calendar                        The calendar to add\r
 954          * @param[in]   accountId                               The account Id\r
 955          * @exception   E_SUCCESS                               The method is successful.\r
 956          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 957          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 958          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
 959          *                                                                              - The record ID of the calendar is not #INVALID_RECORD_ID. @n\r
 960          *                                                                              - The specified @c accountId is invalid.\r
 961          * @exception   E_OBJ_NOT_FOUND                 The specified account is not found.\r
 962          * @exception   E_STORAGE_FULL                  The storage is insufficient.\r
 963          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 964          */\r
 965         result AddCalendar(Calendar& calendar, AccountId accountId);\r
 966 \r
 967         /**\r
 968          * Removes the specified calendar.\r
 969          *\r
 970          * @since       2.0\r
 971          * @privlevel   public\r
 972          * @privilege   %http://tizen.org/privilege/calendar.write\r
 973          *\r
 974          * @return              An error code\r
 975          * @param[in]   calendarId                              The calendar ID to remove\r
 976          * @exception   E_SUCCESS                               The method is successful.\r
 977          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 978          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 979          * @exception   E_INVALID_ARG                   The specified @c calendarId is invalid, or\r
 980          *                                                                                      the calendar represents default calendar.\r
 981          * @exception   E_OBJ_NOT_FOUND                 The specified calendar is not found.\r
 982          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
 983          */\r
 984         result RemoveCalendar(RecordId calendarId);\r
 985 \r
 986         /**\r
 987          * Updates the specified calendar.\r
 988          *\r
 989          * @since       2.0\r
 990          * @privlevel   public\r
 991          * @privilege   %http://tizen.org/privilege/calendar.write\r
 992          *\r
 993          * @return              An error code\r
 994          * @param[in]   calendar                                The Calendar instance to update\r
 995          * @exception   E_SUCCESS                               The method is successful.\r
 996          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
 997          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
 998          * @exception   E_INVALID_ARG                   The calendar's recordId is #INVALID_RECORD_ID, or\r
 999          *                                                                              the calendar represents default calendar.\r
1000          * @exception   E_OBJ_NOT_FOUND                 The specified calendar is not found.\r
1001          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
1002          */\r
1003         result UpdateCalendar(const Calendar& calendar);\r
1004 \r
1005         /**\r
1006          * Gets the calendar with the specified calendar ID.\r
1007          *\r
1008          * @since       2.0\r
1009          * @privlevel   public\r
1010          * @privilege   %http://tizen.org/privilege/calendar.read\r
1011          *\r
1012          * @return              The matched calendar, @n \r
1013          *              else @c null if an exception occurs\r
1014          * @param[in]   calendarId                              The calendar ID\r
1015          * @exception   E_SUCCESS                               The method is successful.\r
1016          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
1017          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
1018          * @exception   E_INVALID_ARG                                   The specified @c calendarId is invalid.\r
1019          * @exception   E_OBJ_NOT_FOUND                 The specified calendar is not found.\r
1020          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
1021          * @remarks                     The specific error code can be accessed using the GetLastResult() method.\r
1022          */\r
1023         Calendar* GetCalendarN(RecordId calendarId) const;\r
1024 \r
1025         /**\r
1026          * Removes an instance of the recurring event. @n\r
1027          * 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
1028          *\r
1029          * @since       2.0\r
1030          * @privlevel   public\r
1031          * @privilege   %http://tizen.org/privilege/calendar.write\r
1032          *\r
1033          * @return              An error code\r
1034          * @param[in]   eventInstance                   The event instance to remove @n\r
1035          *                                                                              The @c eventInstance must be an instance of the recurring event.\r
1036          * @exception   E_SUCCESS                               The method is successful.\r
1037          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
1038          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
1039          * @exception   E_INVALID_ARG                   The instance is invalid.\r
1040          * @exception   E_OBJ_NOT_FOUND                 The original event of the @c eventInstance is not found.\r
1041          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
1042          * @remarks             The instance's start time is added to the recurrence of original event as exception date.\r
1043          */\r
1044         result RemoveEventInstance(const CalEventInstance& eventInstance);\r
1045 \r
1046         /**\r
1047          * Update the specified recurring event instance(@ref CalEventInstance). This method can be used for defining exception of the recurring event. @n\r
1048          * In order to update an event instance, you should use copy of its original event(@ref CalEventInstance::GetOriginalEventId()). @n\r
1049          * You can modify the properties of copy of the original event and use it as the second parameter of this method. @n\r
1050          * (The start/end time of the original event should be set with the start/end time of the event instance.) @n\r
1051          * 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
1052          * 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
1053          * However this method only updates the properties of the event, does not add a new event that is already added.\r
1054          *\r
1055          * @since       2.1\r
1056          * @privlevel   public\r
1057          * @privilege   %http://tizen.org/privilege/calendar.write\r
1058          *\r
1059          * @return              An error code\r
1060          * @param[in]   eventInstance                   The event instance to update @n\r
1061          *                                                                              The @c eventInstance must be an instance of the recurring event.\r
1062          * @param[in,out]       event                           The modified copy of the original event @n\r
1063          * @exception   E_SUCCESS                               The method is successful.\r
1064          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
1065          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method.\r
1066          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n\r
1067          *                                                                              - The instance is invalid. @n\r
1068          *                                                                              - @c event is not referring to the original event.\r
1069          * @exception   E_OBJ_NOT_FOUND                 The original event of the @c eventInstance is not found.\r
1070          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
1071          *\r
1072          * @code\r
1073 \r
1074                 void UpdateRecurringEventInstance(const CalEventInstance& eventInstance)\r
1075                 {\r
1076                         CalEvent* pEvent = pCalendarbook->GetEventN(eventInstance.GetOriginalEventId());\r
1077                         if (pEvent == null)\r
1078                         {\r
1079                                 AppLogException("GetEventN() has failed");\r
1080                                 return;\r
1081                         }\r
1082 \r
1083                         // Sets the start time and end time\r
1084                         pEvent->SetRecurrence(null);\r
1085                         pEvent->SetStartAndEndTime(eventInstance.GetStartTime(), eventInstance.GetEndTime());\r
1086 \r
1087                         // Modifies the properties\r
1088                         pEvent->SetLocation(L"Meeting room on 11th floor");\r
1089 \r
1090                         // Updates the instance\r
1091                         result r = pCalendarbook->UpdateEventInstance(eventInstance, *pEvent);\r
1092                         if (IsFailed(r))\r
1093                         {\r
1094                                 AppLogException("UpdateEventInstance() has failed");\r
1095                                 delete pEvent;\r
1096                                 return;\r
1097                         }\r
1098 \r
1099                         delete pEvent;\r
1100                 }\r
1101 \r
1102          * @endcode\r
1103          */\r
1104         result UpdateEventInstance(const CalEventInstance& eventInstance, CalEvent& event);\r
1105 \r
1106         /**\r
1107          * Gets the latest version of calendarbook.\r
1108          *\r
1109          * @since       2.0\r
1110          * @privlevel   public\r
1111          * @privilege   %http://tizen.org/privilege/calendar.read\r
1112          *\r
1113          * @return              The latest version\r
1114          * @exception   E_SUCCESS                               The method is successful.\r
1115          * @exception   E_PRIVILEGE_DENIED              The application does not have the privilege to call this method.\r
1116          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
1117          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
1118          * @remarks                     The specific error code can be accessed using the GetLastResult() method.\r
1119          */\r
1120         int GetLatestVersion(void) const;\r
1121 \r
1122         /**\r
1123          * Searches items of the calendarbook with the filter. @n\r
1124          * The filter specifies the item type and condition for searching.\r
1125          * The searched results are ordered by the @c propertySortedBy and @c sortOrder.\r
1126          * 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
1127          *\r
1128          * @since       2.0\r
1129          * @privlevel   public\r
1130          * @privilege   %http://tizen.org/privilege/calendar.read\r
1131          *\r
1132          * @return              A list of searched results (the list of CalEvent, CalTodo, Calendar, or CalEventInstance), @n\r
1133          *                                              else an empty list if there is no searched result, or @c null if an exception occurs\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          * @param[in]   propertySortedBy                The property for sorting @n The searched results are ordered by the values of this property.\r
1136          * @param[in]   sortOrder               The order for sorting\r
1137          * @param[in]   offset                  The offset of the searched results @n If this value is @c 0, it will be ignored.\r
1138          * @param[in]   maxCount                The maximum count of the searched results @n If this value is @c 0, it will be ignored.\r
1139          * @exception   E_SUCCESS                                               The method is successful.\r
1140          * @exception   E_PRIVILEGE_DENIED                              The application does not have the privilege to call this method.\r
1141          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
1142          * @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
1143          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.\r
1144          * @remarks                             The specific error code can be accessed using the GetLastResult() method.\r
1145          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
1146          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
1147          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
1148           * @see EventFilterProperty\r
1149           * @see TodoFilterProperty\r
1150           * @see CalendarFilterProperty\r
1151           * @see EventInstanceFilterProperty\r
1152          */\r
1153         Tizen::Base::Collection::IList* SearchN(const CalendarbookFilter& filter, unsigned long propertySortedBy = 0, Tizen::Base::SortOrder sortOrder = Tizen::Base::SORT_ORDER_NONE,\r
1154                         int offset = 0, int maxCount = 0) const;\r
1155 \r
1156         /**\r
1157          * Gets the matched item count of the search results with the filter. @n\r
1158          * The filter specifies the item type and condition for searching.\r
1159          *\r
1160          * @since       2.0\r
1161          * @privlevel   public\r
1162          * @privilege   %http://tizen.org/privilege/calendar.read\r
1163          *\r
1164          * @return              The count of the searched results\r
1165          * @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
1166          * @exception   E_SUCCESS                                               The method is successful.\r
1167          * @exception   E_PRIVILEGE_DENIED                              The application does not have the privilege to call this method.\r
1168          * @exception   E_USER_NOT_CONSENTED    The user blocks an application from calling this method. @b Since: @b 2.1\r
1169          * @exception   E_SYSTEM                                                The method cannot proceed due to a severe system error.\r
1170          * @remarks                     The specific error code can be accessed using the GetLastResult() method.\r
1171          */\r
1172         int GetMatchedItemCount(const CalendarbookFilter& filter) const;\r
1173 \r
1174         /**\r
1175          * Parses the events from specific vCalendar file. @n\r
1176          * The %ParseEventsFromVcalendarN() method supports to parse for vCalendar version 1.0 and 2.0 (iCalendar).\r
1177          *\r
1178          * @since       2.0\r
1179          *\r
1180          * @return              A list containing the CalEvent instances, @n\r
1181          *                              else an empty list if there are no events, or @c null if an exception occurs\r
1182          * @param[in]   vCalFilePath                    The path of the vCalendar file\r
1183          * @exception   E_SUCCESS                               The method is successful.\r
1184          * @exception   E_INVALID_ARG                   The specified @c vCalFilePath is invalid.\r
1185          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.\r
1186          * @exception   E_FILE_NOT_FOUND                The specified vCalendar file is not found.\r
1187          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
1188          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
1189          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
1190          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
1191          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
1192          */\r
1193         static Tizen::Base::Collection::IList* ParseEventsFromVcalendarN(const Tizen::Base::String& vCalFilePath);\r
1194 \r
1195         /**\r
1196          * Parses the to-dos from specific vCalendar file. @n\r
1197          * The %ParseTodosFromVcalendarN() method supports to parse for vCalendar version 1.0 and 2.0 (iCalendar).\r
1198          *\r
1199          * @since       2.0\r
1200          *\r
1201          * @return              A list containing the CalTodo instances, @n\r
1202          *                              else an empty list if there are no to-dos, or @c null if an exception occurs\r
1203          * @param[in]   vCalFilePath                    The path of the vCalendar file\r
1204          * @exception   E_SUCCESS                               The method is successful.\r
1205          * @exception   E_INVALID_ARG                   The specified @c vCalFilePath is invalid.\r
1206          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.\r
1207          * @exception   E_FILE_NOT_FOUND                The specified vCalendar file is not found.\r
1208          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
1209          * @remarks             The specific error code can be accessed using the GetLastResult() method.\r
1210          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is\r
1211          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer\r
1212          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.\r
1213          */\r
1214         static Tizen::Base::Collection::IList* ParseTodosFromVcalendarN(const Tizen::Base::String& vCalFilePath);\r
1215 \r
1216         /**\r
1217          * Exports the events to vCalendar 2.0 (iCalendar) file.\r
1218          *\r
1219          * @since       2.0\r
1220          *\r
1221          * @return              An error code\r
1222          * @param[in]   eventList                               The event list to export @n The list should contain CalEvent instances.\r
1223          * @param[in]   vCalFilePath                    The vCalendar file path\r
1224          * @exception   E_SUCCESS                               The method is successful.\r
1225          * @exception   E_INVALID_ARG                   The specified @c eventList is invalid or\r
1226          *                                                                              the specified @c vCalFilePath is invalid.\r
1227          * @exception   E_ILLEGAL_ACCESS                Access of vCalFilePath is denied due to insufficient permission.\r
1228          * @exception   E_FILE_ALREADY_EXIST    The vCalendar file already exists.\r
1229          * @exception   E_STORAGE_FULL                  The disk space is full.\r
1230          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
1231          */\r
1232         static result ExportEventsToVcalendar(const Tizen::Base::Collection::IList& eventList, const Tizen::Base::String& vCalFilePath);\r
1233 \r
1234         /**\r
1235          * Exports the to-dos to vCalendar 2.0 (iCalendar) file.\r
1236          *\r
1237          * @since       2.0\r
1238          *\r
1239          * @return              An error code\r
1240          * @param[in]   todoList                                The to-do list to export @n The list should contain CalTodo instances.\r
1241          * @param[in]   vCalFilePath                    The vCalendar file path\r
1242          * @exception   E_SUCCESS                               The method is successful.\r
1243          * @exception   E_INVALID_ARG                   The specified @c todoList is invalid or\r
1244          *                                                                              the specified @c vCalFilePath is invalid.\r
1245          * @exception   E_ILLEGAL_ACCESS                Access of vCalFilePath is denied due to insufficient permission.\r
1246          * @exception   E_FILE_ALREADY_EXIST    The vCalendar file already exists.\r
1247          * @exception   E_STORAGE_FULL                  The disk space is full.\r
1248          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.\r
1249          */\r
1250         static result ExportTodosToVcalendar(const Tizen::Base::Collection::IList& todoList, const Tizen::Base::String& vCalFilePath);\r
1251 \r
1252         /**\r
1253          * Gets the maximum allowable date and time in the calendarbook (that is, "December 31 2100 23:59:59").\r
1254          *\r
1255          * @since       2.0\r
1256          *\r
1257          * @return              An instance of Tizen::Base::DateTime\r
1258          */\r
1259         static Tizen::Base::DateTime GetMaxDateTime(void);\r
1260 \r
1261         /**\r
1262          * Gets the minimum allowable date and time in the calendarbook (that is, "January 1 1900 00:00:00").\r
1263          *\r
1264          * @since       2.0\r
1265          *\r
1266          * @return              An instance of Tizen::Base::DateTime\r
1267          */\r
1268         static Tizen::Base::DateTime GetMinDateTime(void);\r
1269 \r
1270 private:\r
1271         /**\r
1272          * The implementation of this copy constructor is intentionally blank and declared as private @n\r
1273          * to prohibit copying of objects.\r
1274          *\r
1275          * @since       2.0\r
1276          */\r
1277         Calendarbook(const Calendarbook& rhs);\r
1278 \r
1279         /**\r
1280          * The implementation of this copy assignment operator is intentionally blank and declared as private @n\r
1281          * to prohibit copying of objects.\r
1282          *\r
1283          * @since       2.0\r
1284          */\r
1285         Calendarbook& operator =(const Calendarbook& rhs);\r
1286 \r
1287 private:\r
1288         friend class _CalendarbookImpl;\r
1289         class _CalendarbookImpl* __pCalendarbookImpl;\r
1290 };      // Calendarbook\r
1291 \r
1292 }}      // Tizen::Social\r
1293 \r
1294 \r
1295 #endif // _FSCL_CALENDARBOOK_H_\r