BlackBerry應(yīng)用開(kāi)發(fā)者指南 Mail API
前不久我們給大家介紹過(guò)《BlackBerry應(yīng)用開(kāi)發(fā)者指南 使用受控API》,本文我們將介紹《BlackBerry應(yīng)用開(kāi)發(fā)者指南 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包中.它允許應(yīng)用程序使用消息應(yīng)用程序發(fā)送,接收和訪問(wèn)消息..
(注:BlackBerry mail API提供訪問(wèn)消息列表里的消息的能力,但不能訪問(wèn)其他類型的消息,例如短消息,PIN消息,或者電話呼叫記錄.為了訪問(wèn)電話呼叫記錄,使用電話呼叫記錄的API(net.rim.blackberry.phonelogs).)
當(dāng)你的應(yīng)用程序首先訪問(wèn)mail API時(shí),檢查一個(gè)NoClassDefFoundEorror!.如果系統(tǒng)管理員使用程序控制限制訪問(wèn)mail API,此錯(cuò)誤將拋出.
類
描述
Session
本類為消息操作表現(xiàn)了一個(gè)抽象模型.它提供訪問(wèn)消息服務(wù),存儲(chǔ),以及傳輸?shù)哪芰?應(yīng)用程序獲取一個(gè)新的Session對(duì)發(fā)送或接收消息..
Store
本類模型化BlackBerry設(shè)備的底層消息存儲(chǔ).為了獲得一個(gè)Store實(shí)例,調(diào)用Session實(shí)例.
Transport
本類代表了消息傳輸協(xié)議.
消息
一個(gè)Message對(duì)象包含了一組屬性,例如主題(subject),發(fā)送者(sender),接收者(recipients),以及消息體(它的內(nèi)容).為獲取更多消息,參看14頁(yè)的”多部分消息”.
下面的類和接口定義了支持的屬性:
類或接口
描述
Address
本類代表了一個(gè)消息,ftp,http,或來(lái)自于(from),回復(fù)(reply to),接收屬性以及消息體里的wap地址.Address類包含一些字段來(lái)存儲(chǔ)完全許可的地址字符串,例如aisha.wahl@blackberry.com和顯示名.
Header
本類定義了支持的消息頭字段,例如 TO,FROM,以及DATE.
Message.Flag
本接口定義了消息標(biāo)記,例如MOVED,OPENED,或SAVED.
Message.Icons
本接口定義了多種狀態(tài)圖標(biāo)的字符串表現(xiàn)形式,例如一個(gè)已發(fā)送消息的檢查標(biāo)記.
Message.RecipientType
本接口定義了支持的接收類型,例如TO,CC或BCC.
Message.Status
本接口為發(fā)送和接收消息定義了狀態(tài)選項(xiàng),例如RX_RECEIVED,EX_ERROR,TX_SENT,以及TX_READ.
多部分消息(Multipart messages)
Mail API支持多部分消息.Multipart抽象類為一個(gè)或多個(gè)BodyPart對(duì)象提供一個(gè)容器.Multipart提供獲取和設(shè)置其子部分的方法.
每個(gè)BodyPart由消息頭字段(屬性)以及內(nèi)容(消息體).Mail API提供四個(gè)BodyPart的實(shí)現(xiàn).
類
描述
ContactAttachmentPart
本類代表了一個(gè)地址卡(address card)附件部分.使用javax.microedition.pim.Contact接口.為獲得更多信息,參看27頁(yè)的”使用地址本”.
TextBodyPart
本類代表了一個(gè)內(nèi)容的消息體,此內(nèi)容為text/plain類型.你可使用本類創(chuàng)建text/plain部分的多部分消息.
UnsupportedAttachmentPart
本類代表了一個(gè)不支持的附件部分.你不能實(shí)例化此類.內(nèi)容類型一直為application/octet-stream.
SupportedAttachmentPart
本壘代表了一個(gè)支持的附件部分,對(duì)于此,在BlackBerry設(shè)備上由一個(gè)已注冊(cè)的附件處理器.
消息存儲(chǔ)
Folder類代表了一個(gè)本地郵件箱文件夾.定義了多種文件夾類型,包括INBOX,OUTBOX,SENT以及OTHER.你可以使用這些文件夾類型為獲取或保存消息獲取文件夾.
Store類模型化BlackBerry設(shè)備的底層消息存儲(chǔ),并提供方法查找和獲取文件夾.文件夾以層次存在,正如下面例子中的描述一樣:
Mailbox - Aisha Wahl
Inbox
Projects
In Progress
Complete
Personal
一個(gè)標(biāo)準(zhǔn)的分隔符在層次結(jié)果里獨(dú)立每個(gè)文件夾,你可使用getSeperator()來(lái)得到它.你也可以列出Store對(duì)象里的所有文件夾,列出文件夾下的子文件夾,或者基于查詢字符串查找一個(gè)文件夾.
Folder類定義了一些方法獲取消息,或子文件夾,以及保存和刪除消息.
(注:多個(gè)Folder實(shí)例可以引用相同的BlackBerry設(shè)備文件夾.這樣,你可以一直調(diào)用相同F(xiàn)older對(duì)象的addFolderListener()以及removeFolderListener().使用Folder.equals()判斷是否2個(gè)Folder對(duì)象引用了相同的folder.)#p#
Mail事件
BlackBerry mail事件包(net.rim.blackberry.api.mail.event)定義了下面的消息事件以及每個(gè)事件的監(jiān)聽(tīng)者:
事件
描述
FolderEvent
當(dāng)文件夾里的一個(gè)消息增加或刪除時(shí)此事件觸發(fā).
MessageEvent
當(dāng)一個(gè)消息改變(消息體,消息頭,或標(biāo)記)時(shí)此事件觸發(fā).
StoreEvent
當(dāng)一個(gè)消息以批處理(例如,當(dāng)BlackBerry和桌面同步時(shí))的形式加入到消息Store里,或從消息Store里刪除,此事件觸發(fā).
MailEvent類是這些mail事件類的基類.它定義了一個(gè)抽象的dispatch()方法,為每個(gè)事件調(diào)用合適的監(jiān)聽(tīng)者方法.
EventListener接口為FolderListener和MessageListener接口提供一個(gè)通用接口.
監(jiān)聽(tīng)者
可用對(duì)象
FolderListener
可以將此類型加入到Folder或Store對(duì)象中.
MessageListener
可以將此類型加入到Message對(duì)象中.
StoreListener
可以將此類型加入到Store對(duì)象中.
操作消息
接收消息通知
FolderListener和StoreListener接口的實(shí)現(xiàn)允許你的應(yīng)用程序接收消息通知.
- public class MailTest implements FolderListener, StoreListener { ... }
增加一個(gè)監(jiān)聽(tīng)者到消息Store
為了監(jiān)聽(tīng)消息存儲(chǔ)事件,例如同步,獲取一個(gè)Store對(duì)象,并將一個(gè)StoreListener實(shí)例加給它.
- try {
- Store store = Session.waitForDefaultSession().getStore();
- }
- catch (NoSuchServiceException e) {
- System.out.println(e.toString());
- }
- store.addStoreListener(this);
當(dāng)消息以批處理的形式增加和刪除時(shí),StoreListener.batchOperation()的實(shí)現(xiàn)定義了應(yīng)用程序的行為.例如,你的應(yīng)用程序可能檢查任何它引用的對(duì)象是否刪除.
- void batchOperation(StoreEvent e)
- {
- // Perform action when messages added or removed in batch operation.
- }
增加一個(gè)監(jiān)聽(tīng)者給文件夾
為了監(jiān)聽(tīng)一個(gè)文件夾事件,例如將一個(gè)消息加入到一個(gè)特定的文件夾,為你想接收新消息通知的文件夾獲取一個(gè)Folder對(duì)象.將一個(gè)FoldListener實(shí)例加到此文件夾對(duì)象.
- Folder[] folders = store.list(Folder.INBOX);
- Folder inbox = folders[0];
- inbox.addFolderListener(this);
當(dāng)文件夾事件發(fā)生時(shí), 實(shí)現(xiàn)FolderListener.messagesAdded() 和FolderListener.messagesRemoved()完成操作.例如,你可實(shí)現(xiàn)這些方法維護(hù)任何引用你的應(yīng)用程序必須指定的mail文件夾的一致性.
- void messagesAdded(FolderEvent e) {
- // Perform processing on added messages.
- }
- void messagesRemoved(FolderEvent e)
- {
- // Perform processing on removed messages.
- }
接收一個(gè)消息的更多部分
缺省的,發(fā)送一個(gè)消息的第一部分(一般約2KB)到BlackBerry設(shè)備上.調(diào)用消息體部分上的hasMore()判斷在服務(wù)器上是否有更多的數(shù)據(jù).調(diào)用moreRequestSent()判斷是否一個(gè)獲取更多數(shù)據(jù)的請(qǐng)求已經(jīng)發(fā)出.調(diào)用more()請(qǐng)求一個(gè)消息的更多部分.
- if (( bp.hasMore())&&(! bp.moreRequestSent())
- {
- Transport.more(bp, true);
- }
more()的第二個(gè)參數(shù)是一個(gè)Boolean值,它指定了是否僅獲取消息體部分的下一部分(false),或者獲取所有剩下的部分(true).
打開(kāi)一個(gè)消息
獲取消息存儲(chǔ)以及包含消息的文件夾:
- Store store = Session.waitForDefaultSession.getStore();
- Folder folder = Store.getFolder("SampleFolder");
從文件夾獲取消息對(duì)象.迭代數(shù)組,并獲取信息,例如發(fā)送者,主題,顯示給用戶.
- Message[] msgs = folder.getMessages();
當(dāng)用戶從列表中選擇一個(gè)消息時(shí),調(diào)用Message對(duì)象上的方法獲取合適的字段以及消息體內(nèi)容顯示給用戶.
- 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;
- }
- //...
(注:調(diào)用一個(gè)消息上的getBodyText()方法獲取普通文本內(nèi)容作為一個(gè)String.如果消息不包含普通文本,方法將返回null.)
發(fā)送一個(gè)消息
為發(fā)送消息,使用一個(gè)Transport對(duì)象,它代表了消息傳輸協(xié)議.
創(chuàng)建一個(gè)消息
創(chuàng)建一個(gè)Message對(duì)象,并指定一個(gè)文件夾拷貝已發(fā)送的消息.
- Store store = Session.getDefaultInstance().getStore();
- Folder[] folders = store.list(Folder.SENT);
- Folder sentfolder = folders[0];
- Message msg = new Message(sentfolder);
指定接收者
創(chuàng)建一個(gè)Address對(duì)象的數(shù)組,然后將每個(gè)地址加入到數(shù)組中.你的應(yīng)用程序應(yīng)該捕獲一個(gè)AddressException異常,如果地址無(wú)效,它將會(huì)拋出:
- try {
- toList[0]= new Address("aisha.wahl@blackberry.com", "Aisha Wahl");
- }
- catch(AddressException e)
- {
- System.out.println(e.toString());
- }
增加接收者
調(diào)用Message.addRecipients().
將接收者類型(TO,CC,或BCC),以及地址數(shù)組作為參數(shù)提供給此方法.
如果你的消息有多個(gè)接收者類型,每個(gè)只調(diào)用一次addRecipients()方法.
- msg.addRecipients(Message.RecipientType.TO, toList);
指定一個(gè)發(fā)送者的姓名和internet消息地址
調(diào)用setFrom(Address)
- Address from = new Address("scott.mcpherson@blackberry.com",
- "Scott McPherson");
- msg.setFrom(from);
增加一個(gè)主題行
調(diào)用setSubject(String).
- msg.setSubject("Test Message");
指定消息內(nèi)容
調(diào)用setContent(String).一般來(lái)說(shuō),你的應(yīng)用程序從用戶輸入的文本域里獲取內(nèi)容.
- try
- {
- msg.setContent("This is a test message.");
- }
- catch(MessagingException e)
- {
- System.out.println(e.getMessage());
- }
發(fā)送消息
調(diào)用Transport.send(Message).
- try {
- Transport.send(msg);
- }
- catch(MessagingException e) {
- System.out.println(e.getMessage());
- }
回復(fù)消息
為了創(chuàng)建一個(gè)消息作為已存在消息的回復(fù),調(diào)用Message.reply(Boolean).作為此方法的參數(shù),指定true回復(fù)所有消息接收者,或設(shè)置false僅回復(fù)發(fā)送者.
- 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);
轉(zhuǎn)發(fā)一個(gè)消息
調(diào)用一個(gè)已存在Message對(duì)象的forward()方法.
(注:轉(zhuǎn)發(fā)消息的主題行會(huì)自動(dòng)設(shè)置為FW:<original_subject>.)
- Message fwdmsg = msg.forward();
增加接收者
創(chuàng)建地址數(shù)組,然后調(diào)用addRecipients(int, Address[]).
- Address toList[] = new Address[1];
- toList[0]= new Address("aisha.wahl@blackberry.com", "Katie Laird");
- fwdmsg.addRecipients(Message.RecipientType.TO, toList);
指定消息內(nèi)容
調(diào)用setContent(String).
<!--[if !vml]--><!--[endif]-->(注:你不能編輯轉(zhuǎn)化消息的文本, setContent()方法在轉(zhuǎn)化的消息前增加文本.)
- try {
- fwdmsg.setContent("This is a forwarded message.");
- }
- catch(MessagingException e) {
- System.out.println(e.getMessage());
- }
發(fā)送消息
調(diào)用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());
- }
代碼實(shí)例
例: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上調(diào)用getStore()獲取一個(gè)Store對(duì)象.
- Store store = Session.waitForDefaultSession().getStore();
列出mailbox store的文件夾
調(diào)用Store.List().
- Folder[] folders = store.list();
根據(jù)類型獲取文件夾數(shù)組
調(diào)用List(int).把文件類型作為參數(shù)提供給此方法.
- Folder[] folders = store.list(INBOX);
- Folder inbox = folders[0];
搜索獲取文件夾數(shù)組
為了獲取層次結(jié)構(gòu)上符合指定查詢字符串的所有文件夾,調(diào)用findFolder(String).
- Folder[] folders = store.findFolder("Inbox");
findFolder(String).方法返回一個(gè)與指定字符串匹配的文件夾數(shù)組,或者如果匹配的文件夾沒(méi)有找到,返回一個(gè)空的數(shù)組.
根據(jù)名稱獲取一個(gè)文件夾
調(diào)用getFolder(String).把文件夾的絕對(duì)路徑作為參數(shù).如果文件夾沒(méi)有找到, FolderNotFoundException異常將拋出.
- Folder folder = store.getFolder("Mailbox - Aisha Wahl/Inbox/Projects");
根據(jù)ID獲取一個(gè)文件夾
調(diào)用getID()獲取文件夾ID,然后調(diào)用ID作為參數(shù)的getFolder()方法.
- Folder[] folders = store.list();
- long id = folders[0].getId();
- Folder f2 = store.getFolder(id);
歸檔(File)消息
調(diào)用Folder對(duì)象的appendMessage(Message)方法.
- Message msg = new Message();
- //...
- Folder folder = store.getFolder("Inbox");
- folder.appendMessage(msg);
管理附件
Mail API 允許你在BlackBerry設(shè)備上打開(kāi)一個(gè)進(jìn)來(lái)的消息附件,并且可以創(chuàng)建一個(gè)發(fā)出去的附件.一個(gè)消息附件作為多部分消息的一個(gè)獨(dú)立BodyPart對(duì)象表現(xiàn).
創(chuàng)建一個(gè)自定義的附件處理器
AttachmentHandler接口的實(shí)現(xiàn)定義了一個(gè)自定義的附件處理器.
注冊(cè)接受的MIME類型
supports(String)的實(shí)現(xiàn)注冊(cè)一個(gè)附件處理器接受的附件的MIME類型.當(dāng)BlackBerry設(shè)備接收到一個(gè)附件時(shí),此方法被調(diào)用.
- public boolean supports(String contentType) {
- return (contentType.toLowerCase().indexOf("contenttype") != -1 ? true : false);
- }
定義一個(gè)相關(guān)菜單項(xiàng)字符串
在消息列表中,當(dāng)用戶選擇一個(gè)附件時(shí),menuString()的實(shí)現(xiàn)返回一個(gè)顯示的菜單項(xiàng)字符串.
- public String menuString() {
- return "Custom Attachment Viewer";
- }
定義附件處理
run()的實(shí)現(xiàn)完成了對(duì)附件的合理處理,并將附件顯示給用戶.
- 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())));
- }
(注: 當(dāng)在消息列表里選擇相應(yīng)的菜單項(xiàng)時(shí),調(diào)用run()方法.)
注冊(cè)一個(gè)附件處理器
AttachmentHandlerManager類控制附件是如何在BlackBerry設(shè)備上處理的.當(dāng)用戶打開(kāi)一個(gè)相關(guān)類型的附件時(shí),為了使消息應(yīng)用程序調(diào)用你的自定義附件,調(diào)用addAttachmentHandler()注冊(cè)你的附件處理器.
(注:BES附件服務(wù)在接收附件時(shí)有第一優(yōu)先級(jí),第三方附件處理器不能覆蓋缺省BlackBerry設(shè)備的行為.)
- AttachmentHandlerManager m = AttachmentHandlerManager.getInstance();
- CustomAttachmentHandler ah = new CustomAttachmentHandler();
- m.addAttachmentHandler(ah);
獲取附件
SupportedAttachmentPart類代表了一個(gè)BlackBerry設(shè)備上對(duì)應(yīng)查看器的附件.在BlackBerry設(shè)備上.,一個(gè)沒(méi)有查看器的附件作為一個(gè)UnsupportedAttachmentPart表現(xiàn).
獲取附件內(nèi)容
調(diào)用getContent().
- String s = new String((byte[])p.getContent());
獲取附件信息
SupportedAttachmentPart類提供多個(gè)方法獲取附件信息.下面的例子調(diào)用getName()和getSize()獲取附件名和大小.
- public void run(Message m, SupportedAttachmentPart p) {
- ...
- String name = p.getName();
- int size = p.getSize();
- }
發(fā)送一個(gè)帶有附件的消息
通過(guò)創(chuàng)建一個(gè)新的Multipart對(duì)象創(chuàng)建一個(gè)多部分信息.為了創(chuàng)建每個(gè)附件組件,創(chuàng)建一個(gè)SupportedAttachmentPart的對(duì)象,把Multipart作為它的父組件.為了把每個(gè)SupportedAttachmentPart增加到Multipart,調(diào)用對(duì)象上的addBodyPart(SupportedAttachmentPart).
當(dāng)調(diào)用Message對(duì)象的setContent(Multipart)時(shí),將 Multipart對(duì)象作為參數(shù)傳入.
- 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.
【編輯推薦】