Android- Mail API 的使用

這是官方提供的最複雜應用性最強的一個例子，示範了郵件功能的實現。本篇為OPhone入門級學習筆記的最後一篇，全部例子來源於官方的sample檔案。本篇結束後，將會推出略微複雜的專題講解，感謝大家關注。

一、整體結構

通過觀察工程的整體結構我們可以看到它具有三個java檔案，由於該程式除了主程式之外，還具有另外一個配置帳號資訊的介面，所以使用ConfigAccountLayout.java檔案來描述。

二、主介面介紹
public class MailAPIDemoActivity extends Activity implements POP3ProcessListener
該程式應用了POP3ProcessListener的介面，具有java基礎的朋友們對此應該不會陌生。該介面要求實現voidreceivedMailMessage(BaseAccountInfo accountInfo, CMMail m)函數，作為收到郵件訊息的響應。
該函數內容為： if (mail != null) printLog("Received new mail: \n" + mail.toString());

還有若干變數常量的定義：
// 這裡定義了帳號的基本資料，是OPhone內建的郵件功能類
public BaseAccountInfo accountInfo;
// 該Listener可以關注郵件任務狀態
public MailEventListenerClass mailEventListener;
public View mainView;

public static final String TAG = "MailExample";
public static final String TAG_CMMail = "CMMail";
public static final String TAG_POP3ProcessListener = "POP3ProcessListener: ";

接下來是onCreate代碼：

在主介面首先定義了mainView和textView，此外，還有郵件訊息的Listener和帳號資訊。
接下來，定義了三個按鈕，一個是配置郵件，一個是內送郵件，一個是發送郵件。

1.配置郵件
Button configButton = (Button) findViewById(R.id.button_config_account);
configButton.setOnClickListener(new Button.OnClickListener() {
public void onClick(View v) {
ConfigAccountLayout view = (ConfigAccountLayout) ConfigAccountLayout.inflate(
MailAPIDemoActivity.this, R.layout.config_account, null);
view.setAccountInfo(accountInfo);
setContentView(view);
}
});
從上面代碼我們可以看到，按鈕代碼主要流程是：按鈕定義、建立Listener、配置單擊事件、設定事件響應內容（如切換到ConfigAccountLayout）。在建立ConfigAccountLayout時，我們用到了inflate函數，它可以從一個已有的資源擴充產生一個新的view該函數定義如下：
View android.view.View.inflate(Context context, int resource, ViewGroup root)
setAccountInfo函數是在ConfigAccountLayout.java中定義的，用於設定賬戶資訊，在我們會在後面進行分析。最後將當前的視圖切換至配置郵件視圖。

2.內送郵件
Button popbutton = (Button) findViewById(R.id.button_pop);
popbutton.setOnClickListener(new Button.OnClickListener() {
public void onClick(View v) {
if (accountInfo == null) {
printLog("Please config account first!");
return;
}
printLog("Start fetch new mail...");
// 擷取伺服器郵件訊息
CMMailTaskController.getInstance().startFetchNewMessages(MailAPIDemoActivity.this,accountInfo,null, mailEventListener,MailAPIDemoActivity.this);
}
});
內送郵件的功能實現較容易理解，首先檢查賬戶配置，然後通過收郵件函數執行功能。

3.發送郵件
Button smtpbutton = (Button) findViewById(R.id.button_smtp);
smtpbutton.setOnClickListener(new Button.OnClickListener() {
public void onClick(View v) {
if (accountInfo == null) {
printLog("Please config account first!");
return;
}
try {
// 建立郵件執行個體
CMMail mail = new CMMail();
//添加發送地址
EditText inputTo = (EditText)MailAPIDemoActivity.this.findViewById(R.id.input_to);
String toAddress = inputTo.getText().toString();
if (toAddress == null || toAddress.length() == 0) {
printLog("Please input address first");
return;
}
CMMailAddress toadd = new CMMailAddress(null, toAddress);
mail.addToAddress(toadd);

// 設定郵件主題
mail.setSubject("OMS API Test Mail");

//設定郵件內容
mail.setBodyTxt("Hello!\nThis is a mail from OMS API Tester!");

// 建立發送列表
CMMail[] sendmails = new CMMail[] { mail };

// 開始發送訊息
CMMailTaskController.getInstance().startSendMessages(MailAPIDemoActivity.this,accountInfo, sendmails,mailEventListener);

printLog("Posted mail to: " + toadd.getAddress()+ "; Subject: " + mail.getSubject());

} catch (Exception e) {
printLog(TAG_POP3ProcessListener + e.toString());
Log.d(TAG, TAG_POP3ProcessListener + e.toString());
}
}
});
}

該主介面還包含了一個class，我們來分析郵件狀態響應：
public class MailEventListenerClass implements MailEventListener
它需要實現 MailEventListener介面，該介面函數內容如下：

事件分為三類：登入、收取郵件、收取帶附件郵件，具體事件的列表描述可以查看：http://www.ophonesdn.com/documentation/ophone/reference/ophoneapi/mail/oms/mail/MailBaseEvent.html

在主程式的最後，還有兩個函數，實現了列印日誌的功能。

putstring功能是將文本"text"插入到字串text中。作為在訊息佇列中Handler提取的關鍵字。

Handler可以處理和發送與訊息佇列相關的訊息或者運行對象。handleMessage是必須實現的介面，用於接收處理訊息。在該handlerlog裡面，將msg顯示到view中。在printlog中，sendMessage函數功能是添加訊息至訊息佇列尾部。

三、郵件帳號配置

郵件帳號配置功能在另外一個ConfigAccountLayout.java檔案中實現，它extends於RelativeLayout， 即它上面的組件的位置可以用和其他組件或者父親的相對位置來描述。context作為應用程式的全域環境，即ConfigAccountLayout.java使用MailAPIDemoActivity的context。

當View附加到一個表單上時,調用onAttachedToWindow方法，該方法完成：1.定義控制項，2.初始化帳號資訊，3.定義OK Cancel按鈕。這些代碼都很容易看懂，可以觀察到，ok按鈕中有函數getAccount。

該函數為OPhone內建函數，功能是將擷取的郵件配置參數進行寫入。每個函數的具體功能和參數可以參考：http://www.ophonesdn.com/documentation/ophone/reference/ophoneapi/mail/oms/mail/BaseAccountInfo.html

以下是配置介面運行結果：

四、補充資料

最後，貼一些郵件工具包的介紹，來自superzhang的翻譯，http://www.superzhang.com.cn/viewthread.php?tid=67&extra=page%3D1 ， API原始地址 http://www.ophonesdn.com/documentation/ophone/reference/ophoneapi/mail/oms/mail/package-summary.html

Package oms.mail
這個包提供了接收和發送郵件的所有API.

介面
MailEventListener
郵件事件監聽介面.
POP3ProcessListener
郵件接收介面.

類
BaseAccountInfo
賬戶資訊的基類，包含了所有參數的設定。
CMMail
包含了設定和擷取郵件各部分內容的一些方法。
CMMailAddress
郵件地址類，可以設定和擷取郵件地址。
CMMailBodyPart
郵件內容類別
CMMailTaskController
提供了一個執行個體來管理和運行郵件任務，例如接收和刪除郵件。
MailBaseEvent
郵件事件類別。
MailBaseEvent.TaskStatus
發送和內送郵件任務的狀態資訊。

異常
MailException
郵件常規異常