Header Sep
print this page
Java Tips, Tricks & Code
 
Score
Login to rate page
Back

October 2005
JSR 75: Accessing the PIM database and File system
Part two: The PIM API

[Back]

DFollowing part one, in this article we will access the phone's native PIM database with the PIM API. This API allows us to alter, remove and add items to the mobile phone's phone book, calendar and task lists.

The Sony Ericsson implementation of the JSR 75 API supports these three types of lists. There are some fields and functionality that are not supported like the RepeatRule class and the use of categories, you can read more about this in the Sony Ericsson MIDP 2.0 Developers' Guidelines>>

At the end of this article there is a example MIDlet that is used to create recurring calendar events, a feature that is missing on some Sony Ericsson phones.

To access the native PIM database we need a PIM object. The PIM object has methods for retrieving the different lists that resides in the PIM database. There are three types of lists in the Sony Ericsson implementation:

  • ToDoList: Tasks  
  • EventList: Calendar
  • ContactList:  The phone book

All of these lists are interfaces and implement the PIMList interface. When having a reference to one of the list, we can list the existing PIMItems, alter, add and remove PIMItems from the list.

The Todo, Event and Contact interfaces are all implementing the PIMItem interface. A PIMItem must be of the same type as the type of list, so when using an EventList we can only create and add Event objects.

The PIM object is the first object that has to be created to access the native PIM database and it is used to retrieve the different types of lists that reside in the native PIM database. To get a hold of the PIM object we have to use the PIMs factory method getInstance:

PIM pim = PIM.getInstance();

When we have a PIM object, we can list the available lists that reside on the mobile phone and we can get a reference to one of the lists with the method:

PIMList openPIMList(int pimListType, int mode)

The pimListType defines which list we want a access, the mode sets the access mode to the list like read, write and read & write.
To get a reference to the phones Calendar (EventList) we do the following:

EventList eventList =  (EventList)pim.openPIMList(PIM.EVENT_LIST, PIM.READ_WRITE);

As mentioned before there are three different types of pimListTypes:

  • ContactList - PIM.CONTACT
  • ToDoList - PIM.TODO_ LIST
  • EventList - PIM.EVENT_LIST

If the list type is not supported a PIMException will be thrown. Since the user will be prompted to give the MIDlet access to the PIM database, there is a chance that a SecurityException will be thrown and this should be managed as well.

When we have an EventList we can list all the existing Event items in the list by calling

Enumeration eventEnum= eventList.items();

There are also methods for listing existing PIMitems with filtering functionalities.

PIMItems and Fields
There are three different interfaces that implement the PIMItem interface and these are: ToDo, Event and Contact interfaces.

A PimItem represents an entry in the corresponding list in the PIM database, for example an Event object represents an entry in the EventList (Calendar) in the PIM database.

The data that a PIMItem object is encapsulating are called fields.

All fields are not supported (see MIDP 2.0 Developers' Guidelines). This can be checked with the method PIMList.isSupportedField(int field) and should be used. Some fields are ints, some are Dates and so on. This is the available fields in an Event object:

  • String fields: LOCATION, NOTE, SUMMARY, UID
    To get the value of one of these fields we have to use the method:
    String getString(int field, int index)
  • Date fields: END, REVISION, START 
    To get the value of one of the Date fields we have to use the method:
    long getDate(int field, int index)
  • int fields: ALARM, CLASS
    And for the int values we use this method:
    int getInt(int field, int index)

The following code snippet lists all the entries in the mobile phone's Calendar and writes the NOTE field for each of them:

try{
eventList = (EventList)pim.openPIMList(PIM.EVENT_LIST,PIM.READ_ONLY);
enumeration = eventList.items();

}catch(Exception e){System.out.println(e.toString());}
       
        while(enumeration.hasMoreElements())
        {
           
            Event ev = (Event)enumeration.nextElement();
            int eValues = ev.countValues(Event.NOTE);
            for(int i =0; i< eValues;i++)
            {
                String s = ev.getString(Event.NOTE, i);
                System.out.println(s);
            }           
        }

The ToDo objects and Contacts have their own fields but they are accessed in the same way.

Creating and adding PIMItems
To create a new Event for the calendar we use the createEvent method in the EventList class:

Event event = eventList.createEvent();

Since the fields in the Event interface have three different data types (Date, String, int) there are three different methods for setting the different types of fields:

void addDate(int field, int attributes, long value)

void addInt(int field, int attributes, int value)

addString(int field, int attributes, java.lang.String value)

The field parameter determines which field we want to use, for example Event.NOTE. The attribute value is used for further description of the data values for a field, if no attributes are to be associated, then the ATTR_NONE is used. The value parameter contains the actual value for the field. In the code snippet below we are setting the NOTE field and use the addString method since the NOTE field is of the data type String:
           
if (eventList.isSupportedField(Event.SUMMARY))
event.addString(Event.SUMMARY, PIMItem.ATTR_NONE, "a note");

This will not change anything in the list and the native PIM database, to create permanent event data we need to use the method commit:

try{
event.commit();
}
catch(Exception e) {}

The same thing applies for all PIMItems.

Serialization
It is not difficult to send PIMItems between mobile phones such as a mobile client and a web server. The PIM class has two methods for reading PIM items from an InputStream and writing a PIMItem to an OutputStream. The method toSerialFormat is used to write a PIMItem to an OutputStream.

void toSerialFormat(PIMItem item, java.io.OutputStream os, java.lang.String enc,
java.lang.String dataFormat)

The enc parameter specifies the encoding and must be "UTF-8" for Sony Ericsson mobile phones. The dataFormat String should be "VCARD/2.1" for Contact objects and "VCALENDAR/1.0" for Todo and Event objects. This parameter can be retrieved with the method supportedSerialFormats(int pimListType) in the PIM class.

String[] data_formats = pim.supportedSerialFormats(PIM.CONTACT_LIST);
      try {
          pim.toSerialFormat(myContact, os, "UTF-8", data_formats[0]);
      }
      catch (PIMException pe){
      }

We can read PIMItems from an inputStream with the fromSerialFormat method:

PIMItem[] fromSerialFormat(java.io.InputStream is, java.lang.String enc)

The enc parameter has to be "UTF-8" as with the toSerialFormat method.

Here is a code example for a MIDlet that is used for creating recurrent Events in the native Calendar without the use of the RepeatRule class:

Download example>>

More information:

 

Back
Score
Login to rate page

Copyright © 2001 - 2008 Sony Ericsson Mobile Communications AB. All Rights Reserved.