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

作者:Confach 发表于 2006-04-28 22:17 pm
版权信息:可以任意转载, 转载时请务必以超链接形式标明文章原始出处 和作者信息.
http://www.cnblogs.com/confach/articles/387943.html

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)

{

    // 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设备的行为,为获得更多信息,参看”BES维护和疑难解答指南”.

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.
  • Last Updated:2007年1月23日
  • Last Updated:2006年4月28日
posted @ 2006-04-28 22:17  张太国  阅读(3061)  评论(1)    收藏  举报