Accessing and managing calendar information

The Calendar Service API allows Flash Lite applications to access, create, and manage calendars and calendar entries stored on a device. You can use the Calendar Service to create Flash Lite applications 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

For example code snippets that focus on common Calendar Service use cases, see section Flash Lite components and code snippets.

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 calender = new Service("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.

© Nokia 2009.