SMI - Introduction to JSR 75 PIM

1

Samsung University Program

2

What is PIM API

The PIM API for Java ME is an optional package defined in the Java Specification Request (JSR) 75.

The primary goal of the PIM APIs is to provide access to Personal Information Management (PIM) data on J2ME devices.

PIM data is defined as information included in address book, calendar application, and to do list applications.

CLDC 1.0 is the minimum required platform for this API set.

3

Goals of PIM API

Provide access to entries in an address book that may or may not reside on the device.

Provide access to entries in a calendar that may or may not reside on the device.

Provide access to entries in a to do list that may or may not reside on the device.

Provide an API that allows access to all fields in native PIM databases.

Provide security in using these APIs so that unauthorized Java

applications may not access the entries contained in the PIM lists.

Support the import and export of address book entries in a vCard format and of calendar , to do entries in a vCalendar format .

4

PIM API Package

The API resides in package, javax.microedition.pim.

InterfacesContact, ContactList, Event, EventList, PIMItem, PIMList, ToDo, and ToDoList

Classes PIM and RepeatRule.

ExceptionsFieldEmptyException, FieldFullException, PIMException, and UnsupportedFieldException

5

Classes and Interfaces in PIM API

6

PIM API Package details

The PIM API refers to the databases as PIMList objects

PIMList represents a PIM database in general

ContactList represents the contact list database

EventList represents the calendar events database

ToDoList represents the to-do list database

7

PIM API Package details contd..

PIMItem is a generalization of PIM data, such as contact, calendar or a to-do item.

Contact represents a contact item in the address book database.

Event represents an event item in the calendar database.

ToDo represents a to-do item in the To-Do database.

Items are groupings of related fields. A field consists of a label, a data type, values, and attributes.

8

PIM API Package details contd..

Contact Field Name Field Data Types

NAME, ADDR PIMItem.STRING_ARRAY

EMAIL, FORMATTED_NAME, NICKNAME, NOTE, ORG, TEL, TITLE, UID, URL, PHOTO_URL, PUBLIC_KEY_STRING

PIMItem.STRING

BIRTHDAY, REVISION PIMItem.DATE

PHOTO, PUBLIC_KEY PIMItem.BINARY

Event Field Name Field Data Types

LOCATION, NOTE, SUMMARY, UID PIMItem.STRING

END, REVISION, START PIMItem.DATE

ALARM, CLASS PIMItem.INT

ToDo Field Name Field Data Types

NOTE, SUMMARY, UID PIMItem.STRING

CLASS, PRIORITY PIMItem.INT

COMPLETION_DATE, DUE, REVISION PIMItem.DATE

COMPLETED PIMItem.BOOLEAN

9

PIM API Package details contd..

10

PIM API Availability

To determine if the optional PIM API is available you have to call:

String currentVersion = System.getProperty(“microedition.pim.version”);

If the PIM API is available a string with the version will be returned (eg: “1.0”)

If the PIM API is not available a null value is returned

11

Security Consideration

Access to personal data has obvious security and privacy implications.

Many of the operations will require the MIDlet to acquire an appropriate permission, either by explicit user approval or by being granted a permission as a trusted MIDlet.

It is important to realize that in these operations a SecurityException can be thrown and must be handled properly

Untrusted midlets required explicit user permission to call restricted APIs

12

Security Consideration contd..

Trusted midlets may acquire permission automatically depending on the security domain they belong to.

Required File Permissions javax.microedition.pim.ContactList.read

javax.microedition.pim.ContactList.write

javax.microedition.pim.EventList.read

javax.microedition.pim.EventList.write

javax.microedition.pim.ToDoList.read

javax.microedition.pim.ToDoList.write

13

Reading Telephone Number

Open PIMList using openPIMList(int pimListType, int mode) method of PIM class. Pass the parameters PIM.CONTACT_LIST as listType and PIM.READ_WRITE as Mode

PIM pim = PIM.getInstance();PIMList pimList = pim.openPIMList(PIM.CONTACT_LIST,

PIM.READ_WRITE);

Retrieve enumeration of PIMItem’s using items() method of PIMList class

for (Enumeration items = pimList.items();

items.hasMoreElements();) PIMItem pimItem = (PIMItem) items.nextElement();

14

Reading Telephone Number contd..

Now get supported field in each PIMItem

if (pimList.isSupportedField(Contact.TEL))

Get Number of Telephones present for PIMItem

int countValues = pimItem.countValues(Contact.TEL);

Loop through the countValues and get the Contact no

for(int i=0; i<countValues; i++)

String contactNo = pimItem.getString(Contact.TEL, i);

15

Creating new Contact

Open PIMList using openPIMList(int pimListType, int mode)

method of PIM class. Pass the parameters PIM.CONTACT_LIST as listType and PIM.READ_WRITE as Mode

Retrieve ContactList object

ContactList conList = (ContactList)PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);

Call createContact() method of ContactList class to retrieve Contact Object

Contact new_contact = conList.createContact();

16

Creating new Contact contd..

Now check for each field support and add new contact data in the respective supported fields.

if (conList.isSupportedField(Contact.ORG))

new_contact.addString(Contact.ORG, PIMItem.ATTR_NONE, "Samsung");

if (conList.isSupportedField(Contact.TEL)) {

new_contact.addString(Contact.TEL, PIMItem.ATTR_NONE, "9786545342");

new_contact.addString(Contact.TEL, PIMItem.ATTR_HOME, "9786545347");

}

17

Creating new Contact contd..

if (conList.isSupportedField(Contact.EMAIL))

new_contact.addString(Contact.EMAIL, PIMItem.ATTR_NONE,

"support.smi@samaung.com");

if (conList.isSupportedField(Contact.NOTE)) new_contact.addString(Contact.NOTE, PIMItem.ATTR_NONE, "Welcome to Samsung Mobile Innovator");

New Contact Cannot be created until Commit() method of Contact class is called

new_contact.commit();

conList.close();

18

Thankyou

THANKYOU