Android（OPhone） 学习笔记3 - Mail API 的使用

     今天是第三天，我来学习一下官方提供的最复杂应用性最强的一个例子，演示了邮件功能的实现。全部例子来源于官方的sample文件。

一、整体结构

通过观察工程的整体结构我们可以看到它具有三个java文件，由于该程序除了主程序之外，还具有另外一个配置帐号信息的界面，所以使用ConfigAccountLayout.java文件来描述。

二、主界面介绍
public class MailAPIDemoActivity extends Activity implements POP3ProcessListener
该程序应用了POP3ProcessListener的接口，具有java基础的朋友们对此应该不会陌生。该接口要求实现void receivedMailMessage(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
邮件常规异常
     最后，就介绍到这里，通过本例的学习，使我对OPhone 手机开发有了更加深入的理解。