BlackBerry应用开发者指南 Mail API

移动开发
本文为《BlackBerry应用开发者指南 Mail API》,BlackBerry Mail API在net.rim.blackberry.api.mail和net.rim.blackberry.mail.event中.

前不久我们给大家介绍过《BlackBerry应用开发者指南 使用受控API》,本文我们将介绍《BlackBerry应用开发者指南 Mail API》,BlackBerry Mail API在net.rim.blackberry.api.mail和net.rim.blackberry.mail.event中.

BlackBerry应用开发者指南

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接口的实现允许你的应用程序接收消息通知.

  1. public class MailTest implements FolderListener, StoreListener { ... }  

增加一个监听者到消息Store

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

  1. try {  
  2.  
  3.     Store store = Session.waitForDefaultSession().getStore();  
  4.  
  5. }  
  6.  
  7. catch (NoSuchServiceException e) {  
  8.  
  9.     System.out.println(e.toString());  
  10.  
  11. }  
  12.  
  13. store.addStoreListener(this);  
  14.  

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

  1. void batchOperation(StoreEvent e)  
  2.  
  3. {  
  4.  
  5.     // Perform action when messages added or removed in batch operation.  
  6.  
  7. }  
  8.  
  9.    
  10.  
  11.  

增加一个监听者给文件夹

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

  1. Folder[] folders = store.list(Folder.INBOX);  
  2.  
  3. Folder inbox = folders[0];  
  4.  
  5. inbox.addFolderListener(this);  

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

  1. void messagesAdded(FolderEvent e) {  
  2.  
  3.     // Perform processing on added messages.  
  4.  
  5. }  
  6.  
  7.  
  8.  
  9. void messagesRemoved(FolderEvent e)  
  10.  
  11. {  
  12.  
  13.     // Perform processing on removed messages.  
  14.  
  15. }  
  16.  

