第六部分 fastmail的使用
C++通用框架的設計 作者：naven
1 fastmail介紹
郵件解析庫API完全使用面向對象技術設計，使用C++語言開發的用于郵件解析和組裝的庫。它提供了一些類用來解析和組裝Internet郵件，如MimeMessage和MimeBodyPart，用于Internet郵件協議實現并且遵循RFC822和RFC2045規范。這些API庫用于應用程序的開發。
RFC：Request For Comments, 請求注解, Internet標準(草案)
MIME：Multipurpose Internet Mail Extension protocol, 多用途的網際郵件擴充協議
郵件解析庫包含一系列的類，主要有MimeMessage（郵件實現類）、MimeBodyPart（郵件正文段體類）、MimeMultipart（郵件多部段體類）、InternetHeaders（郵件頭類）、InternetAddress（郵件地址類）和ContentType（段體類型類）等。解析和組裝郵件主要使用這些類進行組裝和分解。
fastmail主要有如下一些類
ContentDisposition MIME郵件頭 實現MIME郵件頭的ContentDisposition
ContentID MIME郵件頭 實現MIME郵件頭的ContentID
ContentType MIME郵件頭 實現MIME郵件頭的ContentType
MimeType MIME類型類 實現MIME的類型，記錄在ContentType里，如text/plain
hdr MIME郵件頭 實現MIME郵件頭HEADER行
HeaderTokenizer 郵件頭分解類 實現分解MIME郵件頭的各元素，如Content-Type的mimetype和各個參數。
IMimePart MIME郵件段體接口類 郵件段體類的基類
MimeBodyPart MIME郵件段體類 實現MIME郵件各個段體的類
MimeMessage MIME郵件類 MIME郵件主類
IMultipart 多部分接口類 多部分類的基類
MimeMultipart 多部分實現類 保存段體類對象的多部分容器類
InternetAddress MIME郵件地址類 實現MIME郵件地址的類
InternetHeaders MIME郵件頭部分類 實現保存MIME各郵件頭的容器類
MimeInitialization 郵件解析全局初始化類 實現初始化MIME郵件用到的各個全局變量
MimetypesFileTypeMap 郵件Mime類型映射類 實現郵件MimeType和FileType類型的映射表，用于查詢
MimeUtility MIME郵件分析工具類 實現郵件解析用到的各個解析工具函數
ParameterList 參數列表類 實現ContentType和ContentDisposition用到的參數列表
UniqueValue 郵件唯一值生成類 實現生成MIME郵件用到的唯一值的類，如boundary等
MimeMessage類
現在介紹一下最主要的也是提供主要的調用接口API的類MimeMessage。
MimeMessage提供了一系列的方法供調用者使用，如定義了獲取地址信息和獲取郵件正文內容的結構（可以為具體的數據也可以為一個MimeMultipart對象），用來實現RFC822和MIME規范。
一個MimeMessage對象里保存了一個郵件內容數據（Content），以及一些記錄特定的郵件地址信息（如發件人（Sender）和收件人（recipients））的屬性（InternetHeaders）。還有關于這封郵件的結構信息（structural information），以及它的郵件主體（body）的段體類型（Content-Type）。
下面用圖來描述一個MimeMessage對象內部可能的結構：
1 Hello World!
以下是一個郵件解析庫的簡單程序，說明使用面向對象設計的API解析郵件的方法：
void main() {
char *emaildata = loademailfile("helloworld.eml");
MimeMessage email(emaildata);
String 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);
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();
// 定義存儲郵件主題的字符串變量，郵件解析庫均使用String做為字符串處理
String 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行的內容
String xline;
email.getHeader("X-Priority", xline);
Printf("X-Priority: %s\n", xline.c_str());
// 獲取郵件純文本正文。由于每一封郵件都可能同時包含一個純文本正文體和一個
// HTML正文體，所以它們單獨獲取
String textplain;
email.getTextPlain(textplain);
printf("BodyTextPlain: %s\n", textplain.c_str());
// 也可以這樣同時獲取純文本正文的字符集編碼方式，以供調用者根據它來
// 選擇不同的字符集顯示給用戶。getTextHtml()也類似。
String charset;
email.getTextPlain(textplain, charset);
// 獲取郵件HTML正文內容。
String texthtml;
email.getTextHtml(texthtml);
printf("BodyTextHtml: %s\n", texthtml.c_str());
// 獲取郵件所有附件的名字。
StringArray filenames;
email.getAllAttachmentFilenames(filenames);
// 遍歷查找名字跟其他Array用法一樣
// 獲取指定附件文件名的附件內容，如果有重復的名字的附件將只返回第一個相同
// 名字的附件數據。要獲取其他所有附件，請參考下面的方法。
String 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;
String filename, content;
// 獲取此附件文件名
part->getFileName(filename);
// 獲取此附件內容，已解碼
part->getContent(content);
}
// 獲取郵件的內聯資源附件的名字及內容
// 方法與獲取普通附件一樣，只不過調用getRelatedAttachment()等。
// filename參數換成cid （Content-ID）
// 獲取郵件所有內聯資源附件的名字。
StringArray cids;
email.getAllRelatedAttachmentCIDs(cids);
// 遍歷查找名字跟其他Array用法一樣
// 獲取指定內聯資源附件文件名的附件內容，如果有重復的名字的附件將只返回第一個相同
// 名字的附件數據。要獲取其他所有附件，請參考下面的方法。
String 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;
String filename, cid, content;
// 獲取此內聯資源附件CID
Part->getContentID(cid);
// 獲取此內聯資源附件文件名
part->getFileName(filename);
// 獲取此內聯資源附件內容，已解碼
part->getContent(content);
}
}
1 組裝郵件
下面的例子詳細說明如何用郵件解析庫API組裝一封郵件：
/**
* 郵件源文數據通過參數傳遞
* @param emaildata 存儲組裝好的郵件源文的字符串
*/
void createMessage(String &emaildata)
{
// 定義一個MimeMessage郵件對象用于組裝
MimeMessage email;
// 設置標題
email.setSubject("test mail");
// 設置發件人
email.setSender("test@test.net");
// 也可以，后面是地址的名字
email.setSender("test@test.net", "測試帳號");
// 添加收件人
email.addTo("test1@test.net");
email.addTo("test2@test.net", "收件人2");
// 添加抄送者地址
email.addCc("test3@test.net");
email.addCc("test4@test.net", "收件人4");
// 添加密送者地址
email.addBcc("test5@test.net");
email.addBcc("test6@test.net", "收件人6");
// 設置特殊的郵件頭
email.addHeader("X-Mailer", "jmail 1.0");
// 設置純文本正文，缺省為gb2312（環境變量控制，后面會講到如何配置郵件解析環境）
email.setTextPlain("This is a test mail created by xmail");
// 也可以這樣指定編碼方式
email.setTextPlain("This is a mail encoded by gbk", "gbk");
// 當然也可以這樣
String 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");
// 當然也可以這樣
String bodyhtml;
// bodyhtml可以從其他地方讀取
email.setTextHtml(bodyhtml);
// 或者這樣
email.setTextHtml(bodyhtml, "gbk");
// 添加附件
String 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里引用的個數
String 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將會自動遍歷所有資源附件，刪除沒有再引用的資源附件。
}
1 修改郵件
下面的例子詳細說明如何用郵件解析庫API修改一封郵件：
/**
* 郵件源文數據通過參數傳遞
* @param emaildata 存儲組裝好的郵件源文的字符串
*/
void createMessage(String &emaildata)
{
// 定義一個MimeMessage郵s件對象用于修改
// 方法與上面的解析和組裝類似，解析和組裝調用的方法都可以調用
MimeMessage email(emaildata);
// 下面介紹一下刪除的功能
// 清除郵件純文本正文
email.removeTextPlain();
// 清楚郵件HTML正文
email.removeTextHtml();
// 刪除指定文件名的附件
String filename("attr1.jpg");
email.removeAttachment(filename);
email.removeAttachment("attr1.jpg");
// 刪除指定位置的附件，getAllAttachments()獲取的數組中的位置，從0開
email.removeAttachment(2);
// 刪除所有附件
email.removeAllAttachments();
// 刪除所有內嵌資源附件
email.removeAllRelatedAttachments();
// 還可以調用上面的組裝方法更新指定的數據
// 更新郵件源文數據
// 注意：一定這樣重新定義變量存儲新源文數據
String newdata;
email.toString(newdata);
// 更新返回值字符串
emaildata = newdata;
}
1 高級功能
郵件解析引擎庫API還有更復雜更強大的高級功能，可以組裝和解析出任何符合RFC822和RFC2045的郵件。請參考解析庫里的測試程序mimeutils.cpp和相關的文檔。