Интерфейсы pim api

Интерфейс	Описание
PIMItem	Самый общий интерфейс для элементов PIM списка.
PIMList	Общий интерфейс для ContactList, EventList и ToDoList, каждый из которых может содержать ноль или более PIMItem элементов.
Contact	Отдельная запись в базе контактов; поля этого интерфейса являются подмножеством полей vCard спецификации.
ContactList	Список Contact элементов.
Event	Отдельная запись в базе событий.
EventList	Список Event элементов.
ToDo	Отдельная запись в базе дел.
ToDoList	Список ToDo элементов.

Классы pim api

Интерфейс	Описание
Класс	Описание
PIM	Набор методов для получения информации о PIMList и установки доступа.
RepeatRule	Описание структуры Event элемента для описания времени наступления соответствующего события; статические поля этого класса представляют собой подмножество поля RRULE в VEVENT, определенного в спецификации vCalendar 1.0.
FieldEmptyException	Эта исключительная ситуация возникает при попытке обратиться к полю, которое не имеет связанных с ним данных.
FieldFullException	Эта исключительная ситуация возникает при попытке записать данные в непустое поле
PIMException	Эта исключительная ситуация инициируется PIM классами
UnsupportedException	Эта исключительная ситуация возникает, когда поле не поддерживается PIM списком, к которому относится элемент.

Чтобы убедиться в том, что устройство поддерживает PIM API, необходимо воспользоваться методом System.getproperty() с параметром microedition.pim.version. Метод должен возвратить номер версии API или null, есть PIM не поддерживается данным устройством.

String v = System.getProperty( "microedition.pim.version" );

if( v != null )

{

// PIM поддерживается

} else {

// PIM не поддерживается

}

Использование pim api

Доступ к данным осуществляется через экземпляр класса PIM:

import javax.microedition.pim.*;

PIM singleton = PIM.getInstance();

Все PIM списки представлены PIMList интерфейсом, имеющим три подинтерфейса: ContactList, EventList и ToDoList.

Для того чтобы получить доступ к PIM списку необходимо использовать метод openPIMList(int par1, int par2, String par3). Первый параметр этого метода определяет тип списка:

• PIM.CONTACT_LIST — для списка контактов

• PIM.EVENT_LIST — для списка событий

• PIM.TODO_LIST — для списка дел

Второй параметр определяет режим работы:

• PIM.READ_ONLY — только чтение

• PIM.READ_WRITE — чтение и запись

• PIM.WRITE_ONLY — только запись

Третий параметр является дополнительным и содержит имя PIM списка, который Вы хотели бы получить. Если Вы опустите этот параметр, openPIMList() вернет заданный по умолчанию список. При попытке открыть несуществующий список, возникает исключительная ситуация PIMException.

...

PIM pim = PIM.getInstance();

ToDoList list = null;

try {

list = (ToDoList) pim.openPIMList(PIM.TODO_LIST, PIM.READ_ONLY, "list-name");

// используем список

} catch (PIMException pe) {

// такого списка не сузествует

} catch (SecurityException se) {

// MIDlet не может получить доступ к требуемому списку

}

Как правило, в сотовом телефоне контакты могут храниться на SIM карте и в памяти самого телефона. Таким образом, имеются несколько различных PIM списков одного типа. Следует сказать, что не существует общепринятых имен для обозначения списков. Чтобы получить все доступные PIM списки, необходимо воспользоваться методом listPIMLists().

PIM список содержит элементы, представленные интерфейсом PIMItem и его подинтерфейсами Contact, Event и ToDo. Чтобы получить набор элементов PIM списка, нужно воспользоваться методом items(). Для перемещения по элементам используйте метод nextElement():

...

Enumeration enum = list.items();

while(enum.hasMoreElements()) {

ToDo task = (ToDo) enum.nextElement();

// Делаем что-нибудь с задачей

}

...

Следующий пример показывает, как открыть список контактов и найти/добавить контакт.

...

// Открываем заданный по умолчанию список контактов.

PIM pim = PIM.getInstance();

ContactList clist;

try {

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

} catch(Exception e) {

// security or other exception

}

// Поиск контактов.

// Метод countValues() возвращает число значений,

// содержащихся в текущем поле.

Enumeration contacts = clist.items();

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

int phoneNumbers = c.countValues(Contact.TEL);

for(int i = 0; i < phoneNumbers; i++) {

if((c.getAttributes(Contact.TEL) != 0) & Contact.ATTR_HOME != 0) {

// домашний номер

String home = c.getString(Contact.TEL, i);

}

}

//Добавляем значение в контакт

Contact c = clist.createContact();

int attrs = Contact.ATTR_HOME;

c.addString(Contact.TEL, attrs, "416-799-1313");

// Некоторые поля могут быть добавлены без атрибутов

c.addString(Contact.ORG, PIMItem.ATTR_NONE, "someName Corporation");

// Заносим элемент в базу данных телефона

c.commit();

...

Обратите внимание на использование метода countValues(), возвращающего число значений в поле. Для чтения значений элементов используются методы getAttributes(int field), getString(int field, int index), getDate(int field, int index) и getInt(int field, int index), где field — определяет требуемое поле, а index — требуемую запись.

Для создания нового PIMItems элемента используются методы createContact(), createEvent(), createToDo(). Для заполнения полей — методы addDate(int field, int attributes, long value), addInt(int field, int attributes, int value), addString(int field, int attributes, java.lang.String value).

Следует отметить, что устройство может поддерживать не все поля. В определенных ситуациях это приводит к потере данных. Чтобы убедиться, что требуемые поля поддерживаются, воспользуйтесь методом isSupportedField().