BlackBerry应用开发者指南 Mail API

前不久我们给大家介绍过《BlackBerry应用开发者指南 使用受控API》，本文我们将介绍《BlackBerry应用开发者指南 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).）

当你的应用程序首先访问mail API时,检查一个NoClassDefFoundEorror!.如果系统管理员使用程序控制限制访问mail API,此错误将抛出.

类

描述

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.）#p#

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)  
 
{  
 
    // Perform action when messages added or removed in batch operation.  
 
}  
 
   
 
 

增加一个监听者给文件夹

为了监听一个文件夹事件,例如将一个消息加入到一个特定的文件夹,为你想接收新消息通知的文件夹获取一个Folder对象.将一个FoldListener实例加到此文件夹对象.

Folder[] folders = store.list(Folder.INBOX);  
 
Folder inbox = folders[0];  
 
inbox.addFolderListener(this);  

当文件夹事件发生时, 实现FolderListener.messagesAdded() 和FolderListener.messagesRemoved()完成操作.例如,你可实现这些方法维护任何引用你的应用程序必须指定的mail文件夹的一致性.

void messagesAdded(FolderEvent e) {  
 
    // Perform processing on added messages.  
 
}  
 
 
 
void messagesRemoved(FolderEvent e)  
 
{  
 
    // Perform processing on removed messages.  
 
}  
 

接收一个消息的更多部分

缺省的,发送一个消息的第一部分(一般约2KB)到BlackBerry设备上.调用消息体部分上的hasMore()判断在服务器上是否有更多的数据.调用moreRequestSent()判断是否一个获取更多数据的请求已经发出.调用more()请求一个消息的更多部分.

