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