前不久我们给大家介绍过《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.
【编辑推荐】