if (( bp.hasMore())&&(! bp.moreRequestSent())     
 
{  
 
    Transport.more(bp, true);  
 
}  

more()的第二个参数是一个Boolean值,它指定了是否仅获取消息体部分的下一部分(false),或者获取所有剩下的部分(true).

打开一个消息

获取消息存储以及包含消息的文件夹:

Store store = Session.waitForDefaultSession.getStore();  
 
Folder folder = Store.getFolder("SampleFolder");  

从文件夹获取消息对象.迭代数组,并获取信息,例如发送者,主题,显示给用户.

Message[] msgs = folder.getMessages(); 

当用户从列表中选择一个消息时,调用Message对象上的方法获取合适的字段以及消息体内容显示给用户.

Message msg = msgs[0]; // Retrieve the first message.  
 
Address[] recipients = msg.getRecipients(Message.RecipientType.TO)  
 
Date sent = msg.getSentDate();  
 
Address from = msg.getFrom();  
 
String subject = msg.getSubject();  
 
Object o = msg.getContent();  
 
// Verify that the message is not multipart.  
 
if ( o instanceof String ) {  
 
String body = (String)o;  
 
}  
 
//...  

（注:调用一个消息上的getBodyText()方法获取普通文本内容作为一个String.如果消息不包含普通文本,方法将返回null.）

发送一个消息

为发送消息,使用一个Transport对象,它代表了消息传输协议.

创建一个消息

创建一个Message对象,并指定一个文件夹拷贝已发送的消息.

Store store = Session.getDefaultInstance().getStore();  
 
Folder[] folders = store.list(Folder.SENT);  
 
Folder sentfolder = folders[0];  
 
Message msg = new Message(sentfolder);  

指定接收者

创建一个Address对象的数组,然后将每个地址加入到数组中.你的应用程序应该捕获一个AddressException异常,如果地址无效,它将会抛出:

try {  
 
  toList[0]= new Address("aisha.wahl@blackberry.com", "Aisha Wahl");  
 
}  
 
catch(AddressException e)  
 
{  
 
    System.out.println(e.toString());  
 
}  

增加接收者

调用Message.addRecipients().

将接收者类型(TO,CC,或BCC),以及地址数组作为参数提供给此方法.

如果你的消息有多个接收者类型,每个只调用一次addRecipients()方法.

msg.addRecipients(Message.RecipientType.TO, toList); 

指定一个发送者的姓名和internet消息地址

调用setFrom(Address)

Address from = new Address("scott.mcpherson@blackberry.com",  
 
"Scott McPherson");  
 
msg.setFrom(from);  

增加一个主题行

调用setSubject(String).

msg.setSubject("Test Message"); 

指定消息内容

调用setContent(String).一般来说,你的应用程序从用户输入的文本域里获取内容.

try 
 
{  
 
    msg.setContent("This is a test message.");  
 
}  
 
catch(MessagingException e)  
 
{  
 
    System.out.println(e.getMessage());  
 
}  

发送消息

调用Transport.send(Message).

try {  
 
Transport.send(msg);  
 
}  
 
catch(MessagingException e) {  
 
    System.out.println(e.getMessage());  
 
}  

回复消息

为了创建一个消息作为已存在消息的回复,调用Message.reply(Boolean).作为此方法的参数,指定true回复所有消息接收者,或设置false仅回复发送者.

Store store = Session.waitForDefaultSession().getStore();  
 
Folder[] folders = store.list(INBOX);  
 
Folder inbox = folders[0];  
 
Message[] messages = folder.getMessages();  
 
if( messages.length > 0 ) {  
 
    Message msg = messages[0];  
 
}  
 
Message reply = msg.reply(true);  
 
Transport.send(reply);  

转发一个消息

调用一个已存在Message对象的forward()方法.

（注:转发消息的主题行会自动设置为FW:<original_subject>.）

Message fwdmsg = msg.forward(); 

增加接收者

创建地址数组,然后调用addRecipients(int, Address[]).

Address toList[] = new Address[1];  
 
toList[0]= new Address("aisha.wahl@blackberry.com", "Katie Laird");  
 
fwdmsg.addRecipients(Message.RecipientType.TO, toList);  

指定消息内容

调用setContent(String).

<!--[if !vml]--><!--[endif]-->（注:你不能编辑转化消息的文本, setContent()方法在转化的消息前增加文本.）

try {  
 
    fwdmsg.setContent("This is a forwarded message.");  
 
}  
 
catch(MessagingException e) {  
 
    System.out.println(e.getMessage());  
 
}  

发送消息

调用Send(Message).

try {  
 
    Transport.send(fwdmsg);  
 
}  
 
catch(MessagingException e) {  
 
    System.out.println(e.getMessage());  
 
}  
 
try 
 
{  
 
    Transport.send(fwdmsg);  
 
}  
 
catch(MessagingException e) {  
 
    System.out.println(e.getMessage());  
 
} 

代码实例

例:BasicMail.java

/**  
 
* BasicMail.java  
 
* Copyright (C) 2001-2005 Research In Motion Limited.  
 
*/ 
 
package com.rim.samples.docs.basicmail;  
 
import net.rim.blackberry.api.mail.*;  
 
import net.rim.blackberry.api.mail.event.*;  
 
import net.rim.device.api.system.*;  
 
 
 
public class BasicMail extends Application {  
 
    private Store store;  
 
    static void main (String args[]) {  
 
       BasicMail app = new BasicMail();  
 
       app.enterEventDispatcher();  
 
       }  
 
    BasicMail() {  
 
       Store store = Session.getDefaultInstance().getStore();  
 
       Folder[] folders = store.list(Folder.SENT);  
 
       Folder sentfolder = folders[0];  
 
       // Create message.  
 
       Message msg = new Message(sentfolder);  
 
       // Add TO Recipients.  
 
       Address toList[] = new Address[1];  
 
       try {  
 
           toList[0]= new Address(“scott.tooke@rim.com”, “Scott Tooke”);  
 
       }  
 
       catch(AddressException e) {  
 
           System.out.println(e.toString());  
 
       }  
 
       try {  
 
           msg.addRecipients(Message.RecipientType.TO, toList);  
 
       }  
 
       catch (MessagingException e) {  
 
           System.out.println(e.toString());  
 
       }  
 
        
 
       // Add CC Recipients.  
 
       Address ccList[] = new Address[1];  
 
       try {  
 
           ccList[0]= new Address("katie.laird@rim.com", "Katie Laird");  
 
       }  
 
       catch(AddressException e) {  
 
           System.out.println(e.toString());  
 
       }  
 
        
 
       try {  
 
           msg.addRecipients(Message.RecipientType.CC, ccList);  
 
           }  
 
       catch (MessagingException e) {  
 
           System.out.println(e.toString());  
 
       }  
 
        
 
       // Add the subject.  
 
       msg.setSubject("A Test Email");  
 
        
 
       // Add the message body.  
 
       try {  
 
           msg.setContent("This is a test message.");  
 
       }  
 
       catch(MessagingException e)  
 
       {  
 
           // Handle messaging exceptions.  
 
       }  
 
        
 
       // Send the message.  
 
       try {  
 
           Transport.send(msg);  
 
           }  
 
       catch(MessagingException e) {  
 
           System.out.println(e.getMessage());  
 
           }  
 
       System.out.println("Email sent successfully.");  
 
       System.exit(0);  
 
       }  
 
    }  

管理文件夹

为了列出,接收并搜索文件夹,在缺省Session上调用getStore()获取一个Store对象.

Store store = Session.waitForDefaultSession().getStore(); 

列出mailbox store的文件夹

调用Store.List().

Folder[] folders = store.list(); 

根据类型获取文件夹数组

调用List(int).把文件类型作为参数提供给此方法.

Folder[] folders = store.list(INBOX);  
 
Folder inbox = folders[0];  

搜索获取文件夹数组

为了获取层次结构上符合指定查询字符串的所有文件夹,调用findFolder(String).

Folder[] folders = store.findFolder("Inbox"); 

findFolder(String).方法返回一个与指定字符串匹配的文件夹数组,或者如果匹配的文件夹没有找到,返回一个空的数组.

根据名称获取一个文件夹

调用getFolder(String).把文件夹的绝对路径作为参数.如果文件夹没有找到, FolderNotFoundException异常将抛出.

Folder folder = store.getFolder("Mailbox - Aisha Wahl/Inbox/Projects"); 

根据ID获取一个文件夹

调用getID()获取文件夹ID,然后调用ID作为参数的getFolder()方法.

Folder[] folders = store.list();  
 
long id = folders[0].getId();  
 
Folder f2 = store.getFolder(id);  
 

归档(File)消息

调用Folder对象的appendMessage(Message)方法.

Message msg = new Message();  
 
//...  
 
Folder folder = store.getFolder("Inbox");  
 
folder.appendMessage(msg);  
 

管理附件

Mail API 允许你在BlackBerry设备上打开一个进来的消息附件,并且可以创建一个发出去的附件.一个消息附件作为多部分消息的一个独立BodyPart对象表现.

创建一个自定义的附件处理器

AttachmentHandler接口的实现定义了一个自定义的附件处理器.

注册接受的MIME类型

supports(String)的实现注册一个附件处理器接受的附件的MIME类型.当BlackBerry设备接收到一个附件时,此方法被调用.

public boolean supports(String contentType) {  
 
      return (contentType.toLowerCase().indexOf("contenttype") != -1 ? true : false);  
 
}  
 

定义一个相关菜单项字符串

在消息列表中,当用户选择一个附件时,menuString()的实现返回一个显示的菜单项字符串.

public String menuString() {  
 
    return "Custom Attachment Viewer";  
 
}  

定义附件处理

run()的实现完成了对附件的合理处理,并将附件显示给用户.

public void run(Message m, SupportedAttachmentPart p) {  
 
    // Perform processing on data.  
 
    Screen view = new Screen();  
 
    view.setTitle(new LabelField("Attachment Viewer"));  
 
    view.add(new RichTextField(new String((byte[])p.getContent())));  
 
}  

（注: 当在消息列表里选择相应的菜单项时,调用run()方法.）

注册一个附件处理器

AttachmentHandlerManager类控制附件是如何在BlackBerry设备上处理的.当用户打开一个相关类型的附件时,为了使消息应用程序调用你的自定义附件,调用addAttachmentHandler()注册你的附件处理器.

（注:BES附件服务在接收附件时有第一优先级,第三方附件处理器不能覆盖缺省BlackBerry设备的行为.）

AttachmentHandlerManager m = AttachmentHandlerManager.getInstance();  
 
CustomAttachmentHandler ah = new CustomAttachmentHandler();  
 
m.addAttachmentHandler(ah);  

获取附件

SupportedAttachmentPart类代表了一个BlackBerry设备上对应查看器的附件.在BlackBerry设备上.,一个没有查看器的附件作为一个UnsupportedAttachmentPart表现.

获取附件内容

调用getContent().

String s = new String((byte[])p.getContent()); 

获取附件信息

SupportedAttachmentPart类提供多个方法获取附件信息.下面的例子调用getName()和getSize()获取附件名和大小.

public void run(Message m, SupportedAttachmentPart p) {  
 
     ...  
 
     String name = p.getName();  
 
     int size = p.getSize();  
 
    }  

发送一个带有附件的消息

通过创建一个新的Multipart对象创建一个多部分信息.为了创建每个附件组件,创建一个SupportedAttachmentPart的对象,把Multipart作为它的父组件.为了把每个SupportedAttachmentPart增加到Multipart,调用对象上的addBodyPart(SupportedAttachmentPart).

当调用Message对象的setContent(Multipart)时,将 Multipart对象作为参数传入.

MultiPart multipart = new MultiPart(); // Default type of multipart/mixed.  
 
SupportedAttachmentPart attach =  
 
    new SupportedAttachmentPart( multipart, "application/x-example", "filename", data);  
 
multipart.addBodyPart(attach); // Add the attachment to the multipart.  
 
msg.setContent(multipart);  
 
Transport.send(msg); // Send the message.  
 

 【编辑推荐】

1. BlackBerry应用开发者指南 使用受控API
2. 在NetBeans Java ME polish环境下开发BlackBerry应用
3. 简介RIM最新官方BlackBerry JDE 4.7
4. 简介BlackBerry API
5. Java语言编写BlackBerry应用程序