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:

  1. Create a service object for the API using device.getServiceObject().

  2. Define the tasks you want to perform and choose the correct methods for them.

  3. Optionally, define how you want the results filtered.

  4. Define methods for processing the results.

  5. Use the methods defined in step 2 to perform the tasks. Use asynchronous methods together with callback().

  6. 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.

© Nokia 2008.