Calendar databases

The EventList class represents a database containing calendar entries (also known as calendar events) of a specific type. The Event class is used to represent individual calendar entries. You can use EventLists to access the calendar information available on a device.

Series 40 and Symbian devices have at least one calendar available: the default, native calendar stored in device memory. Depending on the device, even more calendars can be available. On Series 40 devices and on Symbian devices with Java Runtime 2.1 for Symbian or earlier, MIDlets can only access the default calendar. On Symbian devices with Java Runtime 2.2 for Symbian or newer, MIDlets can access any calendar available on the device.

The PIM API represents each available calendar as a set of EventLists. Each EventList contains calendar entries of a specific type and carries a predefined name based on that type. The name is the same across calendars. The exact EventList names depend on the platform. Moreover, the names are localized, so the exact names additionally depend on the locale selected on a device. Therefore, never hard-code the names in a MIDlet, but rather obtain them dynamically by using the PIM.listPIMLists method as shown in the instructions below.

Series 40 and Symbian devices support different calendar entry types. Although the exact type names differ from device to device, the types can be abstractly represented as follows:

In Series 40:
- Meeting
- Call
- Birthday
- Memo
- Reminder
In Symbian:
- Meeting
- Memo
- Anniversary

The PIM.listPIMLists method always returns the names in the above order.

Accessing the default calendar

To access the default calendar on a device:

Retrieve the EventList names supported by the device by using the PIM.listPIMLists method:
```
PIM pim = PIM.getInstance();
String[] eventListNames = pim.listPIMLists(PIM.EVENT_LIST);
```
The return value is a string array containing the localized EventList names. The names are returned in the order shown above.
Select what type of calendar entries, that is, which EventList you want to access. You can either force the selection yourself by selecting a specific item from the string array returned by the PIM.listPIMLists method, or you can allow the user to select the type. For example, to select the second item:
```
String eventListName = eventListNames[1];
```
Open the EventList by using the PIM.openPIMList(int pimListType, int mode, String name) method, with the name of the database specified in the name parameter:
```
EventList eventList = (EventList)pim.openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE, eventListName);
```
Use the EventList and Event methods to read and write data from and to the opened EventList.

Accessing a specific calendar

To access a specific calendar among multiple calendars available on a device:

Note: This is only supported on Symbian devices with Java Runtime 2.2 for Symbian or newer.

Retrieve the names of all calendars available on the device by using 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.
Select the name of the database you want to access. You can either force the selection yourself by parsing the name from the string returned by com.nokia.mid.calendars, or you can provide a list of names for the user to choose from. For example, to select the first name contained in the string:
```
String calendarName = calendarNames.substring(0, calendarNames.indexOf(","));
```
Retrieve the EventList names supported by the device by using the PIM.listPIMLists method:
```
PIM pim = PIM.getInstance();
String[] eventListNames = pim.listPIMLists(PIM.EVENT_LIST);
```
The return value is a string array containing the localized EventList names. The names are returned in the order shown above.
Select what type of calendar entries, that is, which EventList you want to access. You can either force the selection yourself by selecting a specific item from the string array returned by the PIM.listPIMLists method, or you can allow the user to select the type. For example, to select the second item:
```
String eventListName = eventListNames[1];
```
Open the EventList for the selected calendar by using the PIM.openPIMList(int pimListType, int mode, String name) method, with the calendar and EventList names specified in the name parameter:
```
String name = calendarName + "/" + eventListName;
EventList eventList = (EventList)pim.openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE, eventListName);
```
Use the EventList and Event methods to read and write data from and to the opened EventList.

More information

For information about managing multiple calendars on a Symbian device, see section Managing multiple calendars.

For information about the supported EventList fields and attributes, see the PIM API implementation notes.

For examples on using the calendar and event list functions on a device, see the following articles in the Nokia Developer Wiki: