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,
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