Contacts and Calendars

PIM API (Personal Information Management)

Flexible framework for access to: Contact list Calendar list To-Do list

Contacts and Calendars

PIM API (Personal Information Management)

Flexible framework for access to: Contact list Calendar list To-Do list

Designed around the concept of Item and ItemList

PIMItem

Contact Event ToDo

PIMIList

ContactList EventList ToDoList

Contact

A collection of fields, with one more values, with attributes for each value

TEL ATTR_WORK:717-… ATTR_WORK:717-…

field attr:val attr:val

EMAIL ATTR_PREFERRED:a@b.c ATTR_NONE:a1@b.c

NAME ATTR_NONE: Smith || John || D

Contact (PIMItem)

A collection of fields, with one more values, with attributes for each value

Each field has type : INTEGER, BOOLEAN, DATE, BINARY STRING (e.g. EMAIL, TEL) STRING_ARRAY (e.g. NAME)

TEL ATTR_WORK:717-… ATTR_WORK:717-…

field attr:val attr:val

EMAIL ATTR_PREFERRED:a@b.c ATTR_NONE:a1@b.c

NAME ATTR_NONE: Smith || John || D

Contact

Predefined Constants (from Contact API)

fields – NAME, NICK_NAME, TEL, ADDR, NOTE, PHOTO, EMAIL, …

attributes – ATTR_NONE, ATTR_PREFERRED, ATR_HOME, ATTR_WORK,…

type – STRING, STRING_ARRAY, INTEGER, BINARY, …

Contact

Selected Methods (inherited from PIMItem):

// Add (append) a new value to a field

 void addString(int field, int attributes, String value);

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

 void addBinary(int field, int attributes, byte[] value, int off, int len);

// Retrieve the n-th value in a field

String getString(int field, int index);

int getInt(int field, int index);

byte[] getBinary(int field, int index);

// Update the n-th value in a field

 void setString(int field, int index, int attributes, String value);

 void setInt(int field, int index, int attributes, int value);

 void setBinary(int field, int index, int attr, byte[] value, int off, int len);

int[] getFields();

int countValues(int field); (e.g. how many phone numbers entered)

Contact

Example for STRING fields

// Contact c = ... (obtain a contact)

// add three values for field TEL field with relevant attributes

 c.addString(Contact.TEL, Contact.HOME, “717-337—6641”);

c.addString(Contact.TEL, Contact.WORK, “717-337—6642”);

c.addString(Contact.TEL, Contact.MOBILE, “717-337—6643”);

// add three values for field EMAIL field with relevant attributes

 c.addString(Contact.EMAIL, Contact.ATTR_WORK | Contact.ATTR_PREFERRED, “a@b.c”);

 c.addString(Contact.EMAIL, Contact.ATTR_NONE, “a2@b.c”);

Contact Example for STRING_ARRAY fields – value is an array of strings

Need to know: how big the value array should be how to index in the value array

field attr:val

NAME ATTR_NONE: Smith || John || D

Contact Example for STRING_ARRAY fields – value is an array of strings

Need to know: how big the value array should be how to index in the value array

// Contact contList = ... (obtain a list)

// Contact c = ... (obtain a contact)

 int size = cl.stringArraySize(Contact.ADDR);

String[] address = new String[size];

address[Contact.ADDR_STREET] = “300 N Washington”;

address[Contact.ADDR_COUNTRY] = “17325”;

address[Contact.ADDR_POSTALCODE] = “USA”;

c.addStringArray(Contact.ADDR, Contact.WORK, address);

c.commit();

field attr:val

NAME ATTR_NONE: Smith || John || D

Contact Example for STRING_ARRAY fields – value is an array of strings

Need to know: how big the value array should be how to index in the value array

// Contact contList = ... (obtain a list)

// Contact c = ... (obtain a contact)

 int size = cl.stringArraySize(Contact.ADDR);

String[] address = new String[size];

address[Contact.ADDR_STREET] = “300 N Washington”;

address[Contact.ADDR_COUNTRY] = “17325”;

