Accessing +and managing calendar information

The Calendar +Service API allows widgets to access, create, and manage +calendars and calendar entries stored on a device. You can use the Calendar +Service to create widgets that:

Retrieve information about calendars and calendar entries
+
Create and delete calendars
Create, update, and delete entries for a given calendar
+
Import and export calendar entries
Notify the user when calendar entries are created, updated, +or deleted

Calendar information involves the following concepts:

Calendar stores calendar entries. There can be one +or more calendars on a device, and each calendar corresponds to a single file +in the device file system.
Calendar entries make up the main content of a calendar. +Each entry belongs to one of the following categories:
+ +
- Anniversary
- Event
- Meeting
- Reminder
- To-do item
+
For more information about calendar entries and what they contain, see +section Calendar entries.
+ +
Recurring entry is an entry that has more than one +occurrence. The rules of recurrence must be defined separately for each entry. +Only meetings can be recurring.
Instance is a specific occurrence of a recurring entry. +Instances are not stored separately (as a rule) but calculated dynamically +based on the entry data and rules of recurrence. Non-recurring entries have +only a single instance.
+ +
For example, a weekly meeting that occurs once a week for eight weeks +has eight instances. The meeting entry itself is stored only once in the calendar +file, but a calendar application can show each meeting instance separately.
+ +
Parent entry is any original entry. When a new entry +is added to a calendar, the entry is stored as a parent entry. A recurring +parent entry can have one or more child entries.
Child entry is a modified instance of a recurring +parent entry. When an instance (occurrence) of a recurring entry is explicitly +modified, so that it differs in some way from the parent data, it is stored +as a child entry. A parent entry and its child entries share the same id, +but have unique LocalIds. A child entry always has a +single instance.
+ +
For example, if one of the eight instances of the weekly meeting is +modified to occur at a different time of day than the rest, it is stored as +a child entry. Since it no longer fully conforms to the parent data and cannot +be derived from it, it must be stored as a separate entry.
+ +
Exception is an occurrence in the original schedule +that has been removed and may be replaced with a different occurrence.
+

Accessing the API and supported methods

To create a service +object for the Calendar Service API, use Service.Calendar to +identify the service provider and IDataSource to identify +the supported interface:

+ +

var so = device.getServiceObject("Service.Calendar", "IDataSource");

The IDataSource interface provides the following +methods:

GetList()
+ +
Use the GetList() method to retrieve information +about calendars and calendar entries.
+ +
Add()
+ +
Use the Add() method to create a new calendar or +calendar entry. You can also use this method to update an existing calendar +entry.
+ +
Delete()
+ +
Use the Delete() method to delete a calendar or +one or more entries in a given calendar.
+ +
Import()
+ +
Use the Import() method to import entries into +a calendar. The information must be imported from an iCal or vCal file (see +below).
+ +
Export()
+ +
Use the Export() method to export entries from +a calendar. The information is exported to an iCal or vCal file (see below).
+ +
RequestNotification()
+ +
Use the RequestNotification() method to receive +notifications when entries are created, updated, or deleted in a given calendar.
+ +
Cancel()
+ +
Use the Cancel() method to cancel an ongoing asynchronous +call. This method is valid for any asynchronous call made through the Calendar +Service API.
+ +

iCal and vCal

iCalendar (iCal) is an RFC standard for calendar data exchange. It allows +for the capture and exchange of information normally stored within a calendar +or scheduling application. It allows users to send meeting requests and tasks +to other users through email. Recipients of the iCalendar email can respond +to the sender easily or counter-propose another meeting date and time. For +more information, see the iCalendar +specification (RFC 2445).

vCalendar (vCal) is the precursor of the iCalendar standard. It defines +a format that allows for the capture of information normally stored within +a calendar or scheduling application. The format is suitable as an interchange +format between applications or systems and is intended to be used for exchanging +information about event and to-do types of entities. For more information, +see the vCalendar specification.

Using the service in a widget

To access and manage calendar information using the Calendar Service +API:

Create a service +object for the API using device.getServiceObject().
+
Define the +tasks you want to perform and choose the correct methods for them.
+
Optionally, +define how you want the results filtered.
Define methods +for processing the results.
Use the methods +defined in step 2 to perform the tasks. Use asynchronous methods together +with callback().
+
Process the +results with the methods defined in step 4.

For the complete source of a sample widget that demonstrates how to +use this service, see the +full example.