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