address[Contact.ADDR_POSTALCODE] = “USA”;

c.addStringArray(Contact.ADDR, Contact.WORK, address);

c.commit();

field attr:val

NAME ATTR_NONE: Smith || John || D

Contact and ContactList

Contacts are associated with ContactLists

Contact and ContactList interaction:

Contact methods

 PIMList getPIMList() – obtain the list in which this Contact (Item) belongs

void commit() – “store” the Contact (Item) in the ContactList it belongs to

ContactList methods

Contact createContact() – create a contact object

Contact importContact(Contact c) – inserts a copy of c in the list; returns the copy

Contact removeContact(Contact c) – removes a matching contact

ContactList

Contact Contact Contact

Contact and ContactList Complete Example

PIM pim = PIM.getInstance();

ContactList contacts =

(ContactList) pim.openPIMList(PIM.CONTACT_LIST, PIM.READ_WRITE);

Contact c = contacts.createContact();

int size = cl.stringArraySize(Contact.ADDR);

String[] address = new String[size];

address[Contact.ADDR_STREET] = “300 N Washington”;

address[Contact.ADDR_COUNTRY] = “17325”;

address[Contact.ADDR_POSTALCODE] = “USA”;

c.addStringArray(Contact.ADDR, Contact.WORK, address);

c.commit(); // commit (save) the data in the list

Contacts.close();

Contact and ContactList Traversing a ContactList – (see MIDP API for Enumeration details)

Enumeration contacts = cl.items();

while (contacts.hasMoreElements()) {

Contact c = (Contact) contacts.nextElement();

// extract the data

String[] name = c.getStringArray(Contact.NAME, 0);

String first = name[Contact.NAME_GIVEN];

String last = name[Contact.NAME_FAMILY];

// do s.th. With data

mainForm.append(last + ", " + first + "\n");

}

Contact and ContactList Things to keep in mind:

Check if the fields and attribute values are supported by the phone

 boolean isSupportedArrayElement(int stringArrayField, int arrayElement)

boolean isSupportedAttribute(int field, int attribute)

boolean isSupportedField(int field)

Importing External Data PIM API can import/export data in vCard and vCalendar format

Format Specification --- Internet Mail Consortium ( www.imc.org )

Example vCard

BEGIN:VCARD

N:Smith;John;D

NICKNAME:DJ

TEL;HOME:861012345678

TEL;WORK:861012345678

EMAIL;PREF:a@b.c

BDAY:1971-08-13

TZ:-06:00

END:VCARD

Importing External Data PIM API can import/export data in vCard and vCalendar format

Format Specification --- Internet Mail Consortium ( www.imc.org )

Example vCard

BEGIN:VCARD

N:Smith;John;D

NICKNAME:DJ

TEL;HOME:861012345678

TEL;WORK:861012345678

EMAIL;PREF:a@b.c

BDAY:1971-08-13

TZ:-06:00

END:VCARD

InputStream in = getResourceAsStream(“/vcard.vcs”);

PIMItem[] items = pim.fromSerialFormat(in, “UTF-8”);

for (int i = 0; I < items.length; ++i) { Contact c = (Contact) items[i]; Contact added = contacts.importContact(c); added.commit();}

Contact and ContactList Things to keep in mind:

Check if the fields and attribute values are supported by the phone

 boolean isSupportedArrayElement(int stringArrayField, int arrayElement)

boolean isSupportedAttribute(int field, int attribute)

boolean isSupportedField(int field)

Taking Pictures Setting up the Control

player = Manager.createPlayer("capture://video");

player.realize();

videoControl = (VideoControl) player.getControl("VideoControl");

Form form = new Form("Camera Form");

Item item = (Item) videoControl.initDisplayMode(

GUIControl.USE_GUI_PRIMITIVE, null);

form.append(item);

mDisplay.setCurrent(form);

Taking the picture

byte[] raw = videoControl.getSnapshot(null);

Image image = Image.createImage(raw, 0, raw.length);