doc/calendar_doc.h

   1 /*
   2  * Calendar Service
   3  *
   4  * Copyright (c) 2012 - 2015 Samsung Electronics Co., Ltd. All rights reserved.
   5  *
   6  * Licensed under the Apache License, Version 2.0 (the "License");
   7  * you may not use this file except in compliance with the License.
   8  * You may obtain a copy of the License at
   9  *
  10  * http://www.apache.org/licenses/LICENSE-2.0
  11  *
  12  * Unless required by applicable law or agreed to in writing, software
  13  * distributed under the License is distributed on an "AS IS" BASIS,
  14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  * See the License for the specific language governing permissions and
  16  * limitations under the License.
  17  *
  18  */
  19
  20
  21 #ifndef __TIZEN_SOCIAL_CALENDAR_DOC_H__
  22 #define __TIZEN_SOCIAL_CALENDAR_DOC_H__
  23
  24
  25 /**
  26  * @ingroup CAPI_SOCIAL_FRAMEWORK
  27  * @defgroup CAPI_SOCIAL_CALENDAR_SVC_MODULE Calendar
  28  * @brief The Calendar Service API provides functions for managing calendars(including events, to-dos).
  29  *        This API allows you not only to store information about calendar but also to query calendar information.
  30  * @section CAPI_SOCIAL_CALENDARS_SVC_MODULE_HEADER Required Header
  31  * \#include <calendar.h>
  32  *
  33  * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_OVERVIEW Overview
  34  * A calendar is a system of organizing days for social purposes and is composed of records like events and to-dos.
  35  * These records are made up of another sub records like alarms, attendees or extended ones.
  36  * Events could have recurrence rule, instances would be generated.
  37  *
  38  * @image html calendar_model.png "Figure: Calendar model"
  39  * The Calendar-Service provides an interface to manage the information of records.
  40  * <table>
  41  * <caption> Table: Calendar service properties. </caption>
  42  *      <tr>
  43  *              <td>
  44  *              * Managing information stored in database. <br>
  45  *              * Aggregating information from various accounts. <br>
  46  *              * Notifying changes of information. <br>
  47  *              * Searching information. <br>
  48  *              * Vcalendar  supports ver1.0(vcs) / 2.0(ics).
  49  *              </td>
  50  *      </tr>
  51  * </table>
  52  * Calendar service module works in a way similar to client-service architecture.
  53  * In this architecture Tizen application is a client side and has to connect to service before using calendar service APIs.
  54  * Connection/disconnection MUST be done with use of calendar_connect() / calendar_disconnect().
  55  *
  56  * @code
  57  * calendar_connect();
  58  *
  59  * // Jobs for records
  60  *
  61  * calendar_disconnect(); *
  62  * @endcode
  63  *
  64  * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Entities Entities
  65  * Calendar service manages information related to following entities.
  66  * - Calendar books
  67  *    - Represents where event and to-do should belong to.
  68  *    - Created by one of calendars sources below
  69  *       -# Local device, which has no account.
  70  *       -# Service providers such as Google or Yahoo, with account.
  71  *       -# Applications like ChatON, Joyn, Facebook, etc.
  72  *    - Have properties like name, account id, color.
  73  * - Events
  74  *    - Have properties like summary, start_time, description.
  75  *    - Single entry can be available on each calendar book.
  76  * - To-dos
  77  *    - Similar with event entry.
  78  *
  79  * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Entities_Relationship_between_entities Relationship between entities
  80  *
  81  * @image html entities.png "Figure: Relationship between entities"
  82  *
  83  * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Entities_Multiple_Address_books_from_Accounts Multiple Address books from Accounts
  84  * 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.
  85  * Local device address book has no account and its related account id is zero.
  86  *
  87  * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Views Views
  88  * \ref CAPI_SOCIAL_CALENDAR_SVC_VIEW_MODULE
  89  * To access and handle entities, views are provided. <br>
  90  * According to data-view declarations, generic access functions are used (calendar_db_insert_record(), calendar_record_get_int(), …). <br>
  91  * Data-View is almost same as database "VIEW" which limits access and guarantees the performance by offering various views for the proper purpose.
  92  * _calendar_instance_utime, _calendar_instance_localtime views are not offered but combination with another view are provided.
  93  * <table>
  94  * <caption> Table: Calendar views </caption>
  95  * <tr>
  96  *      <th> Editable view </th>
  97  *      <th> Read only view </th>
  98  * </tr>
  99  * <tr>
 100  *      <td>
 101  *              _calendar_book <br>
 102  *              _calendar_event <br>
 103  *              _calendar_todo <br>
 104  *              _calendar_timezone <br>
 105  *              _calendar_attendee <br>
 106  *              _calendar_alarm <br>
 107  *              _calendar_extended_property
 108  *      </td>
 109  *      <td>
 110  *              _calendar_updated_info <br>
 111  *              _calendar_event_calendar_book <br>
 112  *              _calendar_todo_calendar_book <br>
 113  *              _calendar_event_calendar_book_attendee <br>
 114  *              _calendar_instance_utime_calendar_book <br>
 115  *              _calendar_instance_localtime_calendar_book <br>
 116  *              _calendar_instance_utime_calendar_book_extended <br>
 117  *              _calendar_instance_localtime_calendar_book_extended
 118
 119  *      </td>
 120  * </tr>
 121  * </table>
 122  * _calendar_updated_info is used when identifying record changes depending on version.
 123  * The other read only views are combination of editable views for UI convenience. <br>
 124  * _calendar_event + _calendar_book = _calendar_event_calendar_book <br>
 125  * _calendar_instance_utime + _calendar_book = _calendar_instance_utime_calendar_book <br>
 126  * _calendar_event + _calendar_book + _calendar_attendee = _calendar_event_calendar_book_attendee <br>
 127  *
 128  *
 129  * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Views_Properties Properties
 130  * 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).
 131  * 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.
 132  * In calendar_view.h header file, view macros are found and below figure shows what macro means.
 133  *
 134  * @image html view_property.png "Figure: Properties"
 135  *
 136  * There is an example how to create event with view.
 137  *
 138  * @code
 139  * // Create an event with _calendar_event view
 140  * calendar_record_h event = NULL;
 141  * calendar_record_create(_calendar_event._uri, &event);
 142  *
 143  * // Set event summary to _calendar_event view
 144  * calendar_record_set_str(event, _calendar_event.summary, "Meeting");
 145  * @endcode
 146  *
 147  * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Views_Version Version
 148  * Calendar service uses version system in below APIs.
 149  * <table>
 150  * <caption> Table: Version related APIs </caption>
 151  * <tr>
 152  *  <td>
 153  * calendar_db_get_current_version(int* calendar_db_version) <br>
 154  * 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>
 155  * calendar_db_get_last_change_version(int* last_change_version) <br>
 156  * calendar_db_get_changes_exception_by_version(const char *view_uri, int original_event_id, int calendar_db_version, calendar_list_h *list)
 157  *  </td>
 158  * </tr>
 159  * </table>
 160  * Whenever modifications are in DB, version number is increased every time. <br>
 161  * 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>
 162  * 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.
 163  * (see exception in Events and instances)
 164  *
 165  * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Records Records
 166  * An important concept in Calendar service APIs is a record.
 167  * 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.
 168  * 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>
 169  * 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.
 170  *
 171  * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Records_URI URI
 172  * A record's type is identified by a structure called the view.
 173  * For example, the _calendar_event view describes the properties of the calendar event record.
 174  * Every view has a special field - _uri - that uniquely identifies the view.
 175  * In many cases you will need to provide the _uri value to indicate what type of record you wish to create or operate on.
 176  *
 177  * @code
 178  * // Create an event and get handle
 179  * calendar_record_h event = NULL;
 180  * calendar_record_create(_calendar_event._uri, &event);
 181  * @endcode
 182  *
 183  * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Records_Record_handle Record handle
 184  * To use a record, you must obtain its handle.
 185  * There are many ways to obtain it, including creating a new record and referring to child records of a record.
 186  *
 187  * @code
 188  * // Create an event and get handle
 189  * calendar_record_h event = NULL;
 190  * calendar_record_create(_calendar_event._uri, &event);
 191  *
 192  * // Get record handle with ID
 193  * calendar_record_h event2 = NULL
 194  * calendar_db_get_record(_calendar_event._uri, event_id, &event2);
 195  * @endcode
 196  *
 197  * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Records_Basic_types Basic types
 198  * Records contain properties of basic types: integer, lli (long integer, long long int), double,
 199  * string and calendar_time_s.<br>
 200  * The calendar_time_s type holds either a long long int, or three integers (year, month, day).
 201  * There are setter and getter functions for each type:
 202  * <table>
 203  * <caption> Table: Setter and getter functions </caption>
 204  * <tr>
 205  *     <th> Property </th>
 206  *     <th> Setter </th>
 207  *     <th> Getter </th>
 208  * </tr>
 209  * <tr>
 210  *     <td> integer </td>
 211  *     <td> calendar_record_set_int </td>
 212  *     <td> calendar_record_get_int </td>
 213  * </tr>
 214  * <tr>
 215  *     <td> long long integer </td>
 216  *     <td> calendar_record_set_lli </td>
 217  *     <td> calendar_record_get_lli </td>
 218  * </tr>
 219  * <tr>
 220  *     <td> double </td>
 221  *     <td> calendar_record_set_double </td>
 222  *     <td> calendar_record_get_double </td>
 223  * </tr>
 224  * <tr>
 225  *     <td> string </td>
 226  *     <td> calendar_record_set_str </td>
 227  *     <td> calendar_record_get_str </td>
 228  * </tr>
 229  * <tr>
 230  *     <td> calendar_time_s </td>
 231  *     <td> calendar_record_set_caltime </td>
 232  *     <td> calendar_record_get_caltime </td>
 233  * </tr>
 234  * </table>
 235  * A record's type is identified by a structure called the view. For example,
 236  * the _calendar_event view describes the properties of the calendar event record.
 237  * Every view has a special field - _uri - that uniquely identifies the view.
 238  * In many cases you will need to provide the _uri value to indicate what
 239  * type of record you wish to create or operate on.
 240  *
 241  * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Records_Child Child
 242  * Records of certain type also hold 'child list' properties.
 243  * If a record has property of this type, it can be a parent of other records, called child records.
 244  * For example, attendee records can hold an event's identifier in their event_id property.
 245  * The event is the parent record of the child attendee records.
 246  * To use a record, you must obtain its handle. There are many ways to obtains it,
 247  * including creating a new record and referring to child records of a record.
 248  * Sample code:<br>
 249  * the code below creates an event and inserts it into default event book
 250  * (see below on calendar books).
 251  *
 252  * @code
 253  * // Create an event
 254  * calendar_record_h event;
 255  * calendar_record_create(_calendar_event._uri, &event);
 256  *
 257  * // Set event summary
 258  * calendar_record_set_str(event, _calendar_event.summary, "Meeting");
 259  *
 260  * // Put the event into the default calendar book for events
 261  * calendar_record_set_int(event, _calendar_event.calendar_book_id, book_id);
 262  *
 263  * // Add alarm as child
 264  * calendar_record_h alarm = NULL;
 265  * calendar_record_create(_calendar_alarm._uri, &alarm);
 266  * calendar_record_set_int(alarm, _calendar_alarm.tick_unit, CALENDAR_ALARM_TIME_UNIT_MINUTE);
 267  * calendar_record_set_int(alarm, _calendar_alarm.tick, 5);
 268  * calendar_record_add_child_record(event, _calendar_event.calendar_alarm, alarm);
 269  *
 270  * // Insert calendar book into the database
 271  * int event_id = 0;
 272  * calendar_db_insert_record(event, &event_id);
 273  *
 274  * // Destroy
 275  * calendar_record_destroy(event, true);
 276  * @endcode
 277  *
 278  * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Calendar_books Calendar Books
 279  * A calendar book is a placeholder for other records in Calendar API.
 280  * Every event and to-do has to belong to a calendar book.
 281  * There are three built-in calendar books.
 282  * <table>
 283  * <caption> Table: Calendar books </caption>
 284  * <tr>
 285  *  <td> DEFAULT_EVENT_CALENDAR_BOOK_ID </td>
 286  *  <td> Event book </td>
 287  * </tr>
 288  * <tr>
 289  *  <td> DEFAULT_TODO_CALENDAR_BOOK_ID </td>
 290  *  <td> Todo book </td>
 291  * </tr>
 292  * <tr>
 293  *  <td> DEFAULT_BIRTHDAY_CALENDAR_BOOK_ID </td>
 294  *  <td> Birthday book </td>
 295  * </tr>
 296  * </table>
 297  * There is an example how calendar book id is set.
 298  *
 299  * @code
 300  * calendar_record_h event = NULL;
 301  *
 302  * calendar_record_create(_calendar_event._uri, &event);
 303  *
 304  * // Set default calendar book ID
 305  * calendar_record_set_int(event, _calendar_event.calendar_id, DEFAULT_EVENT_CALENDAR_BOOK_ID);
 306  *
 307  * // Set other fields
 308  *
 309  * int event_id = 0;
 310  * calendar_db_insert_record(event &event_id);
 311  *
 312  * // Destroy
 313  * calendar_record_destroy(event, true);
 314  * @endcode
 315  *
 316  * To receive a list of existing calendar books, use the following:
 317  *
 318  * @code
 319  * calendar_list_h calendar_book_list = NULL;
 320  * calendar_db_get_all_records(_calendar_calendar_book._uri, 0, 0, &calendar_book_list);
 321  * @endcode
 322  *
 323  * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Events_and_instances Events and Instances
 324  * Two important concepts are event and instance. An event record describes
 325  * various properties of the event, like description, categories, priority
 326  * and many others. It also contains information on when the event takes place,
 327  * there can be more than one instance of the event. Each instance has its
 328  * corresponding instance record. <br>
 329  * If event is inserted with rrule, alarm and attendee, its data is saved to each database.
 330  * Generated instances based on rrule are also stored in instance database.
 331  *
 332  * @image html view_db.png "Figure: Views and databases"
 333  * For example, if an event has the following properties:
 334  * <table>
 335  * <caption> Table: Event and instance example </caption>
 336  * <tr>
 337  *      <th> event </th>
 338  *      <th> instances </th>
 339  * </tr>
 340  * <tr>
 341  *      <td>
 342  *              start date on 2012-10-09 (Tuesday) <br>
 343  *              frequency set to 'WEEKLY' <br>
 344  *              interval set to 1 <br>
 345  *              count set to 3
 346  * </td>
 347  *      <td>
 348  *              2012-10-09 Tuesday <br>
 349  *              2012-10-16 Tuesday <br>
 350  *              2012-10-23 Tuesday
 351  *      </td>
 352  * </tr>
 353  * </table>
 354  * Interval is a multiplier of frequency, which means that if it is set to N,
 355  * instances occur every N weeks (or whatever was set in frequency attribute).
 356  * The recurrence model in Calendar API is compliant with iCalendar specification
 357  * (<a href="http://www.ietf.org/rfc/rfc2445.txt">www.ietf.org/rfc/rfc2445.txt</a>).
 358  * The following event properties have the same functionality as their corresponding
 359  * values in iCalendar:
 360  * <table>
 361  * <caption> Table: Recurrence rules. </caption>
 362  * <tr>
 363  *      <th> Recurrence rule property </th>
 364  *      <th> comment </th>
 365  * </tr>
 366  * <tr>
 367  *      <td> freq </td>
 368  *      <td> Yearly, monthly, weekly, daily </td>
 369  * </tr>
 370  * <tr>
 371  *      <td> count </td>
 372  *      <td> Until count. If count is 3, 3 instances are generated </td>
 373  * </tr>
 374  * <tr>
 375  *      <td> interval </td>
 376  *      <td> The interval is positive integer representing how often the recurrence rule repeats </td>
 377  * </tr>
 378  * <tr>
 379  *      <td> byday </td>
 380  *      <td> MO, TU, WE, TH, FR, SA, SU </td>
 381  * </tr>
 382  * <tr>
 383  *      <td> bymonthday </td>
 384  *      <td> Days of month </td>
 385  * </tr>
 386  * <tr>
 387  *      <td> byyearday </td>
 388  *      <td> Days of year </td>
 389  * </tr>
 390  * <tr>
 391  *      <td> byweekno </td>
 392  *      <td> Ordinals specifying weeks of the year </td>
 393  * </tr>
 394  * <tr>
 395  *      <td> bymonth </td>
 396  *      <td> Months of year </td>
 397  * </tr>
 398  * <tr>
 399  *      <td> bysetpos </td>
 400  *      <td> Values which corresponds to the nth occurrence within the set of events </td>
 401  * </tr>
 402  * <tr>
 403  *      <td> wkst </td>
 404  *      <td> The day on which the workweek starts </td>
 405  * </tr>
 406  * </table>
 407  *
 408  * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Events_and_instances_Exceptions Exceptions
 409  * If one of instances is modified in summary, date… or deleted, this is called exception.<br>
 410  * For example, if 2nd instance date is modified from 16th to 17th, 17th is the exception.
 411  * <table>
 412  * <caption> Table: Exception example </caption>
 413  * <tr>
 414  *      <th> event </th>
 415  *      <th> instances </th>
 416  *      <th> exceptions </th>
 417  * </tr>
 418  * <tr>
 419  *      <td>
 420  *              start date on 2012-10-09 (Tuesday) <br>
 421  *              frequency set to 'WEEKLY' <br>
 422  *              interval set to 1 <br>
 423  *              count set to 3
 424  * </td>
 425  *      <td>
 426  *              2012-10-09 Tuesday <br>
 427  *              2012-10-23 Tuesday
 428  *      </td>
 429  *  <td>
 430  *              2012-10-17 Tuesday <br>
 431  *  </td>
 432  * </tr>
 433  * </table>
 434  * 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.
 435  *
 436  * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Calendar_time_structure Calendar Time Structure
 437  * The calendar time structure, calendar_caltime_s, is defined as follows:
 438  *
 439  * @code
 440  * struct calendar_time_s;
 441  * {
 442  *     calendar_time_type_e type;
 443  *     union {
 444  *         long long int utime;
 445  *         struct {
 446  *             int year;
 447  *             int month;
 448  *             int mday;
 449  *         } date;
 450  *     } time;
 451  * }
 452  * typedef struct calendar_time_s;
 453  * @endcode
 454  *
 455  * The structure should be used when setting the calendar time type
 456  * (_CALENDAR_PROPERTY_CALTIME) properties of records.
 457  * It can hold two types of data: UTC time (long long int) and date,
 458  * given as year, month and day of the month (three integers). These types
 459  * are identified by values of calendar_time_type_e, which are CALENDAR_TIME_UTIME
 460  * and CALENDAR_TIME_LOCALTIME, respectively. The data type determines the usage
 461  * of the structure.
 462  * <table>
 463  * <caption> Table: Data types </caption>
 464  * <tr>
 465  *     <th> Identifier </th>
 466  *     <th> Type </th>
 467  *     <th> Name </th>
 468  *     <th> Purpose </th>
 469  * </tr>
 470  * <tr>
 471  *     <td> CALENDAR_TIME_UTIME </td>
 472  *     <td> long long int </td>
 473  *     <td> utime </td>
 474  *     <td> UTC time, used to describe non-all-day events </td>
 475  * </tr>
 476  * <tr>
 477  *     <td> CALENDAR_TIME_LOCALTIME </td>
 478  *     <td> struct </td>
 479  *     <td> date </td>
 480  *     <td> date only (year, month and day of the month), used to describe all day events </td>
 481  * </tr>
 482  * </table>
 483  *
 484  * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Calendar_time_structure_UTC_time_usage UTC Time Usage
 485  * Structures with UTC time should be used for non-all-day events.
 486  * In such cases, the API user should convert local time to UTC time. The local
 487  * time zone identifier should be stored in the record, in the corresponding
 488  * property.
 489  * For example, when setting starting time of an event, the local
 490  * time zone should be stored in start_tzid.
 491  * When converting local time to UTC time, the function below can be useful.
 492  * The function converts the given date and time to the corresponding
 493  * UTC time, considering the given time zone (first argument).
 494  *
 495  * @code
 496  * #define ms2sec(ms) (long long int)(ms / 1000.0)
 497  *
 498  * long long int
 499  * _time_convert_itol(char *tzid, int y, int mon, int d, int h, int min, int s)
 500  * {
 501  *     int ret = 0;
 502  *     i18n_uchar utf16_timezone[CAL_STR_SHORT_LEN64] = {0};
 503  *     i18n_ustring_copy_ua_n(utf16_timezone, tzid, sizeof(utf16_timezone)/sizeof(i18n_uchar));
 504  *
 505  *     i18n_ucalendar_h ucal = NULL;
 506  *     char *loc_default = NULL;
 507  *     i18n_ulocale_get_default((const char **)&loc_default);
 508  *     ret = i18n_ucalendar_create(utf16_timezone, -1, loc_default, I18N_UCALENDAR_GREGORIAN, &ucal);
 509  *     if (I18N_ERROR_NONE != ret) {
 510  *                 dlog_print(DLOG_DEBUG, LOG_TAG, "i18n_ucalendar_create() Fail (%d)\n", ret);
 511  *
 512  *         return -1;
 513  *     }
 514  *
 515  *     i18n_ucalendar_set_date_time(ucal, y, mon - 1, d, h, min, s);
 516  *
 517  *     i18n_udate date;
 518  *     ret = i18n_ucalendar_get_millisecond(ucal, &date);
 519  *     if (I18N_ERROR_NONE != ret) {
 520  *         dlog_print(DLOG_DEBUG, LOG_TAG, "i18n_ucalendar_create() Fail (%d)\n", ret);
 521  *         i18n_ucalendar_destroy(ucal);
 522  *
 523  *         return -1;
 524  *     }
 525  *     i18n_ucalendar_destroy(ucal);
 526  *
 527  *     return ms2sec(date);
 528  * }
 529  * @endcode
 530  *
 531  * Sample code:<br>
 532  * @code
 533  * // Fill calendar time structures (start and end time)
 534  * calendar_time_s st = {0};
 535  * calendar_time_s et = {0};
 536  *
 537  * st.type = CALENDAR_TIME_UTIME;
 538  * st.time.utime = _time_convert_itol("Asia/Seoul", 2012, 9, 15, 11, 0, 0);
 539  *
 540  * et.type = CALENDAR_TIME_UTIME;
 541  * et.time.utime = _time_convert_itol("Asia/Seoul", 2012, 9, 15, 12, 0, 0);
 542  *
 543  * // Create an event record
 544  *
 545  * // Set local time zone of start time
 546  * calendar_record_set_str(event, _calendar_event.start_tzid, "Asia/Seoul");
 547  *
 548  * // Set start time
 549  * calendar_record_set_caltime(event, _calendar_event.start_time, st);
 550  *
 551  * // Set local time zone of end time
 552  * calendar_record_set_str(event, _calendar_event.end_tzid, "Asia/Seoul");
 553  *
 554  * // Set end time
 555  * calendar_record_set_caltime(event, _calendar_event.end_time, et);
 556  * @endcode
 557  *
 558  * @subsection CAPI_SOCIAL_CALENDAR_SVC_MODULE_Calendar_time_structure_Date_usage Date Usage
 559  * Another usage of time structure is an all day event.
 560  * In case of such events, the structure's type field MUST be set to CALENDAR_TIME_LOCALTIME.
 561  * Only the date (no time) will be stored. Such structures can be used to set start and end time of an event. <br>
 562  * Both start and end time of the event MUST be set.
 563  * The end date value MUST be later in time than the value of the start date.
 564  *
 565  * @code
 566  * // Range is 2 days: 2014/02/17 00:00:00 ~ 2014/02/19 00:00:00
 567  *
 568  * calendar_time_s st = {0};
 569  * st.type = CALENDAR_TIME_LOCALTIME;
 570  * st.time.date.year = 2014;
 571  * st.time.date.month = 2;
 572  * st.time.date.mday = 17;
 573  *
 574  * calendar_time_s et = {0};
 575  * et.type = CALENDAR_TIME_LOCALTIME;
 576  * et.time.date.year = 2014;
 577  * et.time.date.month = 2;
 578  * et.time.date.mday = 19;
 579  *
 580  * // Create an event record
 581  * @endcode
 582  *
 583  * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Creating_a_recurring_event Recurring Events
 584  * To create a recurring event in Calendar API, you MUST set frequency.
 585  * There is a sample code how to create recurring event. Firstly, set start and end time.
 586  *
 587  * @code
 588  * calendar_time_s st = {0};
 589  * st.type = CALENDAR_TIME_UTIME;
 590  * st.time.utime = _time_convert_itol("Asia/Seoul", 2012, 9, 15, 11, 0, 0);
 591  *
 592  * calendar_time_s et = {0};
 593  * et.type = CALENDAR_TIME_UTIME;
 594  * et.time.utime = _time_convert_itol("Asia/Seoul", 2012, 9, 15, 12, 0, 0);
 595  * @endcode
 596  *
 597  * Then, the remaining properties should be set.
 598  * Each frequency needs other proper fields except daily event.
 599  * If other values are not inserted, these values are calculated based on start time.
 600  * <table>
 601  * <caption> Table: Frequency properties </caption>
 602  * <tr>
 603  *  <th> Freq </th>
 604  *  <th> Property </th>
 605  *  <th> Comment </th>
 606  * </tr>
 607  * <tr>
 608  *  <td> CALENDAR_RECURRENCE_YEARLY </td>
 609  *  <td> byyearday </td>
 610  *  <td> Every 100th day </td>
 611  * </tr>
 612  * <tr>
 613  *  <td> </td>
 614  *  <td> byweekno </td>
 615  *  <td> Every 34th week </td>
 616  * </tr>
 617  * <tr>
 618  *  <td> </td>
 619  *  <td> bymonthday </td>
 620  *  <td> Every 1st February (birthday)</td>
 621  * </tr>
 622  * <tr>
 623  *  <td> </td>
 624  *  <td> byday </td>
 625  *  <td> Every 1st Monday of May (holiday) </td>
 626  * </tr>
 627  * <tr>
 628  *  <td> CALENDAR_RECURRENCE_MONTHLY </td>
 629  *  <td> bymonthday </td>
 630  *  <td> Every 29th (payday) </td>
 631  * </tr>
 632  * <tr>
 633  *  <td> </td>
 634  *  <td> byday </td>
 635  *  <td> Every last Friday </td>
 636  * </tr>
 637  * <tr>
 638  *  <td> CALENDAR_RECURRENCE_WEEKLY </td>
 639  *  <td> byday </td>
 640  *  <td> Every week </td>
 641  * </tr>
 642  * <tr>
 643  *  <td> CALENDAR_RECURRENCE_DAILY </td>
 644  *  <td> - </td>
 645  *  <td> - </td>
 646  * </tr>
 647  * </table>
 648  * If byday is not set in weekly event, default byday is followed start day of week.
 649  * By the same token, default interval is 1 and default range type is endless.
 650  * <table>
 651  * <caption> Table: Range types </caption>
 652  * <tr>
 653  *  <th> Range type </th>
 654  *  <th> Comment </th>
 655  * </tr>
 656  * <tr>
 657  *  <td> CALENDAR_RANGE_NONE </td>
 658  *  <td> Endless(max date is 2036/12/31) </td>
 659  * </tr>
 660  * <tr>
 661  *  <td> CALENDAR_RANGE_UNTIL </td>
 662  *  <td> Should set until property </td>
 663  * </tr>
 664  * <tr>
 665  *  <td> CALENDAR_RANGE_COUNT </td>
 666  *  <td> Should set count property </td>
 667  * </tr>
 668  * </table>
 669  *
 670  * @code
 671  * calendar_record_h event;
 672  * calendar_record_create(_calendar_event._uri, &event);
 673  *
 674  * calendar_record_set_str(event, _calendar_event.start_tzid, "Asia/Seoul");
 675  * calendar_record_set_caltime(event, _calendar_event.start_time, st);
 676  * calendar_record_set_str(event, _calendar_event.end_tzid, "Asia/Seoul");
 677  * calendar_record_set_caltime(event, _calendar_event.end_time, et);
 678  *
 679  * calendar_record_set_int(event, _calendar_event.freq, CALENDAR_RECURRENCE_WEEKLY);
 680  * calendar_record_set_int(event, _calendar_event.interval, 1)
 681  * calendar_record_set_int(event, _calendar_event.count, 3);
 682  * @endcode
 683  *
 684  * The last step is inserting the event into the database.
 685  * Records representing instances of the event are created when the event record is inserted.
 686  *
 687  * @code
 688  * int event_id = 0;
 689  * calendar_db_insert_record(event, &event_id);
 690  *
 691  * calendar_record_destroy(event, true);
 692  * @endcode
 693  *
 694  *
 695  * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Filters_and_queries Filters and Queries
 696  * Queries are used to retrieve data which satisfies given criteria, like an integer
 697  * property being greater than a given value, or a string property containing a given substring.
 698  * The criteria are defined by creating filters and adding conditions to them, joining them
 699  * with logical operators. Also, instead of a condition, another filter can be added,
 700  * which can be used to create more complex filters.
 701  * Operator precedence in filters determined by the order in which the
 702  * conditions and filters are added.
 703  * When a filter is ready, it can be set as a property of a query.
 704  * Other query properties allow configuring how the returned results
 705  * are grouped and sorted.
 706  * Operator precedence in filters is determined by the order in which the
 707  * conditions and filters are added are added.
 708  * For example, if the following sequence is added:
 709  * <table>
 710  * <caption> Table: Filter and conditions </caption>
 711  * <tr>
 712  *      <th> Filter with conditions </th>
 713  *      <th> Result </th>
 714  * </tr>
 715  * <tr>
 716  *      <td>
 717  *              Contidion C1 <br>
 718  *              OR <br>
 719  *              Contidion C2 <br>
 720  *              AND <br>
 721  *              Condition C3
 722  *      </td>
 723  *      <td> (C1 OR C2) AND C3 </td>
 724  * </tr>
 725  * <tr>
 726  *      <td>
 727  *              Filter F1: <br>
 728  *                      Condition C1 <br>
 729  *                      OR <br>
 730  *                      Condition C2 <br><br>
 731  *              Filter F2: <br>
 732  *                      Condition C3 <br>
 733  *                      OR <br>
 734  *                      Condition C4 <br><br>
 735  *              Filter F3: <br>
 736  *                      Condition C5 <br>
 737  *                      AND <br>
 738  *                      F1 <br>
 739  *                      AND <br>
 740  *                      F2
 741  *      </td>
 742  *      <td>
 743  *              (C5 AND F1) AND F2 <br>
 744  *              Which is: <br>
 745  *              (C5 AND (C1 OR C2)) AND (C3 OR C4)
 746  *      </td>
 747  * </tr>
 748  * </table>
 749  * The following code creates a filter, accepting events with high priority
 750  * or those that include the word "meeting" in their description.
 751  *
 752  * @code
 753  * calendar_filter_h filter = NULL;
 754  *
 755  * // Create a filter returning event type records
 756  * calendar_filter_create(_calendar_event._uri, &filter);
 757  *
 758  * // Add 'priority equals high' condition
 759  * calendar_filter_add_int(filter, _calendar_event.priority, CALENDAR_MATCH_EQUAL, CALENDAR_EVENT_PRIORITY_HIGH);
 760  *
 761  * // Add OR operator
 762  * calendar_filter_add_operator(filter, CALENDAR_FILTER_OPERATOR_OR);
 763  *
 764  * // Add 'description contains "meeting"' condition
 765  * calendar_filter_add_str(filter, _calendar_event.description, CALENDAR_MATCH_CONTAINS, "meeting");
 766  * @endcode
 767  *
 768  * The filter should be inserted into a query and the query should be executed:
 769  *
 770  * @code
 771  * calendar_query_h query = NULL;
 772  * calendar_list_h list = NULL;
 773  *
 774  * // Create a query returning event type records
 775  * calendar_query_create(_calendar_event._uri, &query);
 776  *
 777  * // Add the filter
 778  * calendar_query_set_filter(query, filter);
 779  *
 780  * // Execute the query, results are returned in a list
 781  * calendar_db_get_records_with_query(query, 0, 0, &list);
 782  *
 783  * calendar_filter_destroy(filter);
 784  * calendar_query_destroy(query);
 785  *
 786  * // Use the list
 787  *
 788  * calendar_list_destroy(list, true);
 789  * @endcode
 790  *
 791  *
 792  * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Projections Projections
 793  * Useful concept in Calendar service APIs is projection, related to searching with filters and queries.
 794  * Projection allows you to query the Data for just those specific properties of a record that you actually need, at lower latency
 795  * and cost than retrieving the entire properties.
 796  * Sample code:<br>
 797  * create filter which will get event id, summary and start time from the record with its summary has “test” (string filter).
 798  * Create a query and add the filter to it. Results are received in a list.
 799  *
 800  * @code
 801  * calendar_query_h query = NULL;
 802  * calendar_filter_h filter = NULL;
 803  *
 804  * // Set query with filter
 805  * calendar_query_create(_calendar_event_calendar_book_attendee._uri, &query);
 806  * calendar_filter_create(_calendar_event_calendar_book_attendee._uri, &filter);
 807  * calendar_filter_add_str(filter, _calendar_event.summary, CALENDAR_MATCH_CONTAINS, "test");
 808  * calendar_query_set_filter(query, filter);
 809  *
 810  * // Set projection
 811  * unsigned int projection[3];
 812  * projection[0]=_calendar_event_calendar_book_attendee.event_id;
 813  * projection[1]=_calendar_event_calendar_book_attendee.summary;
 814  * projection[2]=_calendar_event_calendar_book_attendee.start_time;
 815  *
 816  * // Get list
 817  * calendar_query_set_projection(query, projection, 3);
 818  * calendar_db_get_records_with_query(query, 0, 0, &list);
 819  *
 820  * // Destroy handle
 821  * calendar_filter_destroy(filter);
 822  * calendar_query_destroy(query);
 823  * calendar_list_destroy(list, true);
 824  * @endcode
 825  *
 826  * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Reminders Reminders
 827  * Alarm and reminder is the similar terminology but reminder is used as package name storages, shown in below figure 5.
 828  * When alarm alerts, calendar-service sends notification to all packages which is registered in reminder DB table with calendar_reminder_add_receiver().
 829  * This shows how to set alarm and how alarm works.
 830  *
 831  * @image html alarm_process.png "Figure: Alarm process"
 832  * After adding receiver, registered alarm would be alerted on reserved time by inserting alarm as child.
 833  * <table>
 834  * <caption> Table: Alarm fields </caption>
 835  * <tr>
 836  *      <th> tick_unit </th>
 837  *      <th> related field </th>
 838  *      <th> comment </th>
 839  * </tr>
 840  * <tr>
 841  *      <td> CALENDAR_ALARM_TIME_UNIT_SPECIFIC </td>
 842  *      <td> time </td>
 843  *      <td> This represents the number of seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC) </td>
 844  * </tr>
 845  * <tr>
 846  *      <td> CALENDAR_ALARM_TIME_UNIT_WEEK </td>
 847  *      <td> tick </td>
 848  *      <td> The number of weeks before start time </td>
 849  * </tr>
 850  * <tr>
 851  *      <td> CALENDAR_ALARM_TIME_UNIT_DAY </td>
 852  *      <td> tick </td>
 853  *      <td> The number of days before start time </td>
 854  * </tr>
 855  * <tr>
 856  *      <td> CALENDAR_ALARM_TIME_UNIT_HOUR </td>
 857  *      <td> tick </td>
 858  *      <td> The number of hours before start time </td>
 859  * </tr>
 860  * <tr>
 861  *      <td> CALENDAR_ALARM_TIME_UNIT_MINUTE </td>
 862  *      <td> tick </td>
 863  *      <td> The number of minutes before start time </td>
 864  * </tr>
 865  * </table>
 866  * Below example shows the alarm which is set 1 minute before start time.
 867  *
 868  * @code
 869  * // Set alarm with normal unit
 870  * calendar_record_h alarm = NULL;
 871  * calendar_record_create(_calendar_alarm._uri, &alarm);
 872  * calendar_record_set_int(alarm, _calendar_alarm.tick_unit, CALENDAR_ALARM_TIME_UNIT_MINUTE);
 873  * calendar_record_set_int(alarm, _calendar_alarm.tick, 1); // Before 1 min (60 secs)
 874  *
 875  * // Add alarm as child
 876  * calendar_record_add_child_record(event, _calendar_event.calendar_alarm, alarm);
 877  * @endcode
 878  *
 879  * With CALENDAR_ALARM_TIME_UNIT_SPECIFIC, the alarm could be set regardless of the start time.
 880  *
 881  * @code
 882  * // Set alarm with specific unit
 883  * calendar_record_h alarm = NULL;
 884  * calendar_record_create(_calendar_alarm._uri, &alarm);
 885  * calendar_record_set_int(alarm, _calendar_alarm.tick_unit, CALENDAR_ALARM_TIME_UNIT_SPECIFIC);
 886  * // Suppose start time is 1404036000 (Sun, 29 Jun 2014 10:00:00 GMT) and alarm is set 60 secs after from start time
 887  * calendar_time_s ct;
 888  * ct.type = CALENDAR_TIME_UTIME;
 889  * ct.time.utime = 1404036000 + 60;
 890  * calendar_record_set_caltime(alarm, _calendar_alarm.alarm_time, ct);
 891  *
 892  * // Add alarm as child
 893  * calendar_record_add_child_record(event, _calendar_event.calendar_alarm, alarm);
 894  * @endcode
 895  *
 896  * How to register package as reminder.
 897  * In manifest.xml file, below code must be inserted.
 898  *
 899  * @code
 900  * <app-control>
 901  *    <operation name="http://tizen.org/appcontrol/operation/view"/>
 902  *    <mime name="application/x-tizen.calendar.reminder"/>
 903  * </app-control>
 904  * @endcode
 905  *
 906  * When alarm alerts, calendar-service sends data with key, value pairs.<br>
 907  * With "ids" key, id array could be get.<br>
 908  * Each detail value could be get with "each id" key.<br>
 909  * The detail data is the combination of alarm values. id, time, tick, unit and type is connected with "&" charater.<br>
 910  * ex> id=64&time=1415106300&tick=0&unit=60&type=0
 911  *
 912  * @code
 913  * // "ids" string is the key, to get id array
 914  * char **ids = NULL;
 915  * int len = 0;
 916  * app_control_get_extra_data_array(b, "ids", &ids, &len);
 917  *
 918  * int i = 0;
 919  * for (i = 0; i < len; i++) {
 920  *         // "id" is the key to get detail value
 921  *         char *value = NULL;
 922  *         app_control_get_extra_data(b, ids[i], &value);
 923  *         if (NULL == value)
 924  *                 continue;
 925  *
 926  *         // Parse detail data
 927  *
 928  *         // Free
 929  *         free(ids[i]);
 930  *         ids[i] = NULL;
 931  * }
 932  *
 933  * free(ids);
 934  * @endcode
 935  *
 936  * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Db_change_noties Database Change Notifications
 937  * Applications add/remove callback function to detect/ignore the calendar DB changes
 938  * with calendar_db_add_changed_cb() / calendar_db_remove_changed_cb(). <br>
 939  * Clients await calendar change notification on client side.
 940  * If calendar is changed by another module, server publishes inotify event. Inotify module broadcasts to subscribe modules.
 941  * Internal inotify handler is called at client side. User callback function is called with user data.
 942  *
 943  * @code
 944  * // Add callback function
 945  * void __event_changed_cb(const char *view_uri, void *user_data) {}
 946  * // Add changed noti callback
 947  * calendar_db_add_changed_cb(_calendar_event._uri, __event_changed_cb, NULL);
 948  * @endcode
 949  *
 950  * @section CAPI_SOCIAL_CALENDAR_SVC_MODULE_Vcalendar Vcalendar
 951  * To exchange of personal calendaring and scheduling information, vcalendar is used.
 952  * In order to avoid confusion with this referenced work, this is to be known as the vcalendar specification.
 953  * Vcalendar ver2.0 is known as icalendar.
 954  * <table>
 955  * <caption> Table: Vcalendar example ( http://www.ietf.org/rfc/rfc2445.txt ) </caption>
 956  * <tr>
 957  *  <td>
 958  *      BEGIN:VCALENDAR<br>
 959  *      VERSION:2.0<br>
 960  *      PRODID:-//hacksw/handcal//NONSGML v1.0//EN<br>
 961  *      BEGIN:VEVENT<br>
 962  *      DTSTART:19970714T170000Z<br>
 963  *      DTEND:19970715T035959Z<br>
 964  *      SUMMARY:Bastille Day Party<br>
 965  *      END:VEVENT<br>
 966  *      END:VCALENDAR<br>
 967  *  </td>
 968  * </tr>
 969  * </table>
 970  * Calendar service provides APIs to compose vcalendar stream.
 971  * With stream, file could be made or data could be transmitted with json data.
 972  *
 973  * @code
 974  * calendar_list_h list = NULL;
 975  * // Create or get list to make vcalendar stream
 976  *
 977  * char *stream = NULL;
 978  * calendar_vcalendar_make_from_records(list, &stream);
 979  *
 980  * // Jobs for stream
 981  *
 982  * // Free
 983  * free(stream);
 984  * @endcode
 985  *
 986  * Vcalendar could be parsed with calendar service APIs as well.
 987  *
 988  * @code
 989  * // Read stream from file
 990  *
 991  * calendar_list_h list = NULL;
 992  * calendar_vcalendar_parse_to_calendar(stream, &list);
 993  *
 994  * // Jobs for list
 995  * calendar_list_destroy(list, true);
 996  * @endcode
 997  */
 998
 999
