inc/FSclCalendarbook.h

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