| PIM API
Java个人信息管理(Personal Information Manager,PIM) API(javax.microedition.pim)以及BlackBerry PDAP(Personal Digital Assistant Profile) API(net.rim.blackberry.api.pdap)允许你访问BlackBerry设备上的日历,任务,以及地址本.
注:在4.0版本里,net.rom.blackberry.api.pim包是不赞成使用的. 现在这个包里的类在javax.microedition.pim and net.rim.blackberry.api.pdap里可以得到.
PIM类是一个抽象类,它提供了访问BlackBerry设备上的PIM数据的方法.
获取一个PIM对象
调用PIM.getInstance().
注:当你的应用程序第一次访问PIM API时,它将检查一个ControlledAccessException.如果系统管理员使用应用程序控制限制访问PIM API,一个运行时异常将会抛出.为获取更多信息,参看”BlackBerry应用程序开发者指南 第2卷:高级 第一卷:基础”.
PIM列表
PIM列的接口代表了所有联系人,事件以及任务列的常用功能.一个列包含0个或多个项,它们是PIMItem的子类.使用PIM列组织相关项,并且获取一些或所有列表的项.
注:在BlackBerry设备里,每个ContactList,ToDoList或EventList实例都会涉及到BlackBerry设备上的本地数据库.第三方应用程序不能创建自定义的列表.
PIM项
PIMItem接口代表了一个列项常用的功能.Contact,Event,以及ToDo接口扩展了PIMItem.一个PIM项代表了单个入口的数据集合,例如一个约会或者一个联系人.
当你在一个指定的PIM列表上创建一个PIM项时,自从它存在开始,此项仍保留了和列表的关联.你也可以使用标准的格式,例如iCal和vCard,导入或导出PIM项里的数据.
字段
一个PIM项在字段里存储数据.每个PIMItem接口-Contact,Event,或ToDo-为每个支持的字段定义了唯一的ID.例如,Contact接口定义字段来存储一个internet消息地址(EMAIL),姓名(FORMATTED_NAME),以及电话号码(TEL).
在你试图设置或获取字段值之前,调用PIMList.isSupportedField(int)来确认是否支持方法.
一个字段可能有一个与之关联的具有描述性的标签显示给用户.为获取这个字段的标签,调用PIMList.getFieldLabel(int).
每个字段都有一个数据类型ID,例如INT,BINARY,DATE,BOOLEAN,或STRING.为了得到一个字段的数据类行,调用PIMList.getFieldDataType(int).
数据类型决定了你将使用哪一个方法得到或设置字段数据.例如:
如果字段的数据类型为STRING,为了加入一个值,调用PIMItem.addString(String).
为了改变已经存在的值,调用PIM.setString(String).
为了获取一个字段值,调用PIMItem.getString().
监听者
当列表里的一个项发生变化时,你的PIMListListener接口实现会收到这个通知. PIMListListener接口提供了下面的方法:
方法
描述
itemAdded(PIMItem)
当加入一个项到列表时调用.
item.Removed(PIMItem)
当从列表里删除时调用.
itemUpdated(PIMItem,PIMItem)
当一个项发生变化时调用.
ContactList cl = (ContactList)PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.WRITE_ONLY);
((BlackBerryPIMList)cl).addListener(
new PIMListListener() {
public void itemAdded(PIMItem item) {
System.out.println(" ITEM ADDED: " +
((Contact)item).getString(Contact.UID, 0));
}
public void itemUpdated(PIMItem oldItem, PIMItem newItem) {
System.out.println(" ITEM UPDATED: " +
((Contact)oldItem).getString(Contact.UID, 0) + " to " +
((Contact)newItem).getString(Contact.UID, 0));
}
public void itemRemoved(PIMItem item) {
System.out.println(" ITEM REMOVED: " +
((Contact)item).getString(Contact.UID, 0));
}
});
注:监听者仍然保持和BlackBerry设备数据库的关联,甚至是在相应的PIMList对象已经删除之后.为了删除一个监听者,调用BlackBerryPIMList.removeListener().
远程地址查询
支持远程地址查询的应用程序应该实例化BlackBerryContactList接口.此节口扩展了ContactList接口,并且提供了下面额外的方法:
方法
描述
choose(Contact, int, boolean)
启动地址本以至用户可以选择一个地址.
void lookup(Contact, RemoteLookupListener)
初始化一个远程查询.
void lookup(String, RemoteLookupListener)
初始化一个远程查询.
RemoteLookupListener接口提供了一单个方法,items(),此方法返回一个远程地址查询结果的迭代.
使用地址簿
使用一个ContactList的实例增加或查看BlackBerry设备地址簿的联系人信息.创建Contact对象存储单独的联系人信息,此信息包含姓名,电话号码,Email,以及街道地址.
BlackBerry特定的地址字段
BlackBerryContact接口扩展了Contact,为了访问BlackBerry联系人特定的字段, 它定义了下面的常数:
常量
描述
BlackBerryContact.PIN
访问PIN字段.
BlackBerryContact.USER1 到 USER4
访问USER1到USER4字段.
为了定义USER1到USER4字段的标签,调用BlackBerryPIMList.setFieldLabel().
此改变立即生效.你不必要提交改变.
注:改变一个标签将影响所有BlackBerry设备上的联系人.
打开一个联系人列表
在你增加联系人之前,你必须创建一个联系人列表.调用PIM.openPIMList().将列表的类型作为参数提供给open(PIM.CONTACT_LIST),并且提供访问模式(READ_WRITE,READ_ONLY,或WRITE_ONLY)打开列表.
如果你正在为BlackBerry设备专门编写一个应用程序,将你的联系人列表转化为BlackBerryContactList,因为此接口提供了一个附加的方法来支持远程地址查询.为了让一个应用程序可以跨多个兼容的Java ME BlackBerry设备,使用PDAP实现.
ContactList contactList = null;
try {
contactList = (ContactList)PIM.getInstance().openPIMList(
PIM.CONTACT_LIST, PIM.READ_WRITE);
}
catch (PimException e) {
return;
}
注:联系人不会加到数据库中,直到你提交它.为获得更多信息,参看30页的”保存一个联系人”.
创建一个联系人
调用联系人列表的createContact().
Contact contact = contactList.createContact();
增加联系人信息
Contact类定义了保存数据的字段,例如Contact.Name,Contact.ADDR,以及Contact.TEL.每个字段都有一个特定的数据类型,你可以调用PIMList.getFieldDataType(int)来获取它们.由于依赖字段的数据类型,通过调用下列方法创建一个新值: addString(), addStringArray(), addDate(), addInt(), addBoolean(), 或addBinary().
在你设置和获取一个字段之前,为了验证列表项是否支持字段,调用:
ContactList.isSupportedField(int)
通过使用属性来区分其值,某些字段可以存储多个值.例如,TEL字段支持ATTR_HOME,ATTR_WORK,ATTRMOBILE和ATTR_FAX属性存储工作,家庭,移动以及传真号码.
为了判断一个字段最多支持几个值,调用PIMList.maxValues(int field).
此方法返回支持的值的个数,返回-1意味着可以增加任意个数的值.为了验证一个字段是否支持特定的属性,调用isSupportedAttribute(int, int).
// Create string array for name.
try {
ContactList contactList = (ContactList)PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.WRITE_ONLY);
}
catch (PIMException e)
{
}
Contact contact = contactList.createContact();
String[] name = new String[5]; // 5 name elements
try {
name[Contact.NAME_PREFIX] = "Mr.";
name[Contact.NAME_FAMILY] = "McPherson";
name[Contact.NAME_GIVEN] = "Scott";
}
catch (IllegalArgumentException iae) {
// handle exception
}
// Add name.
if(contactList.isSupportedField(Contact.NAME)) {
contact.addStringArray(Contact.NAME, Contact.ATTR_NONE, name);
}
// Create string array for address.
String[] address = new String[7]; // 7 address elements
try {
address[Contact.ADDR_COUNTRY] = "United States";
address[Contact.ADDR_LOCALITY] = "Los Angeles";
address[Contact.ADDR_POSTALCODE] = "632300";
address[Contact.ADDR_REGION] = "California";
address[Contact.ADDR_STREET] = "323 Main Street";
}
catch (IllegalArgumentException iae) {
// Handle exception.
}
// Add address.
contact.addStringArray(Contact.ADDR, Contact.ATTR_NONE, address);
// Add home telephone number.
if (contactList.isSupportedField(Contact.TEL) &&
contactList.isSupportedAttribute(Contact.TEL, Contact.ATTR_HOME))
{
contact.addString(Contact.TEL, Contact.ATTR_HOME, "555-1234");
}
// Add work telephone number.
if (contactList.isSupportedField(Contact.TEL)) {
contact.addString(Contact.TEL, Contact.ATTR_HOME, "555-5555");
}
// Add work internet messaging address.
if (contactList.isSupportedField(Contact.EMAIL)) {
contact.addString(Contact.EMAIL,
Contact.ATTR_WORK,
"aisha.wahl@blackberry.com");
}
修改联系人信息
对于仅支持一个值的字段,调用合适的set方法用一个新值替代 |