Managing multiple calendars

Creating calendars

To create a new calendar, call the PIM.openPIMList(int pimListType, int mode, String name) method, and use the name parameter to specify the calendar name and the create operation. The format for the name parameter is:

[calendarName "/"] eventListName ["?operation=create"]

The following code snippet creates a new calendar named "Personal":

// create a PIM class instance
PIM pim = PIM.getInstance();

// specify a) the calendar name and b) that it is to be created
String[] eventListNames = pim.listPIMLists(PIM.EVENT_LIST);
String name = "Personal/" + eventListNames[0] + "?operation=create";

// create the calendar by creating a calendar entry
EventList eventList = (EventList)pim.openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE, name);

// create and commit content for the calendar entry,
// although this is not required for creating the calendar
// ...

// close the calendar entry
eventList.close();

Note the following when creating a new calendar:

• If a calendar with the specified name already exists on the device, a PIMException is thrown with reason code -11.

• If no calendar name is specified, the new entry is added to the device's default calendar.

• If the openPIMList call is successful, it returns an EventList or ToDoList (depending on the entry type) associated with the newly created calendar.

• The following characters cannot be used in a calendar name: <, >, \, /, ", |, :, *, ?

Deleting calendars

To delete an existing calendar, call the PIM.openPIMList(int pimListType, int mode, String name) method, and use the name parameter to specify the calendar name and the delete operation. The format for the name parameter is:

[calendarName "/"] eventListName ["?operation=delete"]

The following code snippet deletes a calendar named "Personal", provided it exists on the device:

// create a PIM class instance
PIM pim = PIM.getInstance();

// specify a) the calendar name and b) that it is to be deleted
String[] eventListNames = pim.listPIMLists(PIM.EVENT_LIST);
String name = "Personal/" + eventListNames[0] + "?operation=delete";

// delete the calendar by creating a dummy calendar entry
EventList eventList = (EventList)pim.openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE, name);

// note that you do not need to close the calendar entry,
// since the returned EventList is already closed

Note the following when creating a new calendar:

• If a calendar with the specified name does not exist on the device, a PIMException is thrown with reason code LIST_NOT_ACCESSIBLE.

• If the specified calendar is the device's default calendar, a PIMException is thrown with reason code -21. The default calendar cannot be deleted.

• If the openPIMList call is successful, it returns a closed and empty EventList or ToDoList (depending on the entry type) associated with no calendar.

Listing available calendars

To determine what calendars are available on the device, use the com.nokia.mid.calendars system property:

String calendarNames = System.getProperty("com.nokia.mid.calendars");

The system property returns the names of all the calendars available on the device. The names are separated by commas.

Managing calendar entries

Managing entries in custom-made calendars is no different from managing entries in the device's default calendar. The PIM API works the same way for each calendar available on the device. For more information, see the following sections:

• Calendar databases

• To-do notes databases

• Class and interface description