BlackBerry 应用程序开发者指南 第二卷：高级–第3章 集成PIM功能

3
第3章 集成PIM功能

PIM API
使用地址本
使用任务
使用日历

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: " + [...]

继续阅读本文 →

  

Confach发表于 April 28, 2008 12:20 pm | 留言(1) |文档 

BlackBerry 应用程序开发者指南 第二卷：高级–第2章 集成消息

2
  第2章 集成消息

Mail API
操作消息
管理文件夹
管理附件

Mail API
BlackBerry Mail API在net.rim.blackberry.api.mail和net.rim.blackberry.mail.event中.
Mail API类
BlackBerry Mail API在net.rim.blackberry.api.mail和net.rim.blackberry.mail.event包中.它允许应用程序使用消息应用程序发送,接收和访问消息..
注:BlackBerry mail API提供访问消息列表里的消息的能力,但不能访问其他类型的消息,例如短消息,PIN消息,或者电话呼叫记录.为了访问电话呼叫记录,使用电话呼叫记录的API(net.rim.blackberry.phonelogs).为得到更多信息,参卡79也的”访问和管理电话记录”.
      当你的应用程序首先访问mail API时,检查一个NoClassDefFoundEorror!.如果系统管理员使用程序控制限制访问mail API,此错误将抛出.为获得更多信息,参看BlackBerry应用程序开发者指南第二卷:高级 第一卷:基础的16页的”应用程序控制”

类

描述

Session

本类为消息操作表现了一个抽象模型.它提供访问消息服务,存储,以及传输的能力.应用程序获取一个新的Session对发送或接收消息..

Store

本类模型化BlackBerry设备的底层消息存储.为了获得一个Store实例,调用Session实例.

Transport

本类代表了消息传输协议.

消息
一个Message对象包含了一组属性,例如主题(subject),发送者(sender),接收者(recipients),以及消息体(它的内容).为获取更多消息,参看14页的”多部分消息”.
下面的类和接口定义了支持的属性:

类或接口

描述

Address

本类代表了一个消息,ftp,http,或来自于(from),回复(reply to),接收属性以及消息体里的wap地址.Address类包含一些字段来存储完全许可的地址字符串,例如aisha.wahl@blackberry.com和显示名.

Header

本类定义了支持的消息头字段,例如 TO,FROM,以及DATE.

Message.Flag

本接口定义了消息标记,例如MOVED,OPENED,或SAVED.

Message.Icons

本接口定义了多种状态图标的字符串表现形式,例如一个已发送消息的检查标记.

Message.RecipientType

本接口定义了支持的接收类型,例如TO,CC或BCC.

Message.Status

本接口为发送和接收消息定义了状态选项,例如RX_RECEIVED,EX_ERROR,TX_SENT,以及TX_READ.

多部分消息(Multipart messages)
Mail API支持多部分消息.Multipart抽象类为一个或多个BodyPart对象提供一个容器.Multipart提供获取和设置其子部分的方法.
每个BodyPart由消息头字段(属性)以及内容(消息体).Mail API提供四个BodyPart的实现.

类

描述

ContactAttachmentPart

本类代表了一个地址卡(address card)附件部分.使用javax.microedition.pim.Contact接口.为获得更多信息,参看27页的”使用地址本”.

TextBodyPart

本类代表了一个内容的消息体,此内容为text/plain类型.你可使用本类创建text/plain部分的多部分消息.

UnsupportedAttachmentPart

本类代表了一个不支持的附件部分.你不能实例化此类.内容类型一直为application/octet-stream.

SupportedAttachmentPart

本垒代表了一个支持的附件部分,对于此,在BlackBerry设备上由一个已注册的附件处理器.

消息存储
Folder类代表了一个本地邮件箱文件夹.定义了多种文件夹类型,包括INBOX,OUTBOX,SENT以及OTHER.你可以使用这些文件夹类型为获取或保存消息获取文件夹.
Store类模型化BlackBerry设备的底层消息存储,并提供方法查找和获取文件夹.文件夹以层次存在,正如下面例子中的描述一样:

Mailbox - Aisha Wahl
Inbox
Projects
In Progress
Complete
Personal

一个标准的分隔符在层次结果里独立每个文件夹,你可使用getSeperator()来得到它.你也可以列出Store对象里的所有文件夹,列出文件夹下的子文件夹,或者基于查询字符串查找一个文件夹.
Folder类定义了一些方法获取消息,或子文件夹,以及保存和删除消息.
注:多个Folder实例可以引用相同的BlackBerry设备文件夹.这样,你可以一直调用相同Folder对象的addFolderListener()以及removeFolderListener().使用Folder.equals()判断是否2个Folder对象引用了相同的folder.
Mail事件
BlackBerry mail事件包(net.rim.blackberry.api.mail.event)定义了下面的消息事件以及每个事件的监听者:

事件

描述

FolderEvent

当文件夹里的一个消息增加或删除时此事件触发.

MessageEvent

当一个消息改变(消息体,消息头,或标记)时此事件触发.

StoreEvent

当一个消息以批处理(例如,当BlackBerry和桌面同步时)的形式加入到消息Store里,或从消息Store里删除,此事件触发.

MailEvent类是这些mail事件类的基类.它定义了一个抽象的dispatch()方法，为每个事件调用合适的监听者方法.
EventListener接口为FolderListener和MessageListener接口提供一个通用接口.

监听者

可用对象

FolderListener

可以将此类型加入到Folder或Store对象中.

MessageListener

可以将此类型加入到Message对象中.

StoreListener

可以将此类型加入到Store对象中.

操作消息
接收消息通知
FolderListener和StoreListener接口的实现允许你的应用程序接收消息通知.

public class MailTest implements FolderListener, StoreListener { … }

增加一个监听者到消息Store
为了监听消息存储事件,例如同步,获取一个Store对象,并将一个StoreListener实例加给它.

try {
    Store store = Session.waitForDefaultSession().getStore();
}
catch (NoSuchServiceException e) {
    System.out.println(e.toString());
}
store.addStoreListener(this);

当消息以批处理的形式增加和删除时,StoreListener.batchOperation()的实现定义了应用程序的行为.例如,你的应用程序可能检查任何它引用的对象是否删除.

void batchOperation(StoreEvent e)
{
    // [...]

继续阅读本文 →

  

Confach发表于 April 28, 2008 12:15 pm | 留言 |文档