src/inc/FScl_CalendarbookImpl.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://www.apache.org/licenses/LICENSE-2.0
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an "AS IS" BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17 /**
  18  * @file                FScl_CalendarbookImpl.h
  19  * @brief               This is the header file for the _CalendarbookImpl class.
  20  *
  21  * This header file contains the declarations of the _CalendarbookImpl class.
  22  */
  23
  24 #ifndef _FSCL_INTERNAL_CALENDARBOOK_IMPL_H_
  25 #define _FSCL_INTERNAL_CALENDARBOOK_IMPL_H_
  26
  27 #include <calendar2.h>
  28 #include <FBaseObject.h>
  29 #include <FSclTypes.h>
  30 #include "FScl_ICalendarbookDbChangeEventListener.h"
  31
  32 namespace Tizen { namespace Base
  33 {
  34 class String;
  35 class DateTime;
  36 namespace Collection
  37 {
  38 class IList;
  39 class ArrayList;
  40 class AllElementsDeleter;
  41 class IEnumerator;
  42 template<class KeyType, class ValueType> class HashMapT;
  43 }
  44 }}
  45
  46 namespace Tizen { namespace Locales
  47 {
  48 class TimeZone;
  49 }}
  50
  51 namespace Tizen { namespace Social
  52 {
  53
  54 class Calendarbook;
  55 class CalEvent;
  56 class CalTodo;
  57 class Calendar;
  58 class CalEventInstance;
  59 class CalEventChangeInfo;
  60 class CalTodoChangeInfo;
  61 class CalendarbookFilter;
  62 class ICalendarbookEventListener;
  63 class IRecordEventListener;
  64 class IRecordListener;
  65 class ICalendarbookEventListener;
  66 class _RecordImpl;
  67 class _CalendarbookRecordRetrivalThread;
  68 class _CalendarbookDbMonitor;
  69
  70 const static int _INVALID_VERSION = -1;
  71 const static int _INVALID_COUNT = -1;
  72
  73 /**
  74  * @class       _CalendarbookImpl
  75  * @brief       This class handles the _CalendarbookImpl operations.
  76  * @see         Calendarbook
  77  */
  78 class _CalendarbookImpl
  79         : public Tizen::Base::Object
  80         , public _ICalendarbookDbChangeEventListener
  81 {
  82
  83 public:
  84         /**
  85          * The object is not fully constructed after this constructor is called. For full construction, @n
  86          * the Construct() method must be called right after calling this constructor.
  87          *
  88          * @see             Construct()
  89          */
  90         _CalendarbookImpl(void);
  91
  92         /**
  93          * This destructor overrides Tizen::Base::Object::~Object().
  94          */
  95         virtual ~_CalendarbookImpl(void);
  96
  97         /**
  98          * Initializes this instance of _CalendarbookImpl with the specified listener.
  99          *
 100          * @see         Calendarbook::Construct
 101          */
 102         result Construct(IRecordEventListener* pListener);
 103
 104         /**
 105          * Initializes this instance of %Calendarbook.
 106          *
 107          * @return              An error code
 108          * @exception   E_SUCCESS                               The method is successful.
 109          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 110          * @exception   E_SYSTEM                                A system error has occurred.
 111          */
 112         result Construct(void);
 113
 114         /**
 115          * Initializes this instance of %Calendarbook with the specified event listener. @n
 116          * The events and to-do lists can be read, added, removed, and updated after construction.
 117          * If the event listener is registered, the application notifies the user when a record is added, removed, or updated in the device.
 118          *
 119          * @return              An error code
 120          * @param[in]   listener                                The event listener to be registered, @n
 121          *                                                                              else @c null if an event listener need not be registered
 122          * @exception   E_SUCCESS                               The method is successful.
 123          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 124          * @exception   E_SYSTEM                                A system error has occurred.
 125          */
 126         result Construct(ICalendarbookEventListener& listener);
 127
 128         /**
 129          * Adds a CalEvent to this calendarbook. @n
 130          * After adding the event to the database successfully, the event has a valid record ID.
 131          *
 132          * @compatibility This method has compatibility issues with OSP API versions @b prior @b to @b 2.1. @n
 133          *                For more information, see @ref CompCalendarbookAddEventPage "here".
 134          *
 135          * @return              An error code
 136          * @param[in/out]       event                   The CalEvent to add
 137          * @exception   E_SUCCESS                       The method was successful.
 138          * @exception   E_INVALID_STATE         This instance has not been constructed yet.
 139          * @exception   E_STORAGE_FULL          The capacity of this event was full.
 140          * @exception   E_INVALID_ARG           Either of the following conditions has occurred: @n
 141          *                                                                      -- The specified @c recordId is not #INVALID_RECORD_ID. @n
 142          *                                  -- The @c event is not #RECORD_TYPE_EVENT. @n
 143          *                                  -- The date of the event is invalid. @n
 144          *                                                                              The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().
 145          * @exception   E_SYSTEM                                A system error occurred.
 146          */
 147         result AddEvent(CalEvent& event);
 148
 149         /**
 150          * @page        CompCalendarbookAddEventPage Compatibility for AddEvent()
 151          * @section     CompCalendarbookAddEventPageIssueSection Issues
 152          *          Implementation of this method in OSP API versions prior to 2.1 has the following issue:
 153          *                      -# The event instance type can't be added.
 154          *
 155          * @section     CompCalendarbookAddEventPageSolutionSection Resolutions
 156          *                      The issue mentioned above is resolved in OSP API version 2.1, and it is recommended to use OSP API version 2.1 or above.
 157          *                      -# The event instance type will be able to be added.
 158          */
 159
 160         /**
 161          * Adds a calendar event to the specific calendar. @n
 162          * After adding the event to the database successfully, the event has a valid record ID.
 163          *
 164          * @return              An error code
 165          * @param[in/out]       event                                   The event to add
 166          * @param[in]   calendarId                              The calendar ID that the event will be added to
 167          * @exception   E_SUCCESS                               The method is successful.
 168          * @exception   E_INVALID_STATE                 This instance has not been constructed as yet.
 169          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n
 170          *                                                                              - The event is invalid. @n
 171          *                                                                              The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().
 172          *                                                                              - The specified @c calendarId is #INVALID_RECORD_ID. @n
 173          *                                                                              - The calendar type of the calendarId is #CALENDAR_TYPE_TODO
 174          * @exception   E_OBJ_NOT_FOUND                 The specified calendarId is not found.
 175          * @exception   E_SYSTEM                                A system error has occurred.
 176          */
 177         result AddEvent(CalEvent& event, RecordId calendarId);
 178
 179         /**
 180          * Adds a CalTodo to this calendarbook. @n
 181          * After adding the to-do item to the database successfully, the item has a valid record ID.
 182          *
 183          * @return              An error code
 184          * @param[in/out]       todo                            The CalTodo to add
 185          * @exception   E_SUCCESS                       The method was successful.
 186          * @exception   E_INVALID_STATE         This instance has not been constructed yet.
 187          * @exception   E_STORAGE_FULL          The capacity of this to-do was full.
 188          * @exception   E_INVALID_ARG           The specified @c recordId is not #INVALID_RECORD_ID, or the date of the to-do item is invalid. @n
 189          *                                  The valid range of the date is from 12:00:00, midnight, January 1, 1900 to 11:59:59 P.M, December 31, 2100.
 190          */
 191         result AddTodo(CalTodo& todo);
 192
 193         /**
 194          * Adds a calendar to-do to specific calendar. @n
 195          * After adding the to-do item to the database successfully, the item has a valid record ID.
 196          *
 197          * @return              An error code
 198          * @param[in/out]       todo                                    The to-do to add
 199          * @param[in]   calendarId                              The calendar ID that the todo will be added to
 200          * @exception   E_SUCCESS                               The method is successful.
 201          * @exception   E_INVALID_STATE                 This instance has not been constructed as yet.
 202          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n
 203          *                                                                                                      - The todo is invalid. @n
 204          *                                                                                                              The valid range of the date can be referenced from GetMaxDateTime() and GetMinDateTime().
 205          *                                                                                                              - The specified @c calendarId is #INVALID_RECORD_ID. @n
 206          *                                                                                                              - The calendar type of the calendarId is not #CALENDAR_TYPE_CALENDAR
 207          * @exception   E_OBJ_NOT_FOUND         The specified calendarId is not found.
 208          * @exception   E_SYSTEM                                A system error has occurred.
 209          */
 210         result AddTodo(CalTodo& todo, RecordId calendarId);
 211
 212         /**
 213          * Adds a calendar. @n
 214          * After adding the calendar to the database successfully, the calendar has a valid calendar ID.
 215          *
 216          * @return              An error code
 217          * @param[in/out]       calendar                                The calendar to add
 218          * @exception   E_SUCCESS                               The method is successful.
 219          * @exception   E_INVALID_STATE                 This instance has not been constructed as yet.
 220          * @exception   E_INVALID_ARG                   The specified @c record ID of the calendar is not #INVALID_RECORD_ID. @n
 221          * @exception   E_SYSTEM                                A system error has occurred.
 222          */
 223         result AddCalendar(Calendar& calendar);
 224
 225         /**
 226          * Adds a calendar that is associated with the specified account of the accountId. @n
 227          * After adding the calendar to the database successfully, the calendar has a valid calendar ID.
 228          *
 229          * @return              An error code
 230          * @param[in/out]       calendar                                The calendar to add
 231          * @param[in]   accountId                               The account Id
 232          * @exception   E_SUCCESS                               The method is successful.
 233          * @exception   E_INVALID_STATE                 This instance has not been constructed as yet.
 234          * @exception   E_INVALID_ARG                           Either of the following conditions has occurred: @n
 235          *                                                                                                              - The record ID of the calendar is not #INVALID_RECORD_ID. @n
 236          *                                                                                                                      - The accountId is invalid.
 237          * @exception   E_OBJ_NOT_FOUND                 The specified calendarId is not found.
 238          * @exception   E_SYSTEM                                A system error has occurred.
 239          */
 240         result AddCalendar(Calendar& calendar, AccountId accountId);
 241
 242         /**
 243          * Removes the specified CalEvent from this calendarbook. @n
 244          * After removing the event from the database successfully, the event has #INVALID_RECORD_ID.
 245          *
 246          * @return              An error code
 247          * @param[in]   event                   The CalEvent to remove
 248          * @exception   E_SUCCESS                       The method was successful.
 249          * @exception   E_INVALID_STATE         This instance has not been constructed yet.
 250          * @exception   E_INVALID_ARG           The specified @c recordId is #INVALID_RECORD_ID.
 251          * @exception   E_OBJ_NOT_FOUND         The specified record was not found.
 252          * @exception   E_SYSTEM                                A system error occurred.
 253          */
 254         result RemoveEvent(CalEvent& event);
 255
 256         /**
 257          * Removes the specified CalEvent from this calendarbook.
 258          *
 259          * @return              An error code
 260          * @param[in]   eventId                         The CalEvent Id to remove
 261          * @exception   E_SUCCESS                       The method was successful.
 262          * @exception   E_INVALID_STATE         This instance has not been constructed yet.
 263          * @exception   E_INVALID_ARG           The specified @c eventId is #INVALID_RECORD_ID.
 264          * @exception   E_OBJ_NOT_FOUND         The specified record was not found.
 265          * @exception   E_SYSTEM                                A system error occurred.
 266          */
 267         result RemoveEvent(RecordId eventId);
 268
 269         /**
 270          * Removes the specified CalTodo from this calendarbook. @n
 271          * After removing the to-do item from the database successfully, the item has #INVALID_RECORD_ID.
 272          *
 273          * @return              An error code
 274          * @param[in]   todo                            The CalTodo ID to remove
 275          * @exception   E_SUCCESS                       The method was successful.
 276          * @exception   E_INVALID_STATE         This instance has not been constructed yet.
 277          * @exception   E_INVALID_ARG           The recordId is #INVALID_RECORD_ID.
 278          * @exception   E_OBJ_NOT_FOUND         The specified record was not found.
 279          * @exception   E_SYSTEM                                A system error occurred.
 280          */
 281         result RemoveTodo(CalTodo& todo);
 282
 283         /**
 284          * Removes the specified CalTodo from this calendarbook.
 285          *
 286          * @return              An error code
 287          * @param[in]   todoId                          The CalTodo ID to remove
 288          * @exception   E_SUCCESS                       The method was successful.
 289          * @exception   E_INVALID_STATE         This instance has not been constructed yet.
 290          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 291          * @exception   E_OBJ_NOT_FOUND         The specified record was not found.
 292          * @exception   E_SYSTEM                                A system error occurred.
 293          */
 294         result RemoveTodo(RecordId todoId);
 295
 296         /**
 297          * Removes the specified calendar of the calendarId. @n
 298          *
 299          * @return              An error code
 300          * @param[in]   calendarId                              The calendar ID to be removed
 301          * @exception   E_SUCCESS                               The method is successful.
 302          * @exception   E_INVALID_STATE                 This instance has not been constructed as yet.
 303          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n
 304          *                                                                              - The specified @c calendarId is #INVALID_RECORD_ID.
 305          *                                                                              - The calendar represents default calendar. @n
 306          * @exception   E_OBJ_NOT_FOUND                 The specified calendarId is not found.
 307          * @exception   E_SYSTEM                                A system error has occurred.
 308          */
 309         result RemoveCalendar(RecordId calendarId);
 310
 311         /**
 312          * Updates the specified CalEvent to the internal data storage.
 313          *
 314          * @return              An error code
 315          * @param[in]   event                   The CalEvent to be updated
 316          * @exception   E_SUCCESS                       The method was successful.
 317          * @exception   E_INVALID_STATE         This instance has not been constructed yet.
 318          * @exception   E_INVALID_ARG           Either of the following conditions has occurred: @n
 319          *                                                                      -- The specified @c recordId is #INVALID_RECORD_ID. @n
 320          *                                  -- The @c event is not #RECORD_TYPE_EVENT. @n
 321          *                                  -- The @c event is not an entry type instance. @n
 322          *                                  -- The date of the event is invalid. @n
 323          *                                    The valid range of the date is from 12:00:00 midnight, January 1, 1900 to 11:59:59 P.M, December 31, 2100.
 324          * @exception   E_OBJ_NOT_FOUND         The specified record was not found.
 325          * @exception   E_SYSTEM                                A system error occurred.
 326          */
 327         result UpdateEvent(const CalEvent& event);
 328
 329         /**
 330          * Updates the specified CalTodo on the internal data storage.
 331          *
 332          * @return              An error code
 333          * @param[in]   todo                            The CalTodo to be updated
 334          * @exception   E_SUCCESS                       The method was successful.
 335          * @exception   E_INVALID_STATE         This instance has not been constructed yet.
 336          * @exception   E_INVALID_ARG           The specified recordId is #INVALID_RECORD_ID, or the date of the to-do item is invalid. @n
 337          *                                    The valid range of the date is from 12:00:00 midnight, January 1, 1900 to 11:59:59 P.M, December 31, 2100.
 338          * @exception   E_OBJ_NOT_FOUND         The specified record was not found.
 339          * @exception   E_SYSTEM                                A system error occurred.
 340          */
 341         result UpdateTodo(const CalTodo& todo);
 342
 343         /**
 344          * Updates the specified calendar.
 345          *
 346          * @return              An error code
 347          * @param[in]   calendar                                The Calendar instance to be updated
 348          * @exception   E_SUCCESS                               The method is successful.
 349          * @exception   E_INVALID_STATE                 This instance has not been constructed as yet.
 350          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n
 351          *                                                                              - The calendar's recordId is #INVALID_RECORD_ID. @n
 352          *                                                                              - The calendar represents default calendar. @n
 353          * @exception   E_OBJ_NOT_FOUND                 The specified calendar is not found.
 354          * @exception   E_SYSTEM                                A system error has occurred.
 355          */
 356         result UpdateCalendar(const Calendar& calendar);
 357
 358         /**
 359          * Gets the specified event ID that is matched with the RecordId.
 360          *
 361          * @return              The matched event
 362          * @param[in]   eventId                         The event ID to be found
 363          * @exception   E_SUCCESS                       The method was successful.
 364          * @exception   E_INVALID_STATE         This instance has not been constructed yet.
 365          * @exception   E_OUT_OF_MEMORY         Insufficient memory.
 366          * @exception   E_INVALID_ARG           The specified @c eventId is invalid.
 367          * @exception   E_OBJ_NOT_FOUND         The specified record was not found.
 368          * @exception   E_SYSTEM                                A system error occurred.
 369          */
 370         CalEvent* GetEventN(RecordId eventId) const;
 371
 372         /**
 373          * Gets the specified to-do after matching it with the specified RecordId.
 374          *
 375          * @return              The matched to-do
 376          * @param[in]   todoId                          The ID of the to-do to be found
 377          * @exception   E_SUCCESS                       The method was successful.
 378          * @exception   E_INVALID_STATE         This instance has not been constructed yet.
 379          * @exception   E_INVALID_ARG           The specified @c todoId is invalid.
 380          * @exception   E_OBJ_NOT_FOUND         The specified record was not found.
 381          * @exception   E_OUT_OF_MEMORY         Insufficient memory.
 382          * @exception   E_SYSTEM                                A system error occurred.
 383          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 384          *
 385          */
 386         CalTodo* GetTodoN(RecordId todoId) const;
 387
 388         /**
 389          * Gets the specified calendar that is matched with the calendarId.
 390          *
 391          * @return              The matched calendar
 392          * @param[in]   calendarId                              The calendar ID
 393          * @exception   E_SUCCESS                               The method is successful.
 394          * @exception   E_INVALID_STATE                 This instance has not been constructed as yet.
 395          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 396          * @exception   E_INVALID_ARG                   The specified @c calendarId is invalid.
 397          * @exception   E_OBJ_NOT_FOUND                 The specified calendarId is not found.
 398          * @exception   E_SYSTEM                                A system error has occurred.
 399          */
 400         Calendar* GetCalendarN(RecordId calendarId) const;
 401
 402         /**
 403          * Gets all the to-do items in the specified time range.
 404          *
 405          * @return              A list of all the matched #CalTodo instances, @n
 406          *                              else an empty list if there is no matched to-do item @n
 407          *              The items are sorted by time.
 408          * @param[in]   start                           The start of the time range
 409          * @param[in]   end                                     The end of the time range
 410          * @param[in]   pageNo                          The page number of the result list @n
 411          *                                                                      It starts from @c 1.
 412          * @param[in]   countPerPage            The desired maximum count of the result items per page @n
 413          * @param[in]   status                          The TodoStatus @n
 414          *                                                                      If you set a specific status, the to-dos that have the specified status are returned. @n
 415          *                                                                      The default status value is #TODO_STATUS_ALL, which means all the statuses are returned.
 416          * @param[in]   priority                        The TodoPriority @n
 417          *                                                                      If you set a specific priority, the to-dos that have the specified priority are returned. @n
 418          *                                                                      The default priority value is #TODO_PRIORITY_ALL that means all the priorities are returned.
 419          * @exception   E_SUCCESS                       The method was successful.
 420          * @exception   E_INVALID_STATE         This instance has not been constructed yet.
 421          * @exception   E_INVALID_ARG           Either of the following conditions has occurred: @n
 422          *                                                                      -- The specified @c pageNo or @c countPerPage is less than @c 1. @n
 423          *                                                                      -- The start time is later than the end date. @n
 424          *                                                                      -- The start or end time is not in a valid range. @n
 425          *                                  The valid range of the date is from 12:00:00 midnight, January 1, 1900 to 11:59:59 P.M, December 31, 2100.
 426          * @exception   E_OUT_OF_MEMORY         Insufficient memory.
 427          * @exception   E_SYSTEM                                A system error occurred.
 428          * @remarks             The specific error code can be accessed using the GetLastResult() method. @n
 429          *                              The values for @c status and @c priority can be set by assigning values to both the @c status and @c priority. For example, status = #STATUS_COMPLETED, priority = #TODO_PRIORITY_ALL.
 430          *
 431          */
 432         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, unsigned long priority = TODO_PRIORITY_ALL) const;
 433
 434         /**
 435          * Gets the total number of to-dos in the specified time range.
 436          *
 437          * @return              count                           The total number of to-dos, @n
 438          *                                                                      else @c -1 if an exception occurs
 439          * @param[in]   start                           The start of the time range
 440          * @param[in]   end                                     The end of the time range
 441          * @param[in]   status                          The TodoStatus @n
 442          *                                                                      If you set a specific status, the to-dos that have the specified status are returned. @n
 443          *                                                                      The default status value is #TODO_STATUS_ALL, which means all the statuses are returned.
 444          * @param[in]   priority                        The TodoPriority @n
 445          *                                                                      If you set a specific priority, the to-dos that have the specified priority are returned. @n
 446          *                                                                      The default priority value is #TODO_PRIORITY_ALL that means all the priorities are returned.
 447          * @exception   E_SUCCESS                       The method was successful.
 448          * @exception   E_INVALID_STATE         This instance has not been constructed yet.
 449          * @exception   E_INVALID_ARG           The start time is later than the end date, or the start or end time is not in a valid range. @n
 450          *                                  The valid range of the date is from 12:00:00 midnight, January 1, 1900 to 11:59:59 P.M, December 31, 2100.
 451          * @exception   E_OUT_OF_MEMORY         Insufficient memory.
 452          * @exception   E_SYSTEM                                A system error occurred.
 453          * @remark              The specific error code can be accessed using the GetLastResult() method.
 454          */
 455         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;
 456
 457         /**
 458          * Gets the CalEvent instances that are within the specified time range. @n
 459          * Anniversary and all day events are retrieved by their start and end dates in the local time zone, while all other events are retrieved by their start and end times in Coordinated Universal Time (UTC).
 460          *
 461          * @return              A list containing all of the matched #CalEvent instances, @n
 462          *                              else an empty list if there are no matched instances or @c null if an exception occurs @n
 463          *                              The results are listed in order of their start date.
 464          *                              The results within the same start date are ordered by their category in the following order: anniversaries, all day events, and other events.
 465          *                              The results in each category are sorted by their start time.
 466          * @param[in] start                             The start of the time range
 467          * @param[in] end                               The end of the time range
 468          * @param[in] timeZone                  The time zone of the specified start and end times
 469          * @param[in] pageNo                    The page number of the result list @n
 470          *                                                              It starts from @c 1.
 471          * @param[in] countPerPage              The desired maximum count of the result items on the page
 472          * @param[in] category                  The EventCategory @n
 473          *                                                              If you set a specific category, the events that have the specified category are returned. @n
 474          *                                                              The default category value is #EVENT_CATEGORY_ALL, which means all the categories are returned.
 475          * @exception E_SUCCESS                         The method was successful.
 476          * @exception E_INVALID_STATE           This instance has not been constructed yet.
 477          * @exception E_INVALID_ARG                     Either of the following conditions has occurred: @n
 478          *                                                                      -- The specified @c pageNo or @c countPerPage is less than @c 1. @n
 479          *                                                                      -- The start time is later than end date. @n
 480          *                                                                      -- The specified category is invalid. @n
 481          *                                                                      -- The start or end time is not in a valid range. @n
 482          *                                                                  The valid range of date is from 12:00:00 midnight, January 1, 1900 to 11:59:59 P.M, December 31, 2100. @n
 483          * @exception E_OUT_OF_MEMORY           Insufficient memory.
 484          * @exception E_SYSTEM                                  A system error occurred.
 485          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 486          */
 487
 488         Tizen::Base::Collection::IList* GetEventInstancesN(const Tizen::Base::DateTime& start, const Tizen::Base::DateTime& end,
 489                                                                                                          const Tizen::Locales::TimeZone& timeZone, int pageNo, int countPerPage,
 490                                                                                                          unsigned long category = EVENT_CATEGORY_ALL) const;
 491
 492         /**
 493          * Gets the CalEvent instances that are within the specified time range. @n
 494          * Anniversary and all day events are retrieved by their start and end dates in the local time zone, while all other events are retrieved by their start and end times in Coordinated Universal Time (UTC).
 495          * Although GetEventInstancesN() retrieves the data synchronously, this method returns data asynchronously using RecordListener::OnEventInstancesReceivedN(). @n
 496          * It is highly recommended to use the asynchronous method because getting event instances may take long time.
 497          *
 498          * @return              An error code
 499          * @param[in] start                             The start of the time range
 500          * @param[in] end                               The end of the time range
 501          * @param[in] timeZone                  The time zone of the specified start and end times
 502          * @param[in] pageNo                    The page number of the result list @n
 503          *                                                              It starts from @c 1.
 504          * @param[in] countPerPage              The desired maximum count of the result items on the page
 505          * @param[in] category                  The #EventCategory @n
 506          *                                                              If you set a specific category, the events which have the specified category are returned. @n
 507          *                                                              The default category value is #EVENT_CATEGORY_ALL, which means all the categories are returned.
 508          * @param[out] reqId                    The ID of the request
 509          * @param[in] listener                  The listener for receiving the responses of the request
 510          * @exception E_SUCCESS                         The method was successful.
 511          * @exception E_INVALID_STATE           This instance has not been constructed yet.
 512          * @exception E_INVALID_ARG                     Either of the following conditions has occurred: @n
 513          *                                                                      -- The specified @c pageNo or @c countPerPage is less than @c 1. @n
 514          *                                                                      -- The start time is later than end date. @n
 515          *                                                                      -- The start or end time is not in a valid range. @n
 516          *                                                                      -- The specified category is invalid. @n
 517          *                                                                      The valid range of date is from 12:00:00 midnight, January 1, 1900 to 11:59:59 P.M, December 31, 2100.
 518          * @exception E_SYSTEM                                  A system error occurred.
 519          * @remarks             IRecordListener::OnRecordsReceivedN(), Calendarbook::GetEventInstancesN()
 520          */
 521
 522         result GetEventInstances(const Tizen::Base::DateTime& start, const Tizen::Base::DateTime& end,
 523                                                          const Tizen::Locales::TimeZone& timeZone, int pageNo, int countPerPage, unsigned long category,
 524                                                          RequestId& reqId,
 525                                                          const IRecordListener& listener) const;
 526
 527         /**
 528          * Gets the all events.
 529          *
 530          * @return              A list containing all the %CalEvent instances, @n
 531          *                              else an empty list if there are no events or @c null if an exception occurs @n
 532          *                              The results are listed in the order of their start time.
 533          * @exception   E_SUCCESS                               The method is successful.
 534          * @exception   E_INVALID_STATE                 This instance has not been constructed as yet.
 535          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 536          * @exception   E_SYSTEM                                A system error has occurred.
 537          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 538          */
 539         Tizen::Base::Collection::IList* GetAllEventsN(void) const;
 540
 541         /**
 542          * Gets all to-dos.
 543          *
 544          * @since       2.0
 545          *
 546          * @return              A list containing all the CalTodo instances, @n
 547          *                              else an empty list if there are no to-dos or @c null if an exception occurs @n
 548          *                              The results are listed in the order of their to-do ID.
 549          * @exception   E_SUCCESS                               The method is successful.
 550          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 551          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 552          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 553          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is
 554          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer
 555          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 556          */
 557         Tizen::Base::Collection::IList* GetAllTodosN(void) const;
 558
 559         /**
 560          * Gets all calendars.
 561          *
 562          * @since       2.0
 563          *
 564          * @return              A list containing all the Calendar instances, @n
 565          *                              else an empty list if there are no calendars or @c null if an exception occurs @n
 566          *                              The results are listed in the order of their calendar ID.
 567          * @exception   E_SUCCESS                               The method is successful.
 568          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 569          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 570          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 571          * @remarks There is a high probability for an occurrence of an out-of-memory exception. If possible, check whether the exception is
 572          *                                      E_OUT_OF_MEMORY or not. For more information on how to handle the out-of-memory exception, refer
 573          *                                      <a href="../org.tizen.native.appprogramming/html/basics_tizen_programming/exception_check.htm">here</a>.
 574          */
 575         Tizen::Base::Collection::IList* GetAllCalendarsN(void) const;
 576
 577         /**
 578          * Gets the all infomations of changed events since the version.
 579          *
 580          * @return              A list containing the %CalEventChangeInfo instances, @n
 581          *                              else an empty list if there are no events or @c null if an exception occurs @n
 582          *                              The results are listed in the order of their version.
 583          * @param[in]   version                                 The version
 584          * @param[out]  latestVersion                   The latest change version among the changed events.
 585          * @exception   E_SUCCESS                               The method is successful.
 586          * @exception   E_INVALID_STATE                 This instance has not been constructed as yet.
 587          * @exception   E_INVALID_ARG                   The version is invalid.
 588          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 589          * @exception   E_SYSTEM                                A system error has occurred.
 590          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 591          */
 592         Tizen::Base::Collection::IList* GetChangedEventsAfterN(int version, int& latestVersion) const;
 593
 594         /**
 595          * Gets the all infomations of changed to-dos since the version.
 596          *
 597          * @return              A list containing the %CalTodoChangeInfo instances, @n
 598          *                              else an empty list if there are no to-dos or @c null if an exception occurs @n
 599          *                              The results are listed in the order of their version.
 600          * @param[in]   version                                 The version
 601          * @param[out]  latestVersion                   The latest change version among the changed to-dos.
 602          * @exception   E_SUCCESS                               The method is successful.
 603          * @exception   E_INVALID_STATE                 This instance has not been constructed as yet.
 604          * @exception   E_INVALID_ARG                   The version is invalid.
 605          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 606          * @exception   E_SYSTEM                                A system error has occurred.
 607          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 608          */
 609         Tizen::Base::Collection::IList* GetChangedTodosAfterN(int version, int& latestVersion) const;
 610
 611         /**
 612          * Removes an instance of the recurring event. @n
 613          * If the event instance has been removed successfully, its start date is added as an exception date to the recurrence of its original event.
 614          *
 615          * @return              An error code
 616          * @param[in]   eventInstance                                   The event instance to remove @n
 617          *                                                                                                              The @c eventInstance must be an instance of the recurring event.
 618          * @exception   E_SUCCESS                               The method is successful.
 619          * @exception   E_INVALID_ARG                           The instance is invalid.
 620          * @exception   E_OBJ_NOT_FOUND                 The instance is not found.
 621          * @exception   E_SYSTEM                                A system error has occurred.
 622          * @remarks             The instance's start time is added to the recurrence of original event as exception date.
 623          */
 624         result RemoveEventInstance(const CalEventInstance& eventInstance);
 625
 626         result UpdateEventInstance(const CalEventInstance& eventInstance, CalEvent& event);
 627
 628         /**
 629          * Gets the latest version of calendarbook storage.
 630          *
 631          * @return              The latest version
 632          * @exception   E_SUCCESS                               The method is successful.
 633          * @exception   E_INVALID_STATE                 This instance has not been constructed as yet.
 634          * @exception   E_SYSTEM                                A system error has occurred.
 635          */
 636         int GetLatestVersion(void) const;
 637
 638         /**
 639          * Searches items of the calendarbook with the filter.
 640          * The filter specifies the item type and condition for searching.
 641          * The searched results are ordered by the @c propertySortedBy and @c sortOrder.
 642          * 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.
 643          *
 644          * @since       2.0
 645          *
 646          * @return              A list of searched results (The list of CalEvent, CalTodo, Calendar or CalEventInstance), @n
 647          *                                              Or, an empty list if there is no searched result @n
 648          *                                              Or, null if an exception occurs.
 649          * @param[in]   filter          The filter that specifies the search condition. If the filter is empty, all items that are specified by the type of this filter will be searched.
 650          * @param[in]   propertySortedBy                The property for sorting. The searched results are ordered by the values of this property.
 651          * @param[in]   sortOrder               The order for sorting.
 652          * @param[in]   offset                  The offset of the searched results. If this value is 0, it will be ignored.
 653          * @param[in]   maxCount                The maximum count of the searched results. If this value is 0, it will be ignored.
 654          * @exception   E_SUCCESS                                               The method is successful.
 655          * @exception   E_OUT_OF_MEMORY                         The memory is insufficient.
 656          * @exception   E_INVALID_ARG                           The specified @c offset or @c maxCount is less than 0.
 657          *                                                                                                                              Or, the @c propertySortedBy is not an elements of the enumerator that corresponds with the type of the specified @c filter.
 658          * @exception   E_SYSTEM                                        The method cannot proceed due to a severe system error.
 659          * @see EventFilterProperty, TodoFilterProperty, CalendarFilterProperty, EventInstanceFilterProperty
 660          * @remarks                             The specific error code can be accessed using the GetLastResult() method.
 661          */
 662         Tizen::Base::Collection::IList* SearchN(const CalendarbookFilter& filter, unsigned long propertySortedBy, Tizen::Base::SortOrder sortOrder, int offset, int maxCount) const;
 663
 664         /**
 665          * Gets matched item count of the search results with the filter.
 666          * The filter specifies the item type and condition for searching.
 667          *
 668          * @since       2.0
 669          *
 670          * @return              The count of the searched results
 671          * @param[in]   filter  The filter that specifies the search condition. If the filter is empty, all items that are specified by the type of this filter will be searched.
 672          * @exception   E_SUCCESS                                               The method is successful.
 673          * @exception   E_OUT_OF_MEMORY                         The memory is insufficient.
 674          * @exception   E_SYSTEM                                                The method cannot proceed due to a severe system error.
 675          */
 676         int GetMatchedItemCount(const CalendarbookFilter& filter) const;
 677
 678         /**
 679          * Parses the events from specific vCalendar file.
 680          * This method supports to parse for vCalendar version 1.0 and 2.0 (iCalendar).
 681          *
 682          * @since       2.0
 683          *
 684          * @return              A list containing the CalEvent instances, @n
 685          *                              else an empty list if there are no events or @c null if an exception occurs @n
 686          * @param[in]   vCalFilePath                    The path of the vCalendar file
 687          * @exception   E_SUCCESS                               The method is successful.
 688          * @exception   E_INVALID_ARG                   The specified @c vCalFilePath is invalid.
 689          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 690          * @exception   E_FILE_NOT_FOUND                The specified vCalendar file not found.
 691          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 692          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 693          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 694          */
 695         static Tizen::Base::Collection::IList* ParseEventsFromVcalendarN(const Tizen::Base::String& vCalFilePath);
 696
 697         /**
 698          * Parses the to-dos from specific vCalendar file.
 699          * This method supports to parse for vCalendar version 1.0 and 2.0 (iCalendar).
 700          *
 701          * @since       2.0
 702          *
 703          * @return              A list containing the CalTodo instances, @n
 704          *                              else an empty list if there are no to-dos or @c null if an exception occurs @n
 705          * @param[in]   vCalFilePath                    The path of the vCalendar file
 706          * @exception   E_SUCCESS                               The method is successful.
 707          * @exception   E_INVALID_ARG                   The specified @c vCalFilePath is invalid.
 708          * @exception   E_ILLEGAL_ACCESS                Access is denied due to insufficient permission.
 709          * @exception   E_FILE_NOT_FOUND                The specified vCalendar file not found.
 710          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 711          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 712          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 713          */
 714         static Tizen::Base::Collection::IList* ParseTodosFromVcalendarN(const Tizen::Base::String& vCalFilePath);
 715
 716         /**
 717          * Exports the events to vCalendar 2.0 (iCalendar) file.
 718          *
 719          * @since       2.0
 720          *
 721          * @return              An error code
 722          * @param[in]   eventList                               The event list to export. The list should contain CalEvent instances.
 723          * @param[in]   vCalFilePath                    The vCalendar file path.
 724          * @exception   E_SUCCESS                               The method is successful.
 725          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n
 726          *                                                                              - The eventList is invalid.
 727          *                                                                              - The specified @c vCalFilePath is invalid.
 728          * @exception   E_ILLEGAL_ACCESS                Access of vCalFilePath is denied due to insufficient permission.
 729          * @exception   E_FILE_ALREADY_EXIST    The vCalendar file already exists.
 730          * @exception   E_STORAGE_FULL                  The disk space is full.
 731          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 732          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 733          */
 734         static result ExportEventsToVcalendar(const Tizen::Base::Collection::IList& eventList, const Tizen::Base::String& vCalFilePath);
 735
 736         /**
 737          * Exports the to-dos to vCalendar 2.0 (iCalendar) file.
 738          *
 739          * @since       2.0
 740          *
 741          * @return              An error code
 742          * @param[in]   todoList                                The to-do list to export. The list should contain CalTodo instances.
 743          * @param[in]   vCalFilePath                    The vCalendar file path.
 744          * @exception   E_SUCCESS                               The method is successful.
 745          * @exception   E_INVALID_ARG                   Either of the following conditions has occurred: @n
 746          *                                                                              - The todoList is invalid.
 747          *                                                                              - The specified @c vCalFilePath is invalid.
 748          * @exception   E_ILLEGAL_ACCESS                Access of vCalFilePath is denied due to insufficient permission.
 749          * @exception   E_FILE_ALREADY_EXIST    The vCalendar file already exists.
 750          * @exception   E_STORAGE_FULL                  The disk space is full.
 751          * @exception   E_OUT_OF_MEMORY                 The memory is insufficient.
 752          * @exception   E_SYSTEM                                The method cannot proceed due to a severe system error.
 753          */
 754         static result ExportTodosToVcalendar(const Tizen::Base::Collection::IList& todoList, const Tizen::Base::String& vCalFilePath);
 755
 756         /**
 757          * Gets the instances.
 758          */
 759         Tizen::Base::Collection::IList* GetEventInstancesCommonN(const Tizen::Base::DateTime& start, const Tizen::Base::DateTime& end,
 760                                                                                                          const Tizen::Locales::TimeZone& timeZone, int pageNo, int countPerPage, unsigned long category) const;
 761
 762         /**
 763          * Gets the maximum allowable date and time in the calendarbook (i.e "December 31 2100 23:59:59").
 764          *
 765          * @return              An instance of %DateTime
 766          */
 767         static Tizen::Base::DateTime GetMaxDateTime(void);
 768
 769         /**
 770          * Gets the minimum allowable date and time in the calendarbook (i.e "January 1 1900 00:00:00").
 771          *
 772          * @return              An instance of %DateTime
 773          */
 774         static Tizen::Base::DateTime GetMinDateTime(void);
 775
 776         virtual void OnCalEventChanged(void);
 777
 778         virtual void OnCalTodoChanged(void);
 779
 780         /**
 781          * Gets the Impl instance.
 782          *
 783          * @return                      The pointer to const _CalendarbookImpl
 784          * @param[in]   calendarbook            A const instance of %Calendarbook class
 785          */
 786         static _CalendarbookImpl* GetInstance(Calendarbook& calendarbook);
 787
 788         /**
 789          * Gets the Impl instance.
 790          *
 791          * @return                      The pointer to const _CalendarbookImpl
 792          * @param[in]   calendarbook            A const instance of %Calendarbook class
 793          */
 794         static const _CalendarbookImpl* GetInstance(const Calendarbook& calendarbook);
 795
 796 private:
 797         /**
 798          * The implementation of this copy constructor is intentionally blank and declared as private @n
 799          * to prohibit copying of objects.
 800          *
 801          * @since       2.0
 802          */
 803         _CalendarbookImpl(const _CalendarbookImpl& rhs);
 804
 805         /**
 806          * The implementation of this copy assignment operator is intentionally blank and declared as private @n
 807          * to prohibit copying of objects.
 808          *
 809          * @since       2.0
 810          */
 811         _CalendarbookImpl& operator =(const _CalendarbookImpl& rhs);
 812
 813         CalendarItemType GetCalendarItemTypeByCalendarId(RecordId calendarId) const;
 814         bool CheckEventExistance(RecordId eventId) const;
 815         bool CheckTodoExistance(RecordId todoId) const;
 816         bool CheckCalendarExistance(RecordId calendarId) const;
 817         bool CheckValidTodoPriority(unsigned long priority) const;
 818         bool CheckValidTodoStatus(unsigned long status) const;
 819         int ConvertTodoStatusToCalendarTodoStatus(unsigned long todoStatus) const;
 820         int ConvertTodoPriorityToCalendarTodoPriority(unsigned long todoPriority) const;
 821
 822         Tizen::Base::Collection::HashMapT<int, int>* GenerateEventCategoryMapN(void) const;
 823         Tizen::Base::Collection::IList* GetEventInstancesOfAllCategoriesN(const calendar_time_s& startTime, const calendar_time_s& endTime,
 824                         const calendar_time_s& localStartTime, const calendar_time_s& localEndTime, int pageNo, int countPerPage) const;
 825         Tizen::Base::Collection::IList* GetEventInstancesOfCategoryN(const calendar_time_s& startTime, const calendar_time_s& endTime,
 826                         const calendar_time_s& localStartTime, const calendar_time_s& localEndTime, int pageNo, int countPerPage, unsigned long category) const;
 827
 828         static CalEvent* ConvertAllDayEventInstanceHandleToCalEventN(calendar_record_h instanceHandle);
 829         static CalEvent* ConvertNonAllDayEventInstanceHandleToCalEventN(calendar_record_h instanceHandle);
 830         static CalEventInstance* ConvertAllDayEventInstanceHandleToCalEventInstanceN(calendar_record_h instanceHandle);
 831         static CalEventInstance* ConvertNonAllDayEventInstanceHandleToCalEventInstanceN(calendar_record_h instanceHandle);
 832         static CalEventChangeInfo* ConvertModifiedEventToCalEventChangeInfoN(calendar_record_h modifiedEventHandle);
 833         static CalTodoChangeInfo* ConvertModifiedTodoToCalTodoChangeInfoN(calendar_record_h modifiedTodoHandle);
 834
 835         template<typename RecordType, typename RecordTypeImpl, typename RecordView>
 836         static Tizen::Base::Collection::IList* ConvertRecordListN(calendar_list_h resultListHandle, RecordView recordView);
 837         static Tizen::Base::Collection::IList* ConvertEventInstanceListN(calendar_list_h resultListHandle, bool isAllDay);
 838
 839 private:
 840         IRecordEventListener* __pIRecordEventListener;
 841         ICalendarbookEventListener* __pICalendarbookEventListener;
 842         int __dbVersionForEvent;
 843         int __dbVersionForTodo;
 844
 845         _CalendarbookDbMonitor* __pCalendarbookDbMonitor;
 846
 847         static RequestId __requestId;
 848         static _CalendarbookRecordRetrivalThread* __pRecordRetrivalThread;
 849 };      // _CalendarbookImpl
 850
 851 }}      // Tizen::Social
 852
 853 #endif //_FSCL_INTERNAL_CALENDARBOOK_IMPL_H_