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.
【編輯推薦】
