第六部分 fastmail的使用
C++通用框架的設(shè)計(jì) 作者：naven
1 fastmail介紹
郵件解析庫(kù)API完全使用面向?qū)ο蠹夹g(shù)設(shè)計(jì)，使用C++語(yǔ)言開(kāi)發(fā)的用于郵件解析和組裝的庫(kù)。它提供了一些類(lèi)用來(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ù)包含一系列的類(lèi)，主要有MimeMessage（郵件實(shí)現(xiàn)類(lèi)）、MimeBodyPart（郵件正文段體類(lèi)）、MimeMultipart（郵件多部段體類(lèi)）、InternetHeaders（郵件頭類(lèi)）、InternetAddress（郵件地址類(lèi)）和ContentType（段體類(lèi)型類(lèi)）等。解析和組裝郵件主要使用這些類(lèi)進(jìn)行組裝和分解。
fastmail主要有如下一些類(lèi)
ContentDisposition MIME郵件頭 實(shí)現(xiàn)MIME郵件頭的ContentDisposition
ContentID MIME郵件頭 實(shí)現(xiàn)MIME郵件頭的ContentID
ContentType MIME郵件頭 實(shí)現(xiàn)MIME郵件頭的ContentType
MimeType MIME類(lèi)型類(lèi) 實(shí)現(xiàn)MIME的類(lèi)型，記錄在ContentType里，如text/plain
hdr MIME郵件頭 實(shí)現(xiàn)MIME郵件頭HEADER行
HeaderTokenizer 郵件頭分解類(lèi) 實(shí)現(xiàn)分解MIME郵件頭的各元素，如Content-Type的mimetype和各個(gè)參數(shù)。
IMimePart MIME郵件段體接口類(lèi) 郵件段體類(lèi)的基類(lèi)
MimeBodyPart MIME郵件段體類(lèi) 實(shí)現(xiàn)MIME郵件各個(gè)段體的類(lèi)
MimeMessage MIME郵件類(lèi) MIME郵件主類(lèi)
IMultipart 多部分接口類(lèi) 多部分類(lèi)的基類(lèi)
MimeMultipart 多部分實(shí)現(xiàn)類(lèi) 保存段體類(lèi)對(duì)象的多部分容器類(lèi)
InternetAddress MIME郵件地址類(lèi) 實(shí)現(xiàn)MIME郵件地址的類(lèi)
InternetHeaders MIME郵件頭部分類(lèi) 實(shí)現(xiàn)保存MIME各郵件頭的容器類(lèi)
MimeInitialization 郵件解析全局初始化類(lèi) 實(shí)現(xiàn)初始化MIME郵件用到的各個(gè)全局變量
MimetypesFileTypeMap 郵件Mime類(lèi)型映射類(lèi) 實(shí)現(xiàn)郵件MimeType和FileType類(lèi)型的映射表，用于查詢(xún)
MimeUtility MIME郵件分析工具類(lèi) 實(shí)現(xiàn)郵件解析用到的各個(gè)解析工具函數(shù)
ParameterList 參數(shù)列表類(lèi) 實(shí)現(xiàn)ContentType和ContentDisposition用到的參數(shù)列表
UniqueValue 郵件唯一值生成類(lèi) 實(shí)現(xiàn)生成MIME郵件用到的唯一值的類(lèi)，如boundary等
MimeMessage類(lèi)
現(xiàn)在介紹一下最主要的也是提供主要的調(diào)用接口API的類(lèi)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）的段體類(lèi)型（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類(lèi)的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是處理郵件地址的類(lèi)
InternetAddress from;
// 調(diào)用MimeMessage類(lèi)的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類(lèi)的getTo()方法獲取所有的收件人地址信息
// 獲取其他地址如 抄送者用getCc() 密送者用getBcc() 參考后面的MimeMessage方法列表
email.getTo(toAddrs);
// 由于InternetAddressArray是一個(gè)FastArray數(shù)組類(lèi)，所以采用以下方式逐個(gè)輸出
// 定義遍歷數(shù)組的迭代器（這是面向?qū)ο蟮脑O(shè)計(jì)，類(lèi)似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)
// 選擇不同的字符集顯示給用戶(hù)。getTextHtml()也類(lèi)似。
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正文， 跟純文本正文類(lèi)似。
// 備注：一封郵件可以同時(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類(lèi)型
// MimeMessage將根據(jù)filename的擴(kuò)展名到MimeTypes數(shù)據(jù)映射表中查找。
// 備注：MimeTypes映射表可以配置，參考后面的"配置郵件解析環(huán)境"
// 所以也可以這樣調(diào)用
email.addAttachment(filedata, filename);
email.addAttachment(filedata, "attr1.jpg");
// 添加內(nèi)嵌資源附件，與添加普通附件類(lè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ì)象用于修改
// 方法與上面的解析和組裝類(lèi)似，解析和組裝調(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)的文檔。