接收一个消息的更多部分

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

  1. if (( bp.hasMore())&&(! bp.moreRequestSent())     
  2.  
  3. {  
  4.  
  5.     Transport.more(bp, true);  
  6.  
  7. }  

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

打开一个消息

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

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

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

  1. Message[] msgs = folder.getMessages(); 

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

  1. Message msg = msgs[0]; // Retrieve the first message.  
  2.  
  3. Address[] recipients = msg.getRecipients(Message.RecipientType.TO)  
  4.  
  5. Date sent = msg.getSentDate();  
  6.  
  7. Address from = msg.getFrom();  
  8.  
  9. String subject = msg.getSubject();  
  10.  
  11. Object o = msg.getContent();  
  12.  
  13. // Verify that the message is not multipart.  
  14.  
  15. if ( o instanceof String ) {  
  16.  
  17. String body = (String)o;  
  18.  
  19. }  
  20.  
  21. //...  

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

发送一个消息

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

创建一个消息

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

  1. Store store = Session.getDefaultInstance().getStore();  
  2.  
  3. Folder[] folders = store.list(Folder.SENT);  
  4.  
  5. Folder sentfolder = folders[0];  
  6.  
  7. Message msg = new Message(sentfolder);  

指定接收者

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

  1. try {  
  2.  
  3.   toList[0]= new Address("aisha.wahl@blackberry.com""Aisha Wahl");  
  4.  
  5. }  
  6.  
  7. catch(AddressException e)  
  8.  
  9. {  
  10.  
  11.     System.out.println(e.toString());  
  12.  
  13. }  

增加接收者

调用Message.addRecipients().

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

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

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

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

调用setFrom(Address)

  1. Address from = new Address("scott.mcpherson@blackberry.com",  
  2.  
  3. "Scott McPherson");  
  4.  
  5. msg.setFrom(from);  

增加一个主题行

调用setSubject(String).

  1. msg.setSubject("Test Message"); 

指定消息内容

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

  1. try 
  2.  
  3. {  
  4.  
  5.     msg.setContent("This is a test message.");  
  6.  
  7. }  
  8.  
  9. catch(MessagingException e)  
  10.  
  11. {  
  12.  
  13.     System.out.println(e.getMessage());  
  14.  
  15. }  

发送消息

调用Transport.send(Message).

  1. try {  
  2.  
  3. Transport.send(msg);  
  4.  
  5. }  
  6.  
  7. catch(MessagingException e) {  
  8.  
  9.     System.out.println(e.getMessage());  
  10.  
  11. }  

回复消息

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

  1. Store store = Session.waitForDefaultSession().getStore();  
  2.  
  3. Folder[] folders = store.list(INBOX);  
  4.  
  5. Folder inbox = folders[0];  
  6.  
  7. Message[] messages = folder.getMessages();  
  8.  
  9. if( messages.length > 0 ) {  
  10.  
  11.     Message msg = messages[0];  
  12.  
  13. }  
  14.  
  15. Message reply = msg.reply(true);  
  16.  
  17. Transport.send(reply);  

转发一个消息

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

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

  1. Message fwdmsg = msg.forward(); 

增加接收者

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

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

指定消息内容

调用setContent(String).

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

  1. try {  
  2.  
  3.     fwdmsg.setContent("This is a forwarded message.");  
  4.  
  5. }  
  6.  
  7. catch(MessagingException e) {  
  8.  
  9.     System.out.println(e.getMessage());  
  10.  
  11. }  

发送消息

调用Send(Message).

  1. try {  
  2.  
  3.     Transport.send(fwdmsg);  
  4.  
  5. }  
  6.  
  7. catch(MessagingException e) {  
  8.  
  9.     System.out.println(e.getMessage());  
  10.  
  11. }  
  12.  
  13. try 
  14.  
  15. {  
  16.  
  17.     Transport.send(fwdmsg);  
  18.  
  19. }  
  20.  
  21. catch(MessagingException e) {  
  22.  
  23.     System.out.println(e.getMessage());  
  24.  

代码实例

例:BasicMail.java

  1. /**  
  2.  
  3. * BasicMail.java  
  4.  
  5. * Copyright (C) 2001-2005 Research In Motion Limited.  
  6.  
  7. */ 
  8.  
  9. package com.rim.samples.docs.basicmail;  
  10.  
  11. import net.rim.blackberry.api.mail.*;  
  12.  
  13. import net.rim.blackberry.api.mail.event.*;  
  14.  
  15. import net.rim.device.api.system.*;  
  16.  
  17.  
  18.  
  19. public class BasicMail extends Application {  
  20.  
  21.     private Store store;  
  22.  
  23.     static void main (String args[]) {  
  24.  
  25.        BasicMail app = new BasicMail();  
  26.  
  27.        app.enterEventDispatcher();  
  28.  
  29.        }  
  30.  
  31.     BasicMail() {  
  32.  
  33.        Store store = Session.getDefaultInstance().getStore();  
  34.  
  35.        Folder[] folders = store.list(Folder.SENT);  
  36.  
  37.        Folder sentfolder = folders[0];  
  38.  
  39.        // Create message.  
  40.  
  41.        Message msg = new Message(sentfolder);  
  42.  
  43.        // Add TO Recipients.  
  44.  
  45.        Address toList[] = new Address[1];  
  46.  
  47.        try {  
  48.  
  49.            toList[0]= new Address(“scott.tooke@rim.com”, “Scott Tooke”);  
  50.  
  51.        }  
  52.  
  53.        catch(AddressException e) {  
  54.  
  55.            System.out.println(e.toString());  
  56.  
  57.        }  
  58.  
  59.        try {  
  60.  
  61.            msg.addRecipients(Message.RecipientType.TO, toList);  
  62.  
  63.        }  
  64.  
  65.        catch (MessagingException e) {  
  66.  
  67.            System.out.println(e.toString());  
  68.  
  69.        }  
  70.  
  71.         
  72.  
  73.        // Add CC Recipients.  
  74.  
  75.        Address ccList[] = new Address[1];  
  76.  
  77.        try {  
  78.  
  79.            ccList[0]= new Address("katie.laird@rim.com""Katie Laird");  
  80.  
  81.        }  
  82.  
  83.        catch(AddressException e) {  
  84.  
  85.            System.out.println(e.toString());  
  86.  
  87.        }  
  88.  
  89.         
  90.  
  91.        try {  
  92.  
  93.            msg.addRecipients(Message.RecipientType.CC, ccList);  
  94.  
  95.            }  
  96.  
  97.        catch (MessagingException e) {  
  98.  
  99.            System.out.println(e.toString());  
  100.  
  101.        }  
  102.  
  103.         
  104.  
  105.        // Add the subject.  
  106.  
  107.        msg.setSubject("A Test Email");  
  108.  
  109.         
  110.  
  111.        // Add the message body.  
  112.  
  113.        try {  
  114.  
  115.            msg.setContent("This is a test message.");  
  116.  
  117.        }  
  118.  
  119.        catch(MessagingException e)  
  120.  
  121.        {  
  122.  
  123.            // Handle messaging exceptions.  
  124.  
  125.        }  
  126.  
  127.         
  128.  
  129.        // Send the message.  
  130.  
  131.        try {  
  132.  
  133.            Transport.send(msg);  
  134.  
  135.            }  
  136.  
  137.        catch(MessagingException e) {  
  138.  
  139.            System.out.println(e.getMessage());  
  140.  
  141.            }  
  142.  
  143.        System.out.println("Email sent successfully.");  
  144.  
  145.        System.exit(0);  
  146.  
  147.        }  
  148.  
  149.     }  

管理文件夹

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

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

列出mailbox store的文件夹

调用Store.List().

  1. Folder[] folders = store.list(); 

根据类型获取文件夹数组

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

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

搜索获取文件夹数组

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

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

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

根据名称获取一个文件夹

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

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

根据ID获取一个文件夹

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

  1. Folder[] folders = store.list();  
  2.  
  3. long id = folders[0].getId();  
  4.  
  5. Folder f2 = store.getFolder(id);  
  6.  

归档(File)消息

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

  1. Message msg = new Message();  
  2.  
  3. //...  
  4.  
  5. Folder folder = store.getFolder("Inbox");  
  6.  
  7. folder.appendMessage(msg);  
  8.  

管理附件

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

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

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

注册接受的MIME类型

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

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

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

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

  1. public String menuString() {  
  2.  
  3.     return "Custom Attachment Viewer";  
  4.  
  5. }  

定义附件处理

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

  1. public void run(Message m, SupportedAttachmentPart p) {  
  2.  
  3.     // Perform processing on data.  
  4.  
  5.     Screen view = new Screen();  
  6.  
  7.     view.setTitle(new LabelField("Attachment Viewer"));  
  8.  
  9.     view.add(new RichTextField(new String((byte[])p.getContent())));  
  10.  
  11. }  

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

注册一个附件处理器

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

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

  1. AttachmentHandlerManager m = AttachmentHandlerManager.getInstance();  
  2.  
  3. CustomAttachmentHandler ah = new CustomAttachmentHandler();  
  4.  
  5. m.addAttachmentHandler(ah);  

获取附件

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

获取附件内容

调用getContent().

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

获取附件信息

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

  1. public void run(Message m, SupportedAttachmentPart p) {  
  2.  
  3.      ...  
  4.  
  5.      String name = p.getName();  
  6.  
  7.      int size = p.getSize();  
  8.  
  9.     }  

发送一个带有附件的消息

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

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

  1. MultiPart multipart = new MultiPart(); // Default type of multipart/mixed.  
  2.  
  3. SupportedAttachmentPart attach =  
  4.  
  5.     new SupportedAttachmentPart( multipart, "application/x-example""filename", data);  
  6.  
  7. multipart.addBodyPart(attach); // Add the attachment to the multipart.  
  8.  
  9. msg.setContent(multipart);  
  10.  
  11. Transport.send(msg); // Send the message.  
  12.  

 【编辑推荐】

  1. BlackBerry应用开发者指南 使用受控API
  2. 在NetBeans Java ME polish环境下开发BlackBerry应用
  3. 简介RIM最新官方BlackBerry JDE 4.7
  4. 简介BlackBerry API
  5. Java语言编写BlackBerry应用程序
责任编辑:佚名 来源: 10086
相关推荐

2011-04-13 13:38:57

选项APIBlackBerry

2011-04-13 11:31:06

PIM APIBlackBerry

2011-04-02 13:44:08

2011-04-14 10:05:16

BlackBerry

2011-04-14 10:03:32

UI组件BlackBerry

2011-04-13 14:10:27

.alx文件BlackBerry

2011-04-14 10:34:08

BlackBerry

2010-05-22 16:57:09

BlackBerry开

2022-01-17 19:34:43

SentryWeb APISentry API

2011-07-19 09:51:32

性能优化Designing FAndroid

2011-04-18 11:00:34

使用音频BlackBerry

2011-02-16 16:45:23

MWCRIMBlackBerry

2011-04-26 10:19:46

BlackBerry

2018-03-27 23:25:40

Paddle

2013-08-29 13:41:42

Windows 8.1

2020-07-15 07:00:00

移动应用开发者指南

2011-04-15 15:16:28

使用图像对象画图BlackBerry

2021-12-31 18:35:40

监控Sentry开发

2024-02-01 09:37:42

Kubernetes服务网格• 命令

2019-08-16 10:55:37

开发者技能AI
点赞
收藏

51CTO技术栈公众号