1000 /**
1001  * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
1002  * @defgroup CAPI_SOCIAL_CALENDAR_SVC_DATABASE_MODULE Database
1003  * @brief The calendar database API provides the set of the definitions and interfaces that enable you to handle calendar database.
1004  * @section CAPI_SOCIAL_CALENDAR_SVC_DATABASE_MODULE_HEADER Required Header
1005  * \#include <calendar.h>
1006  * <BR>
1007  */
1008
1009
1010 /**
1011  * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
1012  * @defgroup CAPI_SOCIAL_CALENDAR_SVC_FILTER_MODULE Filter
1013  * @brief The calendar filter API provides the set of the definitions and interfaces that enable you to handle filter.
1014  * @section CAPI_SOCIAL_CALENDAR_SVC_FILTER_MODULE_HEADER Required Header
1015  * \#include <calendar.h>
1016  * <BR>
1017  */
1018
1019
1020 /**
1021  * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
1022  * @defgroup CAPI_SOCIAL_CALENDAR_SVC_LIST_MODULE List
1023  * @brief The calendar list API provides the set of the definitions and interfaces that enable you to handle list.
1024  * @section CAPI_SOCIAL_CALENDAR_SVC_LIST_MODULE_HEADER Required Header
1025  * \#include <calendar.h>
1026  * <BR>
1027  */
1028
1029
1030 /**
1031  * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
1032  * @defgroup CAPI_SOCIAL_CALENDAR_SVC_QUERY_MODULE Query
1033  * @brief The calendar query API provides the set of the definitions and interfaces that enable you to handle query.
1034  * @section CAPI_SOCIAL_CALENDAR_SVC_QUERY_MODULE_HEADER Required Header
1035  * \#include <calendar.h>
1036  * <BR>
1037  */
1038
1039
1040 /**
1041  * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
1042  * @defgroup CAPI_SOCIAL_CALENDAR_SVC_RECORD_MODULE Record
1043  * @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.
1044  * @section CAPI_SOCIAL_CALENDAR_SVC_RECORD_MODULE_HEADER Required Header
1045  *  \#include <calendar.h>
1046  * <BR>
1047  */
1048
1049
1050 /**
1051  * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
1052  * @defgroup CAPI_SOCIAL_CALENDAR_SVC_REMINDER_MODULE Reminder
1053  * @brief The calendar reminder API provides the interface to set/unset reminder callback.
1054  * @section CAPI_SOCIAL_CALENDAR_SVC_REMINDER_MODULE_HEADER Required Header
1055  * \#include <calendar.h>
1056  * <BR>
1057  */
1058
1059
1060 /**
1061  * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
1062  * @defgroup CAPI_SOCIAL_CALENDAR_SVC_VCALENDAR_MODULE vCalendar
1063  * @brief The calendar vcalendar API provides the set of the definitions and interfaces that enable you to get/set data from/to vCalendar.
1064  * @section CAPI_SOCIAL_CALENDAR_SVC_VCALENDAR_MODULE_HEADER Required Header
1065  * \#include <calendar.h>
1066  * <BR>
1067  */
1068
1069
1070 /**
1071  * @ingroup CAPI_SOCIAL_CALENDAR_SVC_MODULE
1072  * @defgroup CAPI_SOCIAL_CALENDAR_SVC_VIEW_MODULE View/Property
1073  * @brief This page provides information about views with properties.
1074  * @section CAPI_SOCIAL_CALENDAR_SVC_VIEW_MODULE_OVERVIEW Overview
1075  * A view is a structure which describes properties of a record.
1076  * A record can have basic properties of four types: integer, string, long integer. Each property
1077  * of basic type has functions to operate on it:
1078  * <table>
1079  * <tr>
1080  *     <th> Property </th>
1081  *     <th> Setter </th>
1082  *     <th> Getter </th>
1083  * </tr>
1084  * <tr>
1085  *     <td> integer </td>
1086  *     <td> calendar_record_set_int </td>
1087  *     <td> calendar_record_get_int </td>
1088  * </tr>
1089  * <tr>
1090  *     <td> long long integer </td>
1091  *     <td> calendar_record_set_lli </td>
1092  *     <td> calendar_record_get_lli </td>
1093  * </tr>
1094  * <tr>
1095  *     <td> double </td>
1096  *     <td> calendar_record_set_double </td>
1097  *     <td> calendar_record_get_double </td>
1098  * </tr>
1099  * <tr>
1100  *     <td> string </td>
1101  *     <td> calendar_record_set_str </td>
1102  *     <td> calendar_record_get_str </td>
1103  * </tr>
1104  * <tr>
1105  *     <td> calendar_time_s </td>
1106  *     <td> calendar_record_set_caltime </td>
1107  *     <td> calendar_record_get_caltime </td>
1108  * </tr>
1109  * </table>
1110  * For long long integer functions, "lli" stands for long long int, ususally used to hold UTC time.
1111  * Below you can find tables with view properties.
1112  * Properties of type 'record' are other records. For example, the @ref CAPI_SOCIAL_CALENDAR_SVC_VIEW_MODULE_calendar_event
1113  * 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)
1114  * can be children of the event record. If a name record holds the identifier
1115  * of a event record in its 'event_id' property, it is the child record of the corresponding
1116  * event record.
1117  * Records can have many children of a given type.
1118  * Please refer to the main section of Calendar API for a more detailed explanation and examples.
1119  * @section CAPI_SOCIAL_CALENDAR_SVC_VIEW_MODULE_HEADER Required Header
1120  * \#include <calendar.h>
1121  */
1122
1123
1124 #endif /* __TIZEN_SOCIAL_CALENDAR_DOC_H__ */