--- /dev/null
+/**
+ * @ingroup CAPI_SOCIAL_FRAMEWORK
+ * @defgroup CAPI_SOCIAL_CALENDAR_SVC_MODULE Calendar
+ *
+ * @brief The Calendar Service API provides functions for managing calendars(including events, to-dos).
+ * This API allows you not only to store information about calendar but also to query calendar information.
+ *
+ * @section CAPI_SOCIAL_CALENDARS_SVC_MODULE_HEADER Required Header
+ * \#include <calendar.h>
+ *
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_OVERVIEW Overview
+ * A calendar is a system of organizing days for social purposes and is composed of records like events and todos.
+ * These records are made up of another sub records like alarms, attendees or extended ones.
+ * Events could have recurrence rule, instances would be generated.
+ * @image html calendar_model.png "Figure: Calendar model"
+ *
+ * The Calendar-Service provides an interface to manage the information of records.
+ * <table>
+ * <caption> Table: Calendar service properties. </caption>
+ * <tr>
+ * <td>
+ * * Managing information stored in database. <br>
+ * * Aggregating information from various accounts. <br>
+ * * Notifying changes of information. <br>
+ * * Searching information. <br>
+ * * Vcalendar supports ver1.0(vcs) / 2.0(ics).
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * Calendar service module works in a way similar to client-service architecture.
+ * In this architecture Tizen application is a client side and has to connect to service before using calendar service APIs.
+ * Connection/disconnection MUST be done with use of calendar_connect() / calendar_disconnect().
+ *
+ * @code
+ * calendar_connect();
+ *
+ * // jobs for records
+ *
+ * calendar_disconnect(); *
+ * @endcode
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Entities Entities
+ * Calendar service manages information related to following entities.
+ * - Calendar books
+ * - Represents where event and todo should belong to.
+ * - Created by one of calendars sources below
+ * -# Local device, which has no account.
+ * -# Service providers such as Google or Yahoo, with account.
+ * -# Applications like ChatON, Joyn, Facebook, etc.
+ * - Have properties like name, account id, color.
+ * - Events
+ * - Have properties like summary, start_time, description.
+ * - Single entry can be available on each calendar book.
+ * - Todos
+ * - Similar with event entry.
+ *
+ * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Entities_Relationship_between_entities Relationship between entities
+ * @image html entities.png "Figure: Relationship between entities"
+ *
+ * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Entities_Multiple_Address_books_from_Accounts Multiple Address books from Accounts
+ * Each account can create multiple calendar books. Calendar book name does not need to be unique on the device because it is handled with id.
+ * Local device address book has no account and its related account id is zero.
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Views Views
+ * \ref CAPI_SOCIAL_CALENDAR_SVC_VIEW_MODULE
+ * To access and handle entities, views are provided. <br>
+ * According to data-view declarations, generic access functions are used (calendar_db_insert_record(), calendar_record_get_int(), …). <br>
+ * Data-View is almost same as database "VIEW" which limits access and guarantees the performance by offering various views for the proper purpose.
+ *
+ * _calendar_instance_utime, _calendar_instance_localtime views are not offered but combination with another view are provided.
+ *
+ * <table>
+ * <caption> Table: Calendar views </caption>
+ * <tr>
+ * <th> Editable view </th>
+ * <th> Read only view </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * _calendar_book <br>
+ * _calendar_event <br>
+ * _calendar_todo <br>
+ * _calendar_timezone <br>
+ * _calendar_attendee <br>
+ * _calendar_alarm <br>
+ * _calendar_extended_property
+ * </td>
+ * <td>
+ * _calendar_updated_info <br>
+ * _calendar_event_calendar_book <br>
+ * _calendar_todo_calendar_book <br>
+ * _calendar_event_calendar_book_attendee <br>
+ * _calendar_instance_utime_calendar_book <br>
+ * _calendar_instance_localtime_calendar_book <br>
+ * _calendar_instance_utime_calendar_book_extended <br>
+ * _calendar_instance_localtime_calendar_book_extended
+
+ * </td>
+ * </tr>
+ * </table>
+ *
+ *
+ * _calendar_updated_info is used when identifying record changes depending on version.
+ *
+ * The other read only views are combination of editable views for UI convenience. <br>
+ * _calendar_event + _calendar_book = _calendar_event_calendar_book <br>
+ * _calendar_instance_utime + _calendar_book = _calendar_instance_utime_calendar_book <br>
+ * _calendar_event + _calendar_book + _calendar_attendee = _calendar_event_calendar_book_attendee <br>
+ *
+ *
+ * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Views_Properties Properties
+ * Record types which have *_id as their properties, hold identifiers of other records - e.g. attendee and alarm views hold id of their corresponding events or to-dos in event_id or todo_id property respectively (as children of the corresponding events or to-dos record).
+ * Properties of type 'record' are other records. For example, a event record has 'attendee' and 'alarm', which means that records of those types can be children of event type records.
+ *
+ * In calendar_view.h header file, view macros are found and below figure. show what macro means.
+ * @image html view_property.png "Figure: Properties"
+ *
+ * There is an example how to create event with view.
+ *
+ * @code
+ * // create an event with _calendar_event view.
+ * calendar_record_h event = NULL;
+ * calendar_record_create(_calendar_event._uri, &event);
+ *
+ * // set event summary to _calendar_event view.
+ * calendar_record_set_str(event, _calendar_event.summary, "Meeting");
+ * @endcode
+ *
+ * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Views_Version Version
+ *
+ * Calendar service uses version system in bellow APIs.
+ *
+ * <table>
+ * <caption> Table: Version related APIs </caption>
+ * <tr>
+ * <td>
+ * calendar_db_get_current_version(int* calendar_db_version) <br>
+ * calendar_db_get_changes_by_version(const char *view_uri, int calendar_book_id, int calendar_db_version, calendar_list_h *record_list, int *current_calendar_db_version) <br>
+ * calendar_db_get_last_change_version(int* last_change_version) <br>
+ * calendar_db_get_changes_exception_by_version(const char *view_uri, int original_event_id, int calendar_db_version, calendar_list_h *list)
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * Whenever modifications are in DB, version number is increased every time. <br>
+ * If sync applications like google, facebook sync at version 13 and they try to sync again every 1 minute, they want to get changes from version 14 to current version. <br>
+ * To get current version, calendar_db_get_current_version() is used and calendar_db_get_changes_by_version() is used to get the modified record list. calendar_db_get_changes_exception_by_version() is used to get modified instances in recurring event.
+ * (see exception in Events and instances)
+ *
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Records Records
+ * An important concept in Calendar service APIs is a record.
+ * It may be helpful to know that a record represents an actual record in the internal database, but in general, you can think of a record as a structure describing a single (but complex) view, like a calendar event or a time zone.
+ *
+ * A record has many properties, for example, a to-do record has the to-do's description, priority, progress, created, last modified and completed time, plus many others. <br>
+ * A record can also contain an identifier field, which holds an identifier of another record. Setting this field's value establishes a relation between the records, for example, a calendar event contains the identifier of a calendar book to which it belongs.
+ *
+ * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Records_URI URI
+ *
+ * A record's type is identified by a structure called the view.
+ * For example, the _calendar_event view describes the properties of the calendar event record.
+ * Every view has a special field - _uri - that uniquely identifies the view.
+ * In many cases you will need to provide the _uri value to indicate what type of record you wish to create or operate on.
+ * @code
+ * // create an event and get handle
+ * calendar_record_h event = NULL;
+ * calendar_record_create(_calendar_event._uri, &event);
+ * @endcode
+ *
+ * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Records_Record_handle Record handle
+ *
+ * To use a record, you must obtain its handle.
+ * There are many ways to obtains it, including creating a new record and referring to child records of a record.
+ * @code
+ * // create an event and get handle
+ * calendar_record_h event = NULL;
+ * calendar_record_create(_calendar_event._uri, &event);
+ *
+ * // get record handle with id
+ * calendar_record_h event2 = NULL
+ * calendar_db_get_record(_calendar_event._uri, event_id, &event2);
+ * @endcode
+ *
+ * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Records_Basic_types Basic types
+ *
+ * Records contain properties of basic types: integer, lli (long integer, long long int), double,
+ * string and calendar_time_s.<br>
+ * The calendar_time_s type holds either a long long int, or three integers (year, month, day).
+ * There are setter and getter functions for each type:
+ *
+ * <table>
+ * <caption> Table: Setter and getter functions </caption>
+ * <tr>
+ * <th> Property </th>
+ * <th> Setter </th>
+ * <th> Getter </th>
+ * </tr>
+ * <tr>
+ * <td> integer </td>
+ * <td> calendar_record_set_int </td>
+ * <td> calendar_record_get_int </td>
+ * </tr>
+ * <tr>
+ * <td> long long integer </td>
+ * <td> calendar_record_set_lli </td>
+ * <td> calendar_record_get_lli </td>
+ * </tr>
+ * <tr>
+ * <td> double </td>
+ * <td> calendar_record_set_double </td>
+ * <td> calendar_record_get_double </td>
+ * </tr>
+ * <tr>
+ * <td> string </td>
+ * <td> calendar_record_set_str </td>
+ * <td> calendar_record_get_str </td>
+ * </tr>
+ * <tr>
+ * <td> calendar_time_s </td>
+ * <td> calendar_record_set_caltime </td>
+ * <td> calendar_record_get_caltime </td>
+ * </tr>
+ * </table>
+ *
+ * A record's type is identified by a structure called the view. For example,
+ * the _calendar_event view describes the properties of the calendar event record.
+ * Every view has a special field - _uri - that uniquely identifies the view.
+ * In many cases you will need to provide the _uri value to indicate what
+ * type of record you wish to create or operate on.
+ *
+ * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Records_Child Child
+ *
+ * Records of certain type also hold 'child list' properties.
+ * If a record has property of this type, it can be a parent of other records, called child records.
+ * For example, attendee records can hold an event's identifier in their event_id property.
+ * The event is the parent record of the child attendee records.
+ *
+ * To use a record, you must obtain its handle. There are many ways to obtains it,
+ * including creating a new record and referring to child records of a record.
+ *
+ * Sample code:<br>
+ * the code below creates an event and inserts it into default event book
+ * (see below on calendar books).
+ *
+ * @code
+ * // create an event
+ * calendar_record_h event;
+ * calendar_record_create(_calendar_event._uri, &event);
+ *
+ * // set event summary
+ * calendar_record_set_str(event, _calendar_event.summary, "Meeting");
+ *
+ * // put the event into the default calendar book for events
+ * calendar_record_set_int(event, _calendar_event.calendar_book_id, book_id);
+ *
+ * // add alarm as child
+ * calendar_record_h alarm = NULL;
+ * calendar_record_create(_calendar_alarm._uri, &alarm);
+ * calendar_record_set_int(alarm, _calendar_alarm.tick_unit, CALENDAR_ALARM_TIME_UNIT_MINUTE);
+ * calendar_record_set_int(alarm, _calendar_alarm.tick, 5);
+ * calendar_record_add_child_record(event, _calendar_event.calendar_alarm, alarm);
+ *
+ * // insert calendar book into the database
+ * int event_id = 0;
+ * calendar_db_insert_record(event, &event_id);
+ *
+ * // destroy
+ * calendar_record_destroy(event, true);
+ * @endcode
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Calendar_books Calendar Books
+ * A calendar book is a placeholder for other records in Calendar API.
+ * Every event and to-do has to belong to a calendar book.
+ * There are three built-in calendar books.
+ * <table>
+ * <caption> Table: Calendar books </caption>
+ * <tr>
+ * <td> DEFAULT_EVENT_CALENDAR_BOOK_ID </td>
+ * <td> Event book </td>
+ * </tr>
+ * <tr>
+ * <td> DEFAULT_TODO_CALENDAR_BOOK_ID </td>
+ * <td> Todo book </td>
+ * </tr>
+ * <tr>
+ * <td> DEFAULT_BIRTHDAY_CALENDAR_BOOK_ID </td>
+ * <td> Birthday book </td>
+ * </tr>
+ * </table>
+ *
+ * There is an example how calendar book id is set.
+ *
+ * @code
+ * calendar_record_h event = NULL;
+ *
+ * calendar_record_create(_calendar_event._uri, &event);
+ *
+ * // set default calendar book id
+ * calendar_record_set_int(event, _calendar_event.calendar_id, DEFAULT_EVENT_CALENDAR_BOOK_ID);
+ *
+ * // set other fields
+ *
+ * int event_id = 0;
+ * calendar_db_insert_record(event &event_id);
+ *
+ * // destroy
+ * calendar_record_destroy(event, true);
+ * @endcode
+ *
+ * To receive a list of existing calendar books, use the following:
+ *
+ * @code
+ * calendar_list_h calendar_book_list = NULL;
+ * calendar_db_get_all_records(_calendar_calendar_book._uri, 0, 0, &calendar_book_list);
+ * @endcode
+ *
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Events_and_instances Events and Instances
+ * Two important concepts are event and instance. An event record describes
+ * various properties of the event, like description, categories, priority
+ * and many others. It also contains information on when the event takes place,
+ * there can be more than one instance of the event. Each instance has its
+ * corresponding instance record. <br>
+ * If event is inserted with rrule, alarm and attendee, its data is saved to each database.
+ * Generated instances based on rrule are also stored in instance database.
+ * @image html view_db.png "Figure: Views and databases"
+ *
+ * For example, if an event has the following properties:
+ * <table>
+ * <caption> Table: Event and instance example </caption>
+ * <tr>
+ * <th> event </th>
+ * <th> instances </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * start date on 2012-10-09 (Tuesday) <br>
+ * frequency set to 'WEEKLY' <br>
+ * interval set to 1 <br>
+ * count set to 3
+ * </td>
+ * <td>
+ * 2012-10-09 Tuesday <br>
+ * 2012-10-16 Tuesday <br>
+ * 2012-10-23 Tuesday
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * Interval is a multiplier of frequency, which means that if it is set to N,
+ * instances occur every N weeks (or whatever was set in frequency attribute).
+ *
+ * The recurrence model in Calendar API is compliant with iCalendar specification
+ * (<a href="http://www.ietf.org/rfc/rfc2445.txt">www.ietf.org/rfc/rfc2445.txt</a>).
+ * The following event properties have the same functionality as their corresponding
+ * values in iCalendar:
+ *
+ * <table>
+ * <caption> Table: Recurrence rules. </caption>
+ * <tr>
+ * <th> Recurrence rule property </th>
+ * <th> comment </th>
+ * </tr>
+ * <tr>
+ * <td> freq </td>
+ * <td> Yearly, monthly, weekly, daily </td>
+ * </tr>
+ * <tr>
+ * <td> count </td>
+ * <td> Until count. If count is 3, 3 instances are generated </td>
+ * </tr>
+ * <tr>
+ * <td> interval </td>
+ * <td> The interval is positive integer representing how often the recurrence rule repeats </td>
+ * </tr>
+ * <tr>
+ * <td> byday </td>
+ * <td> MO, TU, WE, TH, FR, SA, SU </td>
+ * </tr>
+ * <tr>
+ * <td> bymonthday </td>
+ * <td> Days of month </td>
+ * </tr>
+ * <tr>
+ * <td> byyearday </td>
+ * <td> Days of year </td>
+ * </tr>
+ * <tr>
+ * <td> byweekno </td>
+ * <td> Ordinals specifying weeks of the year </td>
+ * </tr>
+ * <tr>
+ * <td> bymonth </td>
+ * <td> Months of year </td>
+ * </tr>
+ * <tr>
+ * <td> bysetpos </td>
+ * <td> Values which corresponds to the nth occurrence within the set of events </td>
+ * </tr>
+ * <tr>
+ * <td> wkst </td>
+ * <td> The day on which the workweek starts </td>
+ * </tr>
+ * </table>
+ *
+ * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Events_and_instances_Exceptions Exceptions
+ *
+ * If one of instances is modified in summary, date… or deleted, this is called exception.<br>
+ * For example, if 2nd instance date is modified from 16th to 17th, 17th is the exception.
+ * <table>
+ * <caption> Table: Exception example </caption>
+ * <tr>
+ * <th> event </th>
+ * <th> instances </th>
+ * <th> exceptions </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * start date on 2012-10-09 (Tuesday) <br>
+ * frequency set to 'WEEKLY' <br>
+ * interval set to 1 <br>
+ * count set to 3
+ * </td>
+ * <td>
+ * 2012-10-09 Tuesday <br>
+ * 2012-10-23 Tuesday
+ * </td>
+ * <td>
+ * 2012-10-17 Tuesday <br>
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * To get changes in exception, calendar_db_get_changes_exception_by_version() is called. These instances and exceptions are deleted together when original event is deleted.
+ *
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Calendar_time_structure Calendar Time Structure
+ * The calendar time structure, calendar_caltime_s, is defined as follows:
+ *
+ * @code
+ * typedef struct
+ * {
+ * calendar_time_type_e type;
+ * union {
+ * long long int utime;
+ * struct {
+ * int year;
+ * int month;
+ * int mday;
+ * } date;
+ * } time;
+ * } calendar_time_s;
+ * @endcode
+ *
+ * The structure should be used when setting the calendar time type
+ * (_CALENDAR_PROPERTY_CALTIME) properties of records.
+ *
+ * It can hold two types of data: UTC time (long long int) and date,
+ * given as year, month and day of the month (three integers). These types
+ * are identified by values of calendar_time_type_e, which are CALENDAR_TIME_UTIME
+ * and CALENDAR_TIME_LOCALTIME, respectively. The data type determines the usage
+ * of the structure.
+ *
+ * <table>
+ * <caption> Table: Data types </caption>
+ * <tr>
+ * <th> Identifier </th>
+ * <th> Type </th>
+ * <th> Name </th>
+ * <th> Purpose </th>
+ * </tr>
+ * <tr>
+ * <td> CALENDAR_TIME_UTIME </td>
+ * <td> long long int </td>
+ * <td> utime </td>
+ * <td> UTC time, used to describe non-all-day events </td>
+ * </tr>
+ * <tr>
+ * <td> CALENDAR_TIME_LOCALTIME </td>
+ * <td> struct </td>
+ * <td> date </td>
+ * <td> date only (year, month and day of the month), used to describe all day events </td>
+ * </tr>
+ * </table>
+ *
+ *
+ * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Calendar_time_structure_UTC_time_usage UTC Time Usage
+ *
+ * Structures with UTC time should be used for non-all-day events.
+ * In such cases, the API user should convert local time to UTC time. The local
+ * time zone identifier should be stored in the record, in the corresponding
+ * property.
+ *
+ * For example, when setting starting time of an event, the local
+ * time zone should be stored in start_tzid.
+ *
+ * When converting local time to UTC time, the function below can be useful.
+ * The function converts the given date and time to the corresponding
+ * UTC time, considering the given time zone (first argument).
+ *
+ * @code
+ * #define ms2sec(ms) (long long int)(ms / 1000.0)
+ *
+ * long long int _time_convert_itol(char *tzid, int y, int mon, int d, int h, int min, int s)
+ * {
+ * int ret = 0;
+ * i18n_uchar utf16_timezone[CAL_STR_SHORT_LEN64] = {0};
+ * i18n_ustring_copy_ua_n(utf16_timezone, tzid, sizeof(utf16_timezone)/sizeof(i18n_uchar));
+ *
+ * i18n_ucalendar_h ucal = NULL;
+ * char *loc_default = NULL;
+ * i18n_ulocale_get_default((const char **)&loc_default);
+ * ret = i18n_ucalendar_create(utf16_timezone, -1, loc_default, I18N_UCALENDAR_GREGORIAN, &ucal);
+ * if (I18N_ERROR_NONE != ret) {
+ * dlog_print(DLOG_DEBUG, LOG_TAG, "i18n_ucalendar_create() Fail (%d)\n", ret);
+ * return -1;
+ * }
+ *
+ * i18n_ucalendar_set_date_time(ucal, y, mon - 1, d, h, min, s);
+ *
+ * i18n_udate date;
+ * ret = i18n_ucalendar_get_millisecond(ucal, &date);
+ * if (I18N_ERROR_NONE != ret) {
+ * dlog_print(DLOG_DEBUG, LOG_TAG, "i18n_ucalendar_create() Fail (%d)\n", ret);
+ * i18n_ucalendar_destroy(ucal);
+ * return -1;
+ * }
+ * i18n_ucalendar_destroy(ucal);
+ *
+ * return ms2sec(date);
+ * }
+ * @endcode
+ *
+ * Sample code:<br>
+ * @code
+ * // fill calendar time structures (start and end time)
+ * calendar_time_s st = {0};
+ * calendar_time_s et = {0};
+ *
+ * st.type = CALENDAR_TIME_UTIME;
+ * st.time.utime = _time_convert_itol("Asia/Seoul", 2012, 9, 15, 11, 0, 0);
+ *
+ * et.type = CALENDAR_TIME_UTIME;
+ * et.time.utime = _time_convert_itol("Asia/Seoul", 2012, 9, 15, 12, 0, 0);
+ *
+ * // create an event record
+ * // ...
+ *
+ * // set local time zone of start time
+ * calendar_record_set_str(event, _calendar_event.start_tzid, "Asia/Seoul");
+ *
+ * // set start time
+ * calendar_record_set_caltime(event, _calendar_event.start_time, st);
+ *
+ * // set local time zone of end time
+ * calendar_record_set_str(event, _calendar_event.end_tzid, "Asia/Seoul");
+ *
+ * // set end time
+ * calendar_record_set_caltime(event, _calendar_event.end_time, et);
+ * @endcode
+ *
+ *
+ * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Calendar_time_structure_Date_usage Date Usage
+ * Another usage of time structure is an all day event.
+ * In case of such events, the structure's type field MUST be set to CALENDAR_TIME_LOCALTIME.
+ * Only the date (no time) will be stored. Such structures can be used to set start and end time of an event. <br>
+ * Both start and end time of the event MUST be set.
+ * The end date value MUST be later in time than the value of the start date.
+ *
+ * @code
+ * // range is 2days: 2014/02/17 00:00:00 ~ 2014/02/19 00:00:00
+ *
+ * calendar_time_s st = {0};
+ * st.type = CALENDAR_TIME_LOCALTIME;
+ * st.time.date.year = 2014;
+ * st.time.date.month = 2;
+ * st.time.date.mday = 17;
+ *
+ * calendar_time_s et = {0};
+ * et.type = CALENDAR_TIME_LOCALTIME;
+ * et.time.date.year = 2014;
+ * et.time.date.month = 2;
+ * et.time.date.mday = 19;
+ *
+ * // create an event record
+ * // ...
+ * @endcode
+ *
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Creating_a_recurring_event Recurring Events
+ * To create a recurring event in Calendar API, you MUST set frequency.
+ * There is a sample code how to create recurring event. Firstly, set start and end time.
+ *
+ * @code
+ * calendar_time_s st = {0};
+ * st.type = CALENDAR_TIME_UTIME;
+ * st.time.utime = _time_convert_itol("Asia/Seoul", 2012, 9, 15, 11, 0, 0);
+ *
+ * calendar_time_s et = {0};
+ * et.type = CALENDAR_TIME_UTIME;
+ * et.time.utime = _time_convert_itol("Asia/Seoul", 2012, 9, 15, 12, 0, 0);
+ * @endcode
+ *
+ * Then, the remaining properties should be set.
+ * Each frequency needs other proper fields except daily event.
+ * If other values are not inserted, these values are calculated based on start time.
+ *
+ * <table>
+ * <caption> Table: Frequency properties </caption>
+ * <tr>
+ * <th> Freq </th>
+ * <th> Property </th>
+ * <th> Comment </th>
+ * </tr>
+ * <tr>
+ * <td> CALENDAR_RECURRENCE_YEARLY </td>
+ * <td> byyearday </td>
+ * <td> Every 100th day </td>
+ * </tr>
+ * <tr>
+ * <td> </td>
+ * <td> byweekno </td>
+ * <td> Every 34th week </td>
+ * </tr>
+ * <tr>
+ * <td> </td>
+ * <td> bymonthday </td>
+ * <td> Every 1st February (birthday)</td>
+ * </tr>
+ * <tr>
+ * <td> </td>
+ * <td> byday </td>
+ * <td> Every 1st Monday of May (holiday) </td>
+ * </tr>
+ * <tr>
+ * <td> CALENDAR_RECURRENCE_MONTHLY </td>
+ * <td> bymonthday </td>
+ * <td> Every 29th (payday) </td>
+ * </tr>
+ * <tr>
+ * <td> </td>
+ * <td> byday </td>
+ * <td> Every last Friday </td>
+ * </tr>
+ * <tr>
+ * <td> CALENDAR_RECURRENCE_WEEKLY </td>
+ * <td> byday </td>
+ * <td> Every week </td>
+ * </tr>
+ * <tr>
+ * <td> CALENDAR_RECURRENCE_DAILY </td>
+ * <td> - </td>
+ * <td> - </td>
+ * </tr>
+ * </table>
+ *
+ * If byday is not set in weekly event, default byday is followed start day of week.
+ * By the same token, default interval is 1 and default range type is endless.
+ *
+ * <table>
+ * <caption> Table: Range types </caption>
+ * <tr>
+ * <th> Range type </th>
+ * <th> Comment </th>
+ * </tr>
+ * <tr>
+ * <td> CALENDAR_RANGE_NONE </td>
+ * <td> Endless(max date is 2036/12/31) </td>
+ * </tr>
+ * <tr>
+ * <td> CALENDAR_RANGE_UNTIL </td>
+ * <td> Should set until property </td>
+ * </tr>
+ * <tr>
+ * <td> CALENDAR_RANGE_COUNT </td>
+ * <td> Should set count property </td>
+ * </tr>
+ * </table>
+ *
+ * @code
+ * calendar_record_h event;
+ * calendar_record_create(_calendar_event._uri, &event);
+ *
+ * calendar_record_set_str(event, _calendar_event.start_tzid, "Asia/Seoul");
+ * calendar_record_set_caltime(event, _calendar_event.start_time, st);
+ * calendar_record_set_str(event, _calendar_event.end_tzid, "Asia/Seoul");
+ * calendar_record_set_caltime(event, _calendar_event.end_time, et);
+ *
+ * calendar_record_set_int(event, _calendar_event.freq, CALENDAR_RECURRENCE_WEEKLY);
+ * calendar_record_set_int(event, _calendar_event.interval, 1)
+ * calendar_record_set_int(event, _calendar_event.count, 3);
+ * @endcode
+ *
+ * The last step is inserting the event into the database.
+ * Records representing instances of the event are created when the event record is inserted.
+ *
+ * @code
+ * int event_id = 0;
+ * calendar_db_insert_record(event, &event_id);
+ *
+ * calendar_record_destroy(event, true);
+ * @endcode
+ *
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Filters_and_queries Filters and Queries
+ * Queries are used to retrieve data which satisfies given criteria, like an integer
+ * property being greater than a given value, or a string property containing a given substring.
+ * The criteria are defined by creating filters and adding conditions to them, joining them
+ * with logical operators. Also, instead of a condition, another filter can be added,
+ * which can be used to create more complex filters.
+ *
+ * Operator precedence in filters determined by the order in which the
+ * conditions and filters are added.
+ *
+ * When a filter is ready, it can be set as a property of a query.
+ * Other query properties allow configuring how the returned results
+ * are grouped and sorted.
+ *
+ * Operator precedence in filters is determined by the order in which the
+ * conditions and filters are added are added.
+ * For example, if the following sequence is added:
+ *
+ * <table>
+ * <caption> Table: Filter and conditions </caption>
+ * <tr>
+ * <th> Filter with conditions </th>
+ * <th> Result </th>
+ * </tr>
+ * <tr>
+ * <td>
+ * Contidion C1 <br>
+ * OR <br>
+ * Contidion C2 <br>
+ * AND <br>
+ * Condition C3
+ * </td>
+ * <td> (C1 OR C2) AND C3 </td>
+ * </tr>
+ * <tr>
+ * <td>
+ * Filter F1: <br>
+ * Condition C1 <br>
+ * OR <br>
+ * Condition C2 <br><br>
+ * Filter F2: <br>
+ * Condition C3 <br>
+ * OR <br>
+ * Condition C4 <br><br>
+ * Filter F3: <br>
+ * Condition C5 <br>
+ * AND <br>
+ * F1 <br>
+ * AND <br>
+ * F2
+ * </td>
+ * <td>
+ * (C5 AND F1) AND F2 <br>
+ * Which is: <br>
+ * (C5 AND (C1 OR C2)) AND (C3 OR C4)
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * The following code creates a filter, accepting events with high priority
+ * or those that include the word "meeting" in their description.
+ *
+ * @code
+ * calendar_filter_h filter = NULL;
+ *
+ * // create a filter returning event type records
+ * calendar_filter_create(_calendar_event._uri, &filter);
+ *
+ * // add 'priority equals high' condition
+ * calendar_filter_add_int(filter, _calendar_event.priority, CALENDAR_MATCH_EQUAL, CALENDAR_EVENT_PRIORITY_HIGH);
+ *
+ * // add OR operator
+ * calendar_filter_add_operator(filter, CALENDAR_FILTER_OPERATOR_OR);
+ *
+ * // add 'description contains "meeting"' condition
+ * calendar_filter_add_str(filter, _calendar_event.description, CALENDAR_MATCH_CONTAINS, "meeting");
+ * @endcode
+ *
+ * The filter should be inserted into a query and the query should be executed:
+ *
+ * @code
+ * calendar_query_h query = NULL;
+ * calendar_list_h list = NULL;
+ *
+ * // create a query returning event type records
+ * calendar_query_create(_calendar_event._uri, &query);
+ *
+ * // add the filter
+ * calendar_query_set_filter(query, filter);
+ *
+ * // execute the query, results are returned in a list
+ * calendar_db_get_records_with_query(query, 0, 0, &list);
+ *
+ * calendar_filter_destroy(filter);
+ * calendar_query_destroy(query);
+ *
+ * // use the list
+ * // ...
+ *
+ * calendar_list_destroy(list, true);
+ * @endcode
+ *
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Projections Projections
+ * Useful concept in Calendar service APIs is projection, related to searching with filters and queries.
+ * Projection allows you to query the Data for just those specific properties of a record that you actually need, at lower latency
+ * and cost than retrieving the entire properties
+ *
+ * Sample code:<br>
+ * create filter which will get event id, summary and start time from the record with its summary has “test” (string filter).
+ * Create a query and add the filter to it. Results are received in a list.
+ *
+ * @code
+ * calendar_query_h query = NULL;
+ * calendar_filter_h filter = NULL;
+ *
+ * // set query with filter
+ * calendar_query_create(_calendar_event_calendar_book_attendee._uri, &query);
+ * calendar_filter_create(_calendar_event_calendar_book_attendee._uri, &filter);
+ * calendar_filter_add_str(filter, _calendar_event.summary, CALENDAR_MATCH_CONTAINS, "test");
+ * calendar_query_set_filter(query, filter);
+ *
+ * // set projection
+ * unsigned int projection[3];
+ * projection[0]=_calendar_event_calendar_book_attendee.event_id;
+ * projection[1]=_calendar_event_calendar_book_attendee.summary;
+ * projection[2]=_calendar_event_calendar_book_attendee.start_time;
+ *
+ * // get list
+ * calendar_query_set_projection(query, projection, 3);
+ * calendar_db_get_records_with_query(query, 0, 0, &list);
+ *
+ * // destroy handle
+ * calendar_filter_destroy(filter);
+ * calendar_query_destroy(query);
+ * calendar_list_destroy(list, true);
+ * @endcode
+ *
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Reminders Reminders
+ * Alarm and reminder is the similar terminology but reminder is used as package name storages in below figure 5.
+ * When alarm alerts, calendar-service sends notification to all packages which is registered in reminder DB table with calendar_reminder_add_receiver().
+ *
+ * This shows how to set alarm and how alarm works.
+ *
+ * @image html alarm_process.png "Figure: Alarm process"
+ * After adding receiver, registered alarm would be alerted on reserved time by inserting alarm as child.
+ *
+ * <table>
+ * <caption> Table: Alarm fields </caption>
+ * <tr>
+ * <th> tick_unit </th>
+ * <th> related field </th>
+ * <th> comment </th>
+ * </tr>
+ * <tr>
+ * <td> CALENDAR_ALARM_TIME_UNIT_SPECIFIC </td>
+ * <td> time </td>
+ * <td> This represents the number of seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC) </td>
+ * </tr>
+ * <tr>
+ * <td> CALENDAR_ALARM_TIME_UNIT_WEEK </td>
+ * <td> tick </td>
+ * <td> The number of weeks before start time </td>
+ * </tr>
+ * <tr>
+ * <td> CALENDAR_ALARM_TIME_UNIT_DAY </td>
+ * <td> tick </td>
+ * <td> The number of days before start time </td>
+ * </tr>
+ * <tr>
+ * <td> CALENDAR_ALARM_TIME_UNIT_HOUR </td>
+ * <td> tick </td>
+ * <td> The number of hours before start time </td>
+ * </tr>
+ * <tr>
+ * <td> CALENDAR_ALARM_TIME_UNIT_MINUTE </td>
+ * <td> tick </td>
+ * <td> The number of minutes before start time </td>
+ * </tr>
+ * </table>
+ *
+ * Below example shows the alarm which is set 1 minute before start time.
+ *
+ * @code
+ // set alarm with normal unit
+ * calendar_record_h alarm = NULL;
+ * calendar_record_create(_calendar_alarm._uri, &alarm);
+ * calendar_record_set_int(alarm, _calendar_alarm.tick_unit, CALENDAR_ALARM_TIME_UNIT_MINUTE);
+ * calendar_record_set_int(alarm, _calendar_alarm.tick, 1); // before 1min (60secs)
+ *
+ * // add alarm as child
+ * calendar_record_add_child_record(event, _calendar_event.calendar_alarm, alarm);
+ * @endcode
+ *
+ * With CALENDAR_ALARM_TIME_UNIT_SPECIFIC, the alarm could be set regardless of the start time.
+ *
+ * @code
+ // set alarm with specific unit
+ * calendar_record_h alarm = NULL;
+ * calendar_record_create(_calendar_alarm._uri, &alarm);
+ * calendar_record_set_int(alarm, _calendar_alarm.tick_unit, CALENDAR_ALARM_TIME_UNIT_SPECIFIC);
+ * // suppose start time is 1404036000(Sun, 29 Jun 2014 10:00:00 GMT) and alarm is set 60secs after from start time.
+ * calendar_time_s ct;
+ * ct.type = CALENDAR_TIME_UTIME;
+ * ct.time.utime = 1404036000 + 60;
+ * calendar_record_set_caltime(alarm, _calendar_alarm.alarm_time, ct);
+ *
+ * // add alarm as child
+ * calendar_record_add_child_record(event, _calendar_event.calendar_alarm, alarm);
+ * @endcode
+ *
+ * How to register package as reminder.
+ *
+ * In manifest.xml file, below code must be inserted.
+ * @code
+ * <app-control>
+ * <operation name="http://tizen.org/appcontrol/operation/view" />
+ * <mime name="application/x-tizen.calendar.reminder" />
+ * </app-control>
+ * @endcode
+ *
+ * When alarm alerts, calendar-service sends data with key, value pairs.<br>
+ * With "ids" key, id array could be get.<br>
+ * Each detail value could be get with "each id" key.<br>
+ * The detail data is the combination of alarm values. id, time, tick, unit and type is connected with "&" charater.<br>
+ * ex> id=64&time=1415106300&tick=0&unit=60&type=0
+ *
+ * @code
+ * // "ids" string is the key, to get id array
+ * char **ids = NULL;
+ * int len = 0;
+ * app_control_get_extra_data_array(b, "ids", &ids, &len);
+ *
+ * int i = 0;
+ * for (i = 0; i < len; i++) {
+ * // "id" is the key to get detail value
+ * char *value = NULL;
+ * app_control_get_extra_data(b, ids[i], &value);
+ * if (NULL == value) {
+ * continue;
+ * }
+ * // parse detail data
+ *
+ * // free
+ * free(ids[i]);
+ * ids[i] = NULL;
+ * }
+ *
+ * free(ids);
+ * @endcode
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Db_change_noties Database Change Notifications
+ *
+ * Applications add/remove callback function to detect/ignore the calendar DB changes
+ * with calendar_db_add_changed_cb() / calendar_db_remove_changed_cb(). <br>
+ * Clients wait calendar change notification on client side.
+ * If calendar is changed by another module, server publishes inotify event. Inotify module broadcasts to subscribe modules.
+ * Internal inotify handler is called at client side. User callback function is called with user data.
+ *
+ * @code
+ * // add callback function
+ * void __event_changed_cb(const char *view_uri, void *user_data)
+ * {
+ * }
+ * // add changed noti callback
+ * calendar_db_add_changed_cb(_calendar_event._uri, __event_changed_cb, NULL);
+ * @endcode
+ *
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Vcalendar Vcalendar
+ *
+ * To exchange of personal calendaring and scheduling information, vcalendar is used.
+ * In order to avoid confusion with this referenced work, this is to be known as the vcalendar specification.
+ * Vcalendar ver2.0 is known as icalendar.
+ *
+ *
+ * <table>
+ * <caption> Table: Vcalendar example ( http://www.ietf.org/rfc/rfc2445.txt ) </caption>
+ * <tr>
+ * <td>
+ * BEGIN:VCALENDAR<br>
+ * VERSION:2.0<br>
+ * PRODID:-//hacksw/handcal//NONSGML v1.0//EN<br>
+ * BEGIN:VEVENT<br>
+ * DTSTART:19970714T170000Z<br>
+ * DTEND:19970715T035959Z<br>
+ * SUMMARY:Bastille Day Party<br>
+ * END:VEVENT<br>
+ * END:VCALENDAR<br>
+ * </td>
+ * </tr>
+ * </table>
+ *
+ * Calendar service provides APIs to compose vcalendar stream.
+ * With stream, file could be made or data could be transmitted with json data.
+ *
+ * @code
+ * calendar_list_h list = NULL;
+ * // create or get list to make vcalendar stream
+ *
+ * char *stream = NULL;
+ * calendar_vcalendar_make_from_records(list, &stream);
+ *
+ * // jobs for stream
+ *
+ * // free
+ * free(stream);
+ * @endcode
+ *
+ * Vcalendar could be parsed with calendar service APIs as well.
+ *
+ * @code
+ * // read stream from file
+ *
+ * calendar_list_h list = NULL;
+ * calendar_vcalendar_parse_to_calendar(stream, &list);
+ *
+ * // jobs for list…
+ * calendar_list_destroy(list, true);
+ * @endcode
+ *
+ */
+
+/**
+ * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
+ * @defgroup CAPI_SOCIAL_CALENDAR_SVC_DATABASE_MODULE Database
+ *
+ * @brief The calendar database API provides the set of the definitions and interfaces that enable you to handle calendar database.
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_DATABASE_MODULE_HEADER Required Header
+ * \#include <calendar.h>
+ *
+ * <BR>
+ */
+
+/**
+ * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
+ * @defgroup CAPI_SOCIAL_CALENDAR_SVC_FILTER_MODULE Filter
+ *
+ * @brief The calendar filter API provides the set of the definitions and interfaces that enable you to handle filter.
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_FILTER_MODULE_HEADER Required Header
+ * \#include <calendar.h>
+ *
+ * <BR>
+ */
+
+/**
+ * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
+ * @defgroup CAPI_SOCIAL_CALENDAR_SVC_LIST_MODULE List
+ *
+ * @brief The calendar list API provides the set of the definitions and interfaces that enable you to handle list.
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_LIST_MODULE_HEADER Required Header
+ * \#include <calendar.h>
+ *
+ * <BR>
+ */
+
+/**
+ * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
+ * @defgroup CAPI_SOCIAL_CALENDAR_SVC_QUERY_MODULE Query
+ *
+ * @brief The calendar query API provides the set of the definitions and interfaces that enable you to handle query.
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_QUERY_MODULE_HEADER Required Header
+ * \#include <calendar.h>
+ *
+ * <BR>
+ */
+
+/**
+ * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
+ * @defgroup CAPI_SOCIAL_CALENDAR_SVC_RECORD_MODULE Record
+ *
+ * @brief The calendar record API provides the set of the definitions and interfaces that enable you to get/set data from/to calendar record handle.
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_RECORD_MODULE_HEADER Required Header
+ * \#include <calendar.h>
+ *
+ * <BR>
+ */
+
+/**
+ * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
+ * @defgroup CAPI_SOCIAL_CALENDAR_SVC_REMINDER_MODULE Reminder
+ *
+ * @brief The calendar reminder API provides the interface to set/unset reminder callback.
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_REMINDER_MODULE_HEADER Required Header
+ * \#include <calendar.h>
+ *
+ * <BR>
+ */
+
+/**
+ * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
+ * @defgroup CAPI_SOCIAL_CALENDAR_SVC_VCALENDAR_MODULE vCalendar
+ *
+ * @brief The calendar vcalendar API provides the set of the definitions and interfaces that enable you to get/set data from/to vCalendar.
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_VCALENDAR_MODULE_HEADER Required Header
+ * \#include <calendar.h>
+ *
+ * <BR>
+ */
+
+/**
+ * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
+ * @defgroup CAPI_SOCIAL_CALENDAR_SVC_VIEW_MODULE View/Property
+ *
+ * @brief This page provides information about views with properties.
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_VIEW_MODULE_OVERVIEW Overview
+ * A view is a structure which describes properties of a record.
+ * A record can have basic properties of four types: integer, string, long integer. Each property
+ * of basic type has functions to operate on it:
+ *
+ * <table>
+ * <tr>
+ * <th> Property </th>
+ * <th> Setter </th>
+ * <th> Getter </th>
+ * </tr>
+ * <tr>
+ * <td> integer </td>
+ * <td> calendar_record_set_int </td>
+ * <td> calendar_record_get_int </td>
+ * </tr>
+ * <tr>
+ * <td> long long integer </td>
+ * <td> calendar_record_set_lli </td>
+ * <td> calendar_record_get_lli </td>
+ * </tr>
+ * <tr>
+ * <td> double </td>
+ * <td> calendar_record_set_double </td>
+ * <td> calendar_record_get_double </td>
+ * </tr>
+ * <tr>
+ * <td> string </td>
+ * <td> calendar_record_set_str </td>
+ * <td> calendar_record_get_str </td>
+ * </tr>
+ * <tr>
+ * <td> calendar_time_s </td>
+ * <td> calendar_record_set_caltime </td>
+ * <td> calendar_record_get_caltime </td>
+ * </tr>
+ * </table>
+ *
+ * For long long integer functions, "lli" stands for long long int, ususally used to hold UTC time.
+ *
+ * Below you can find tables with view properties.
+ *
+ * Properties of type 'record' are other records. For example, the @ref CAPI_SOCIAL_CALENDAR_SVC_VIEW_MODULE_calendar_event
+ * has a 'calendar_alarm' property of type 'record'. This means that records of type calendar_alarm (@ref CAPI_SOCIAL_CALENDAR_SVC_VIEW_MODULE_calendar_alarm)
+ * can be children of the event record. If a name record holds the identifier
+ * of a event record in its 'event_id' property, it is the child record of the corresponding
+ * event record.
+ *
+ * Records can have many children of a given type.
+ *
+ * Please refer to the main section of Calendar API for a more detailed explanation and examples.
+ *
+ * @section CAPI_SOCIAL_CALENDAR_SVC_VIEW_MODULE_HEADER Required Header
+ * \#include <calendar.h>
+ */
+
+
projects / platform / core / pim / calendar-service.git / commitdiff
