第六部分 fastmail的使用
C++通用框架的設(shè)計(jì) 作者：naven
1 fastmail介紹
郵件解析庫(kù)API完全使用面向?qū)ο蠹夹g(shù)設(shè)計(jì)，使用C++語(yǔ)言開(kāi)發(fā)的用于郵件解析和組裝的庫(kù)。它提供了一些類用來(lái)解析和組裝Internet郵件，如MimeMessage和MimeBodyPart，用于Internet郵件協(xié)議實(shí)現(xiàn)并且遵循RFC822和RFC2045規(guī)范。這些API庫(kù)用于應(yīng)用程序的開(kāi)發(fā)。
RFC：Request For Comments, 請(qǐng)求注解, Internet標(biāo)準(zhǔn)(草案)
MIME：Multipurpose Internet Mail Extension protocol, 多用途的網(wǎng)際郵件擴(kuò)充協(xié)議
郵件解析庫(kù)包含一系列的類，主要有MimeMessage（郵件實(shí)現(xiàn)類）、MimeBodyPart（郵件正文段體類）、MimeMultipart（郵件多部段體類）、InternetHeaders（郵件頭類）、InternetAddress（郵件地址類）和ContentType（段體類型類）等。解析和組裝郵件主要使用這些類進(jìn)行組裝和分解。
fastmail主要有如下一些類
ContentDisposition MIME郵件頭 實(shí)現(xiàn)MIME郵件頭的ContentDisposition
ContentID MIME郵件頭 實(shí)現(xiàn)MIME郵件頭的ContentID
ContentType MIME郵件頭 實(shí)現(xiàn)MIME郵件頭的ContentType
MimeType MIME類型類 實(shí)現(xiàn)MIME的類型，記錄在ContentType里，如text/plain
hdr MIME郵件頭 實(shí)現(xiàn)MIME郵件頭HEADER行
HeaderTokenizer 郵件頭分解類 實(shí)現(xiàn)分解MIME郵件頭的各元素，如Content-Type的mimetype和各個(gè)參數(shù)。
IMimePart MIME郵件段體接口類 郵件段體類的基類
MimeBodyPart MIME郵件段體類 實(shí)現(xiàn)MIME郵件各個(gè)段體的類
MimeMessage MIME郵件類 MIME郵件主類
IMultipart 多部分接口類 多部分類的基類
MimeMultipart 多部分實(shí)現(xiàn)類 保存段體類對(duì)象的多部分容器類
InternetAddress MIME郵件地址類 實(shí)現(xiàn)MIME郵件地址的類
InternetHeaders MIME郵件頭部分類 實(shí)現(xiàn)保存MIME各郵件頭的容器類
MimeInitialization 郵件解析全局初始化類 實(shí)現(xiàn)初始化MIME郵件用到的各個(gè)全局變量
MimetypesFileTypeMap 郵件Mime類型映射類 實(shí)現(xiàn)郵件MimeType和FileType類型的映射表，用于查詢
MimeUtility MIME郵件分析工具類 實(shí)現(xiàn)郵件解析用到的各個(gè)解析工具函數(shù)
ParameterList 參數(shù)列表類 實(shí)現(xiàn)ContentType和ContentDisposition用到的參數(shù)列表
UniqueValue 郵件唯一值生成類 實(shí)現(xiàn)生成MIME郵件用到的唯一值的類，如boundary等
MimeMessage類
現(xiàn)在介紹一下最主要的也是提供主要的調(diào)用接口API的類MimeMessage。
MimeMessage提供了一系列的方法供調(diào)用者使用，如定義了獲取地址信息和獲取郵件正文內(nèi)容的結(jié)構(gòu)（可以為具體的數(shù)據(jù)也可以為一個(gè)MimeMultipart對(duì)象），用來(lái)實(shí)現(xiàn)RFC822和MIME規(guī)范。
一個(gè)MimeMessage對(duì)象里保存了一個(gè)郵件內(nèi)容數(shù)據(jù)（Content），以及一些記錄特定的郵件地址信息（如發(fā)件人（Sender）和收件人（recipients））的屬性（InternetHeaders）。還有關(guān)于這封郵件的結(jié)構(gòu)信息（structural information），以及它的郵件主體（body）的段體類型（Content-Type）。
下面用圖來(lái)描述一個(gè)MimeMessage對(duì)象內(nèi)部可能的結(jié)構(gòu)：
1 Hello World!
以下是一個(gè)郵件解析庫(kù)的簡(jiǎn)單程序，說(shuō)明使用面向?qū)ο笤O(shè)計(jì)的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 解析郵件
下面的例子詳細(xì)說(shuō)明如何用郵件解析庫(kù)API解析一封郵件：
/**
* 郵件源文數(shù)據(jù)通過(guò)參數(shù)傳遞
* @param msg 指向郵件源文的字符串指針
* @param len 郵件源文的長(zhǎng)度
*/
void parseMessage(const char *msg, const int len)
{
// 定義一個(gè)MimeMessage郵件對(duì)象用于解析
// 郵件對(duì)象使用指向郵件源文的字符串指針和長(zhǎng)度的參數(shù)構(gòu)造
// 也可使用 MimeMessage email(msg)構(gòu)造，傳入len參數(shù)的目的是為了節(jié)省再做一次
// strlen()的時(shí)間，因?yàn)橛行┼]件源文比較大。
// 備注：如果只獲取郵件頭，MimeMessage就只解析郵件頭數(shù)據(jù)，不會(huì)解析郵件正文。
MimeMessage email(msg, len);
// 獲取發(fā)信時(shí)間，此時(shí)間UTC時(shí)間
// Coordinated Universal Time (UTC, formerly referred to as "Greenwich Mean Time")
time_t senttm = email.getSentDate();
// 定義存儲(chǔ)郵件主題的字符串變量，郵件解析庫(kù)均使用String做為字符串處理
String subject;
// 調(diào)用MimeMessage類的getSubject()方法獲取郵件主題，內(nèi)容放進(jìn)subject變量里
email.getSubject(subject);
// 打印輸出主題，c_str()方法是標(biāo)準(zhǔn)的獲取字符串內(nèi)容指針的方法
printf("Subject: %s\n", subject.c_str());
// 定義存儲(chǔ)發(fā)信人地址的變量，這里InternetAddress是處理郵件地址的類
InternetAddress from;
// 調(diào)用MimeMessage類的getFrom()方法獲取郵件發(fā)信人地址
email.getFrom(from);
// 輸出地址發(fā)信人地址，personal是郵件地址的名字，address是地址
printf("From: \"%s\" <%s>\n", from.personal(), from.address());
// 定義存儲(chǔ)發(fā)信人地址的變量，這里用InternetAddressArray是因?yàn)槭占丝赡苡卸鄠€(gè)
InternetAddressArray toAddrs;
// 調(diào)用MimeMessage類的getTo()方法獲取所有的收件人地址信息
// 獲取其他地址如 抄送者用getCc() 密送者用getBcc() 參考后面的MimeMessage方法列表
email.getTo(toAddrs);
// 由于InternetAddressArray是一個(gè)FastArray數(shù)組類，所以采用以下方式逐個(gè)輸出
// 定義遍歷數(shù)組的迭代器（這是面向?qū)ο蟮脑O(shè)計(jì)，類似STL庫(kù)容器的迭代器用法）
InternetAddressArrayIterator it(toAddrs);
// 判斷迭代器是否走到數(shù)組的末尾，否則進(jìn)入循環(huán)
while( !it.done() ) {
// 輸出郵件地址，迭代器相當(dāng)于指向InternetAddress的指針
printf("To: \"%s\" <%s>\n", it->personal(), it->address());
// 跌打器向前移動(dòng)一位
it.advance();
}
// 數(shù)組的遍歷也可采用如下傳統(tǒng)方式
for( int i = 0; i < toAddrs.size(); i ++ ) {
// 由于[]操作符不計(jì)算數(shù)組范圍，所以不建議如此使用。盡量使用迭代器，
// 除非是想直接取得第n個(gè)地址
printf("To: \"%s\" <%s>\n", toAddrs[i].personal(),toAddrs[i].address());
}
// 獲取其他郵件Header行的內(nèi)容
String xline;
email.getHeader("X-Priority", xline);
Printf("X-Priority: %s\n", xline.c_str());
// 獲取郵件純文本正文。由于每一封郵件都可能同時(shí)包含一個(gè)純文本正文體和一個(gè)
// HTML正文體，所以它們單獨(dú)獲取
String textplain;
email.getTextPlain(textplain);
printf("BodyTextPlain: %s\n", textplain.c_str());
// 也可以這樣同時(shí)獲取純文本正文的字符集編碼方式，以供調(diào)用者根據(jù)它來(lái)
// 選擇不同的字符集顯示給用戶。getTextHtml()也類似。
String charset;
email.getTextPlain(textplain, charset);
// 獲取郵件HTML正文內(nèi)容。
String texthtml;
email.getTextHtml(texthtml);
printf("BodyTextHtml: %s\n", texthtml.c_str());
// 獲取郵件所有附件的名字。
StringArray filenames;
email.getAllAttachmentFilenames(filenames);
// 遍歷查找名字跟其他Array用法一樣
// 獲取指定附件文件名的附件內(nèi)容，如果有重復(fù)的名字的附件將只返回第一個(gè)相同
// 名字的附件數(shù)據(jù)。要獲取其他所有附件，請(qǐng)參考下面的方法。
String filename("attr1.jpg"), content;
email.getAttachment(filename, content);
// 獲取郵件所有附件。
AttachmentPtrArray attachments;
email. getAllAttachments(attachments);
// 附件總數(shù)
int attnum = attachments.size();
// 遍歷所有附件
for( size_t i = 0; i < attachments.size(); i ++ )
{
// 獲得此附件PART的指針，注意：不能free或其他直接修改指針內(nèi)容的操作。
MimeBodyPart *part = attachments[i];
if( part == NULL )
continue;
String filename, content;
// 獲取此附件文件名
part->getFileName(filename);
// 獲取此附件內(nèi)容，已解碼
part->getContent(content);
}
// 獲取郵件的內(nèi)聯(lián)資源附件的名字及內(nèi)容
// 方法與獲取普通附件一樣，只不過(guò)調(diào)用getRelatedAttachment()等。
// filename參數(shù)換成cid （Content-ID）
// 獲取郵件所有內(nèi)聯(lián)資源附件的名字。
StringArray cids;
email.getAllRelatedAttachmentCIDs(cids);
// 遍歷查找名字跟其他Array用法一樣
// 獲取指定內(nèi)聯(lián)資源附件文件名的附件內(nèi)容，如果有重復(fù)的名字的附件將只返回第一個(gè)相同
// 名字的附件數(shù)據(jù)。要獲取其他所有附件，請(qǐng)參考下面的方法。
String cid("3334776372$1097735850$0600030@local"), content;
email.getRelatedAttachment(cid, content);
// 獲取郵件所有內(nèi)聯(lián)資源附件。
AttachmentPtrArray attachments;
email. getAllRelatedAttachments(attachments);
// 內(nèi)聯(lián)資源附件總數(shù)
int attnum = attachments.size();
// 遍歷所有內(nèi)聯(lián)資源附件
for( size_t i = 0; i < attachments.size(); i ++ )
{
// 獲得此附件PART的指針，注意：不能free或其他直接修改指針內(nèi)容的操作。
MimeBodyPart *part = attachments[i];
if( part == NULL )
continue;
String filename, cid, content;
// 獲取此內(nèi)聯(lián)資源附件CID
Part->getContentID(cid);
// 獲取此內(nèi)聯(lián)資源附件文件名
part->getFileName(filename);
// 獲取此內(nèi)聯(lián)資源附件內(nèi)容，已解碼
part->getContent(content);
}
}
1 組裝郵件
下面的例子詳細(xì)說(shuō)明如何用郵件解析庫(kù)API組裝一封郵件：
/**
* 郵件源文數(shù)據(jù)通過(guò)參數(shù)傳遞
* @param emaildata 存儲(chǔ)組裝好的郵件源文的字符串
*/
void createMessage(String &emaildata)
{
// 定義一個(gè)MimeMessage郵件對(duì)象用于組裝
MimeMessage email;
// 設(shè)置標(biāo)題
email.setSubject("test mail");
// 設(shè)置發(fā)件人
email.setSender("test@test.net");
// 也可以，后面是地址的名字
email.setSender("test@test.net", "測(cè)試帳號(hào)");
// 添加收件人
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");
// 設(shè)置特殊的郵件頭
email.addHeader("X-Mailer", "jmail 1.0");
// 設(shè)置純文本正文，缺省為gb2312（環(huán)境變量控制，后面會(huì)講到如何配置郵件解析環(huán)境）
email.setTextPlain("This is a test mail created by xmail");
// 也可以這樣指定編碼方式
email.setTextPlain("This is a mail encoded by gbk", "gbk");
// 當(dāng)然也可以這樣
String bodytext;
// bodytext可以從其他地方讀取
email.setTextPlain(bodytext);
// 或者這樣
email.setTextPlain(bodytext, "gbk");
// 設(shè)置HTML正文， 跟純文本正文類似。
// 備注：一封郵件可以同時(shí)包含一個(gè)純文本正文和一個(gè)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");
// 當(dāng)然也可以這樣
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");
// 注意：如果不指定后面第三個(gè)參數(shù)，即附件的MimeType類型
// MimeMessage將根據(jù)filename的擴(kuò)展名到MimeTypes數(shù)據(jù)映射表中查找。
// 備注：MimeTypes映射表可以配置，參考后面的"配置郵件解析環(huán)境"
// 所以也可以這樣調(diào)用
email.addAttachment(filedata, filename);
email.addAttachment(filedata, "attr1.jpg");
// 添加內(nèi)嵌資源附件，與添加普通附件類似。
// 注意：必須要先設(shè)置郵件的HTML正文后才能添加內(nèi)嵌資源附件，否則也添不進(jìn)去
// src是資源附件在HTML正文里的URL，包括路徑和文件名
// cid是添加成功后資源附件的CID值
// 返回值count是資源附件在HTML里引用的個(gè)數(shù)
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正文即再次調(diào)用setTextHtml()，
// MimeMessage將會(huì)自動(dòng)遍歷所有資源附件，刪除沒(méi)有再引用的資源附件。
}
1 修改郵件
下面的例子詳細(xì)說(shuō)明如何用郵件解析庫(kù)API修改一封郵件：
/**
* 郵件源文數(shù)據(jù)通過(guò)參數(shù)傳遞
* @param emaildata 存儲(chǔ)組裝好的郵件源文的字符串
*/
void createMessage(String &emaildata)
{
// 定義一個(gè)MimeMessage郵s件對(duì)象用于修改
// 方法與上面的解析和組裝類似，解析和組裝調(diào)用的方法都可以調(diào)用
MimeMessage email(emaildata);
// 下面介紹一下刪除的功能
// 清除郵件純文本正文
email.removeTextPlain();
// 清楚郵件HTML正文
email.removeTextHtml();
// 刪除指定文件名的附件
String filename("attr1.jpg");
email.removeAttachment(filename);
email.removeAttachment("attr1.jpg");
// 刪除指定位置的附件，getAllAttachments()獲取的數(shù)組中的位置，從0開(kāi)
email.removeAttachment(2);
// 刪除所有附件
email.removeAllAttachments();
// 刪除所有內(nèi)嵌資源附件
email.removeAllRelatedAttachments();
// 還可以調(diào)用上面的組裝方法更新指定的數(shù)據(jù)
// 更新郵件源文數(shù)據(jù)
// 注意：一定這樣重新定義變量存儲(chǔ)新源文數(shù)據(jù)
String newdata;
email.toString(newdata);
// 更新返回值字符串
emaildata = newdata;
}
1 高級(jí)功能
郵件解析引擎庫(kù)API還有更復(fù)雜更強(qiáng)大的高級(jí)功能，可以組裝和解析出任何符合RFC822和RFC2045的郵件。請(qǐng)參考解析庫(kù)里的測(cè)試程序mimeutils.cpp和相關(guān)的文檔。