Calendar API

Similar to the addressbook API, the calendar API supports most of the fields specified by the vCalendar in IETF RFC 2445. The calendar API supports two classes analogous to those in the addressbook API.

The following code snippet shows a vCalendar entry:

BEGIN:VCALENDAR
VERSION:2.0
PRODID:-//hacksw/handcal//NONSGML v1.0//EN
BEGIN:VEVENT
DTSTART:19970714T170000Z
DTEND:19970715T035959Z
SUMMARY:Bastille Day Party
END:VEVENT
END:VCALENDAR

As you can see, the format is very similar to the vCard format used in the addressbook API.

The calendar API supports two interfaces analogous to those in the addressbook API (one interface extending the PIMElement interface and one interface derived from the PIMList interface, providing access to an event database).

Here the corresponding interfaces are the Event interface for a particular element and the EventList interface, providing the necessary methods to access an event database.

Contacts and Events support different field IDs. The calendar API supports two interfaces analogous to those in the addressbook API (one interface extending the PIMElement interface and one interface derived from the PIMList interface, providing access to an event database).

Here the corresponding interfaces are the Event interface for a particular element and the EventList interface, providing the necessary methods to access an event database.

Repetition of Events

The EventRepeat class is an encapsulation of the RRULE field in a vCalendar element. It is used to determine how often an event occurs. The repetition details of the event are set using the setInt() method, taking a field ID and an int value as parameter. The valid parameter combinations are shown in Table 7.3. Additionally, an end date for the repetition can be set using the setDate() method, taking the END field constant and a valid date as parameters.

The following snippet shows how a repeat pattern is added to an event:

EventList myEvents = PIM.openEventList(PIM.READ_WRITE);
Event myEvent = myEvents.createEvent();

Date startDate = new Date();
myEvent.setString(Event.SUMMARY, "Weekly developer meeting.");
myEvent.setDate(Event.START, startDate);
myEvent.setDate(Event.ALARM, new Date(startDate.getTime() - 60000));
EventRepeat repeat = new EventRepeat();
repeat.setInt(EventRepeat. DAY_IN_WEEK, EventRepeat.MONDAY);

myEvent.setRepeat(repeat);

myEvent.commit ();
myEvents.close();

In the following section, we will describe the list related calls used in this code snippet in more detail.

EventLists for Handling Events

For access to the event database, the PIM class provides openEventList() and listEventLists() methods analogous to the methods available for obtaining contact lists. The behavior of those methods is as described in the previous section about contact lists, except that the openEventList() methods both return instances of EventList. Like ContactList, EventList extends the general PIMList interface. In addition to the PIMList functionality, it provides a new elements() method, returning an enumeration containing all Event elements ranging from a start date to a specified end date.