1 概述
郵件解析庫API完全使用面向對象技術設計，使用C++語言開發的用於郵件解析和組裝的庫。它提供了一些類用來解析和組裝Internet郵件，如MimeMessage和MimeBodyPart，用於Internet郵件協議實現並且遵循RFC822和RFC2045規範。這些API庫用於應用程序的開發。
1.1 術語
RFC：Request For Comments, 請求註解, Internet標準(草案)
MIME：Multipurpose Internet Mail Extension protocol, 多用途的網際郵件擴充協議
2 Hello World !
以下是一個郵件解析庫的簡單程序，說明使用面向對象設計的API解析郵件的方法：
void main()
{
char *emaildata = loademailfile(“helloworld.eml”);
MimeMessage email(emaildata);
FastString subject, from, bodytext;
InternetAddress addr;
email.getSubject(subject);
email.getFrom(addr); addr.toString(From);
email.getTextPlain(bodytext);
printf(“Subject: %s/nFrom: %s/nBody: %s/n”,
subject.c_str(), from.c_str(), bodytext.c_str());
free(emaildata);
}
3 郵件解析庫的類
郵件解析庫包含一系列的類，主要有MimeMessage（郵件實現類）、MimeBodyPart（郵件正文段體類）、MimeMultipart（郵件多部段體類）、InternetHeaders（郵件頭類）、InternetAddress（郵件地址類）和ContentType（段體類型類）等。解析和組裝郵件主要使用這些類進行組裝和分解。
現在介紹一下最主要的也是提供主要的調用接口API的類MimeMessage。
MimeMessage提供了一系列的方法供調用者使用，如定義了獲取地址信息和獲取郵件正文內容的結構（可以爲具體的數據也可以爲一個MimeMultipart對象），用來實現RFC822和MIME規範。
一個MimeMessage對象裏保存了一個郵件內容數據（Content），以及一些記錄特定的郵件地址信息（如發件人（Sender）和收件人（recipients））的屬性（InternetHeaders）。還有關於這封郵件的結構信息（structural information），以及它的郵件主體（body）的段體類型（Content-Type）。
下面用圖來描述一個MimeMessage對象內部可能的結構：
4 示例
4.1 解析郵件
下面的例子詳細說明如何用郵件解析庫API解析一封郵件：
/**
* 郵件源文數據通過參數傳遞
* @param msg 指向郵件源文的字符串指針
* @param len 郵件源文的長度
*/
void parseMessage(const char *msg, const int len)
{
// 定義一個MimeMessage郵件對象用於解析
// 郵件對象使用指向郵件源文的字符串指針和長度的參數構造
// 也可使用 MimeMessage email(msg)構造，傳入len參數的目的是爲了節省再做一次
// strlen()的時間，因爲有些郵件源文比較大。
// 備註：如果只獲取郵件頭，MimeMessage就只解析郵件頭數據，不會解析郵件正文。
MimeMessage Email(msg, len);
// 獲取發信時間，此時間UTC時間
// Coordinated Universal Time (UTC, formerly referred to as "Greenwich Mean Time")
time_t senttm = email.getSentDate();
// 定義存儲郵件主題的字符串變量，郵件解析庫均使用FastString做爲字符串處理
FastString subject;
// 調用MimeMessage類的getSubject()方法獲取郵件主題，內容放進subject變量裏
Email.getSubject(subject);
// 打印輸出主題，c_str()方法是標準的獲取字符串內容指針的方法
printf(“Subject: %s/n”, subject.c_str());
// 定義存儲發信人地址的變量，這裏InternetAddress是處理郵件地址的類
InternetAddress from;
// 調用MimeMessage類的getFrom()方法獲取郵件發信人地址
Email.getFrom(from);
// 輸出地址發信人地址，personal是郵件地址的名字，address是地址
printf(“From: /”%s/” <%s>/n”, from.personal(), from.address());
// 定義存儲發信人地址的變量，這裏用InternetAddressArray是因爲收件人可能有多個
InternetAddressArray toAddrs;
// 調用MimeMessage類的getTo()方法獲取所有的收件人地址信息
// 獲取其他地址如 抄送者用getCc() 密送者用getBcc() 參考後面的MimeMessage方法列表
Email.getTo(toAddrs);
// 由於InternetAddressArray是一個FastArray數組類，所以採用以下方式逐個輸出
// 定義遍歷數組的迭代器（這是面向對象的設計，類似STL庫容器的迭代器用法）
InternetAddressArrayIterator it(toAddrs);
// 判斷迭代器是否走到數組的末尾，否則進入循環
while( !it.done() ) {
// 輸出郵件地址，迭代器相當於指向InternetAddress的指針
printf(“To: /”%s/” <%s>/n”, it->personal(), it->address());
// 跌打器向前移動一位
it.advance();
}
// 數組的遍歷也可採用如下傳統方式
for( int i = 0; i < toAddrs.size(); i ++ ) {
// 由於[]操作符不計算數組範圍，所以不建議如此使用。儘量使用迭代器，
// 除非是想直接取得第n個地址
printf(“To: /”%s/” <%s>/n”, toAddrs[i].personal(),toAddrs[i].address());
}
// 獲取其他郵件Header行的內容
FastString xline;
Email.getHeader(“X-Priority”, xline);
Printf(“X-Priority: %s/n”, xline.c_str());
// 獲取郵件純文本正文。由於每一封郵件都可能同時包含一個純文本正文體和一個
// HTML正文體，所以它們單獨獲取
FastString
Email.getTextPlain(
printf(“BodyTextPlain: %s/n”,
// 也可以這樣同時獲取純文本正文的字符集編碼方式，以供調用者根據它來
// 選擇不同的字符集顯示給用戶。getTextHtml()也類似。
FastString charset;
Email.getTextPlain(
// 獲取郵件HTML正文內容。
FastString
Email.getTextHtml(
printf(“BodyTextHtml: %s/n”,
// 獲取郵件所有附件的名字。
FastStringArray filenames;
Email.getAllAttachmentFilenames(filenames);
// 遍歷查找名字跟其他Array用法一樣
// 獲取指定附件文件名的附件內容，如果有重複的名字的附件將只返回第一個相同
// 名字的附件數據。要獲取其他所有附件，請參考下面的方法。
FastString filename(“attr1.jpg”), content;
Email.getAttachment(filename, content);
// 獲取郵件所有附件。
AttachmentPtrArray attachments;
Email. getAllAttachments(attachments);
// 附件總數
int attnum = attachments.size();
// 遍歷所有附件
for( size_t i = 0; i < attachments.size(); i ++ )
{
// 獲得此附件PART的指針，注意：不能free或其他直接修改指針內容的操作。
MimeBodyPart *part = attachments[i];
if( part == NULL )
continue;
FastString filename, content;
// 獲取此附件文件名
part->getFileName(filename);
// 獲取此附件內容，已解碼
part->getContent(content);
}
// 獲取郵件的內聯資源附件的名字及內容
// 方法與獲取普通附件一樣，只不過調用getRelatedAttachment()等。
// filename參數換成cid （Content-ID）
// 獲取郵件所有內聯資源附件的名字。
FastStringArray cids;
Email.getAllRelatedAttachmentCIDs(cids);
// 遍歷查找名字跟其他Array用法一樣
// 獲取指定內聯資源附件文件名的附件內容，如果有重複的名字的附件將只返回第一個相同
// 名字的附件數據。要獲取其他所有附件，請參考下面的方法。
FastString cid(“3334776372$1097735850$0600030@local”), content;
Email.getRelatedAttachment(cid, content);
// 獲取郵件所有內聯資源附件。
AttachmentPtrArray attachments;
Email. getAllRelatedAttachments(attachments);
// 內聯資源附件總數
int attnum = attachments.size();
// 遍歷所有內聯資源附件
for( size_t i = 0; i < attachments.size(); i ++ )
{
// 獲得此附件PART的指針，注意：不能free或其他直接修改指針內容的操作。
MimeBodyPart *part = attachments[i];
if( part == NULL )
continue;
FastString filename, cid, content;
// 獲取此內聯資源附件CID
Part->getContentID(cid);
// 獲取此內聯資源附件文件名
part->getFileName(filename);
// 獲取此內聯資源附件內容，已解碼
part->getContent(content);
}
}
4.2 組裝郵件
下面的例子詳細說明如何用郵件解析庫API組裝一封郵件：
/**
* 郵件源文數據通過參數傳遞
* @param emaildata 存儲組裝好的郵件源文的字符串
*/
void createMessage(FastString &emaildata)
{
// 定義一個MimeMessage郵件對象用於組裝
MimeMessage Email;
// 設置標題
Email.setSubject(“test mail”);
// 設置發件人
Email.setSender(“[email protected]”);
// 也可以，後面是地址的名字
Email.setSender(“[email protected]”, “測試帳號”);
// 添加收件人
Email.addTo(“[email protected]”);
Email.addTo(“[email protected]”, “收件人
.. . .
// 添加抄送者地址
Email.addCc(“[email protected]”);
Email.addCc(“[email protected]”, “收件人
.. . .
// 添加密送者地址
Email.addBcc(“[email protected]”);
Email.addBcc(“[email protected]”, “收件人
// 設置特殊的郵件頭
Email.addHeader(“X-Mailer”, “xmail
// 設置純文本正文，缺省編碼gb2312（環境變量控制，後面會講到如何配置郵件解析環境）
Email.setTextPlain(“This is a test mail created by xmail”);
// 也可以這樣指定編碼方式
Email.setTextPlain(“This is a mail encoded by gbk”, “gbk”);
// 當然也可以這樣
FastString bodytext;
.. .. .. // bodytext可以從其他地方讀取
Email.setTextPlain(bodytext);
// 或者這樣
Email.setTextPlain(bodytext, “gbk”);
// 設置HTML正文， 跟純文本正文類似。
// 備註：一封郵件可以同時包含一個純文本正文和一個HTML正文供閱讀器選擇顯示
Email.setTextHtml(“<HTML><BODY>This is a test mail</BODY></HTML>”);
// 也可以這樣指定編碼方式
Email.setTextHtml(“<HTML><BODY>This is a mail encoded by gbk</BODY></HTML>”, “gbk”);
// 當然也可以這樣
FastString bodyhtml;
.. .. .. // bodyhtml可以從其他地方讀取
Email.setTextHtml(bodyhtml);
// 或者這樣
Email.setTextHtml(bodyhtml, “gbk”);
// 添加附件
FastString filename(“attr1.jpg”), filedata;
.. .. .. //filename 和 filedata 可以從其他地方讀取
Email.addAttachment(filedata, filename, ”image/jpeg”);
// 也可以這樣
Email.addAttachment(filedata, “attr1.jpg”, “image/jpeg”);
// 注意：如果不指定後面第三個參數，即附件的MimeType類型
// MimeMessage將根據filename的擴展名到MimeTypes數據映射表中查找。
// 備註：MimeTypes映射表可以配置，參考後面的“配置郵件解析環境”
// 所以也可以這樣調用
Email.addAttachment(filedata, filename);
Email.addAttachment(filedata, “attr1.jpg”);
// 添加內嵌資源附件，與添加普通附件類似。
// 注意：必須要先設置郵件的HTML正文後才能添加內嵌資源附件，否則也添不進去
// src是資源附件在HTML正文裏的URL，包括路徑和文件名
// cid是添加成功後資源附件的CID值
// 返回值count是資源附件在HTML裏引用的個數
FastString src(“/images/attr1.jpg”), cid, filedata;
.. .. .. //src 和 filedata 可以從其他地方讀取
Int count = Email.addRelatedAttachment(filedata, src, cid, ”image/jpeg”);
// 同樣也可以這樣
Count=Email.addRelatedAttachment(filedata, “/images/attr1.jpg”, cid, “image/jpeg”);
Count = Email.addRelatedAttachment(filedata, “/images/attr1.jpg”, cid);
Count = Email.addRelatedAttachment(filedata, “/images/attr1.jpg”, cid);
// 注意：如果重新覆蓋了郵件HTML正文即再次調用setTextHtml()，
// MimeMessage將會自動遍歷所有資源附件，刪除沒有再引用的資源附件。
}
4.3 修改郵件
下面的例子詳細說明如何用郵件解析庫API修改一封郵件：
/**
* 郵件源文數據通過參數傳遞
* @param emaildata 存儲組裝好的郵件源文的字符串
*/
void createMessage(FastString &emaildata)
{
// 定義一個MimeMessage郵s件對象用於修改
// 方法與上面的解析和組裝類似，解析和組裝調用的方法都可以調用
MimeMessage Email(emaildata);
// 下面介紹一下刪除的功能
// 清除郵件純文本正文
Email.removeTextPlain();
// 清楚郵件HTML正文
Email.removeTextHtml();
// 刪除指定文件名的附件
FastString filename(“attr1.jpg”);
Email.removeAttachment(filename);
Email.removeAttachment(“attr1.jpg”);
// 刪除指定位置的附件，getAllAttachments()獲取的數組中的位置，從0開始
Email.removeAttachment(2);
// 刪除所有附件
Email.removeAllAttachments();
// 刪除所有內嵌資源附件
Email.removeAllRelatedAttachments();
// 還可以調用上面的組裝方法更新指定的數據
// 更新郵件源文數據
// 注意：一定這樣重新定義變量存儲新源文數據
FastString newdata;
Email.toString(newdata);
// 更新返回值字符串
Emaildata = newdata;
}
4.4 高級功能
郵件解析引擎庫API還有更復雜更強大的高級功能，可以組裝和解析出任何符合RFC822和RFC2045的郵件。請參考解析庫裏的測試程序mimeutils.cpp和相關的文檔。