CSMTPConnection v1.36
4.94/5 (56投票s)
2000年3月10日
787683
8628
封装 SMTP 协议的 MFC 类。
欢迎使用 CSMTPConnection，这是一个免费的 MFC 类，用于支持 SMTP 协议。对于不熟悉所有互联网协议的读者来说，SMTP 是用于发送互联网电子邮件的协议。
有关 Simple Mail Transfer Protocol 的详细信息，您应该阅读 RFC 821，
这些类引用的其他文档是 RFC 2045（定义了标准 SMTP 消息中如何处理 MIME 附件）和 RFC 822（定义了 SMTP 使用的标准标头的方式）。
您可以通过访问 www.yahoo.com 并搜索 RFC 和 821、822 或 2045 来找到许多包含这些文档的 Web 服务器。
| 特点 |
| 用法 |
| 历史 |
| API 参考 |
| 计划增强功能 |
| 联系作者 |
特点
- 简洁的 C++ 接口。
- 提供的接口是同步的，这提供了一种比使用异步套接字更简单的编程模型。
- 代码不依赖于 MFC 套接字类。这些类存在一些缺点，其中一个缺点在使用 NT 服务时会导致问题。
- 代码可以在控制台应用程序中毫无问题地使用（同样，MFC 套接字类的情况并非如此）。
- 可以通过类 API 设置可配置的连接超时。
- 类完全符合 Unicode 标准，并在工作区文件中包含 Unicode 构建选项。
- 从 v1.1 开始，这些类现在完全支持发送文件附件。
- 支持多个抄送 (CC)、密送 (BCC) 和回复到 (Reply To)。
- 支持常规电子邮件地址格式和多个电子邮件地址解析。
用法
- 要在您的代码中使用该类，只需将 smtp.cpp 包含到您的项目中，并在需要调用该类的任何模块中包含 smtp.h。
- 您的代码需要静态或动态地包含 MFC。
- 在调用 CSMTPConnection 中的任何函数之前，您需要安装并正确初始化一个可正常工作的 winsock 堆栈。根据您的应用程序，这将在应用程序启动时调用 WSAStartup 或 AfxSocketInit。
- 您还需要在预编译头文件中包含 afxtempl.h、winsock.h 或 afxsock.h 以及 afxpriv.h。该代码在 GUI 或控制台应用程序中同样适用。该代码也应该在多线程应用程序中工作，尽管尚未在此场景下进行显式测试。
- 要查看该类的工作示例，请查看 "main.cpp" 模块中的 InitInstance 代码。例如，要向作者发送有关此类的消息，代码将如下所示（忽略错误处理）
CSMTPConnection smtp;
smtp.Connect("mail.yourisp.com");
CSMTPMessage m;
m.AddRecipient(CSMTPAddress("pjn@indigo.ie"));
m.m_From = CSMTPAddress("you@someisp.com");
m.m_sSubject = "Here's my autoexec.bat file!";
CSMTPAttachment a;
a.Attach("c:\\autoexec.bat");
m.AddAttachment(&a);
smtp.SendMessage(m);
要将您的 autoexec.bat 作为文件附件发送给我，您将使用以下代码
CSMTPConnection smtp;
smtp.Connect("mail.yourisp.com");
CSMTPMessage m;
m.AddRecipient(CSMTPAddress("pjn@indigo.ie"));
m.m_From = CSMTPAddress("you@someisp.com");
m.m_sSubject = "Here's my autoexec.bat file!";
CSMTPAttachment a;
a.Attach("c:\\autoexec.bat");
m.AddAttachment(&a);
smtp.SendMessage(m);
历史
V1.0 (1998 年 5 月 26 日)
- 首次公开发布。
V1.1 (1998 年 6 月 17 日)
- 修正了消息正文中出现单独的句点的情况。
- 类现在支持可选的“Reply-To”标头字段。
- 类现在完全支持文件附件。
- 对帮助文件内容的一些重构。
V1.11 (1998 年 6 月 18 日)
- 修正了在编码 base64 附件的缓冲区时发生的内存覆盖问题。
V1.12 (1998 年 6 月 27 日)
- 现在也处理以“.”开头但包含其他文本的行。有关更多详细信息，请参阅 RFC821，第 4.5.2 节。
- CSMTPMessage 中的 m_sBody 现在被设为 protected。客户端应用程序现在应该调用 AddBody。这确保了即使发送相同的消息多次，FixSingleDot 也只会被调用一次。
- 修正了 MIME 边界的定义和发送方式中的一些问题。
- 在发布构建时消除了未引用的形式参数编译器警告。
V1.2 (1998 年 8 月 11 日)
- 现在提供 VC 5 项目文件，而不是 VC 4.x。
- 消息类包含的附件数组现在使用引用而不是指针。
- 现在使用 Sleep(0) 来让出时间片，而不是 Sleep(100)，这是在 Win32 中编写轮询式代码的首选方法，同时不会严重影响性能。
- 所有跟踪语句现在都显示 GetLastError 返回的值。
- 添加了许多额外的断言。
- 添加了 AddMultipleRecipients，它支持一次从单个字符串添加多个收件人。
- 添加了额外的跟踪语句以帮助调试。
- 文档中的一些更新。
V1.21 (1998 年 9 月 12 日)
- 移除了在 Visual C++ 6.0 上编译该类时发现的一些未引用的变量编译器警告。
- 修正了一个主要 bug，该 bug 在样本应用程序的 InitInstance 中调用 CSMTPAttachment 析构函数时导致 ASSERT。这在 1.2 版本中被无意引入。修复方法是恢复 v1.2 的修复 2）。新修复还将有助于减少一次保存在内存中的附件图像数量。
- 修正了此帮助文件中的一些错误。
V1.3 (1999 年 1 月 18 日)
- 现在已完全支持 CC（抄送）和 BCC（密送）。
V1.31 (1999 年 2 月 22 日)
- 添加了 GetTitle 和 SetTitle 方法，允许附件文件的标题与原始文件名不同。
- 更新了示例应用程序，使其包含更具描述性的主题行。
- 现在，当构建调试版本时，代码的默认超时设置为 60 秒。
- 通过实现一个可增长的接收缓冲区，改进了从服务器读取响应。
- 更新了有关如何检索相关 RFC 文档的说明。
V1.32 (1999 年 3 月 25 日)
- 现在休眠 250 毫秒而不是让出时间片。这有助于在等待数据到达套接字时减少 CPU 使用。
V1.33 (1999 年 5 月 14 日)
- 更新了文档以引用 RFC 822。
- 修正了代码生成日期标头中时区字段的 bug。感谢 Randy A. Scott 报告此 bug。
V1.34 (1999 年 9 月 10 日)
- 改进了 CSMTPMessage::GetHeader，使其即使在不包含附件时也包含 mime 字段。
V1.35 (1999 年 10 月 5 日)
- 使用 VC 6 编译时修复了 2 个 4 级警告。
V1.36 (2000 年 2 月 16 日)
- 使用 VC 6 编译时修复了另一个编译器问题。
API 参考
API 由 CSMTPAddress、CSMTPMessage 和 CSMTPConnection 类的公共成员函数组成。
CSMTPAddress
CSMTPAttachment::Attach
CSMTPAttachment::GetFilename
CSMTPAttachment::GetEncodedBuffer
CSMTPAttachment::GetEncodedSize
CSMTPAttachment::SetTitle
CSMTPAttachment::GetTitle
CSMTPMessage::AddRecipient
CSMTPMessage::RemoveRecipient
CSMTPMessage::GetRecipient
CSMTPMessage::GetNumberOfRecipients
CSMTPMessage::AddAttachment
CSMTPMessage::RemoveAttachment
CSMTPMessage::GetAttachment
CSMTPMessage::GetNumberOfAttachments
CSMTPMessage::m_From
CSMTPMessage::m_sSubject
CSMTPMessage::AddBody
CSMTPMessage::AddMultipleRecipients
CSMTPMessage::m_sXMailer
CSMTPMessage::m_ReplyTo
CSMTPConnection::Connect
CSMTPConnection::Disconnect
CSMTPConnection::GetLastCommandResponse
CSMTPConnection::GetLastCommandResponseCode
CSMTPConnection::GetTimeoutCSMTPConnection::SetTimeout
CSMTPConnection::SendMessage
备注
此类封装了用于发送电子邮件的地址。它包含两个字符串，即 m_sFriendlyName 和 m_sEmailAddress。构造地址的示例如下：
CSMTPAddress a(_T("pjn@indigo.ie")); // or CSMTPAddress b(_T("PJ Naughter"),_T("pjn@indigo.ie"));
包含友好地址的第二种形式允许其以“PJ Naughter <pjn@indigo.ie>”的形式用于“To”和“Reply-To”标头。
包含一个名为 GetRegularFormat 的公共类方法，该方法返回前面讨论的格式。
另请参阅
BOOL Attach(const CString& sFilename);
返回值
如果文件成功编码为附件，则返回 TRUE，否则返回 FALSE。
参数
sFilename 要设置为附件的文件的名称的引用。
备注
此函数将在内部对指定文件执行 base64 编码，并将编码存储在私有缓冲区中，以便在将此附件与 SMTP 消息关联时使用。
另请参阅
CString GetFilename() const;
返回值
返回此附件代表的文件的名称。
参数
无
备注
这将仅返回文件的“filename.ext”形式。例如，如果调用 Attach 时使用的文件名是“c:\autoexec.bat”，则 GetFilename 的返回值将是“autoexec.bat”。
CSMTPAttachment::GetEncodedBuffer
const char* GetEncodedBuffer() const;
返回值
返回附件的 base64 编码表示。
参数
无
备注
无
CSMTPAttachment::SetTitle
void SetTitle(const CString& sTitle);
参数
sTitle 文件附件的新标题。
备注
允许您更改附件在电子邮件中显示的名称。默认情况下，它将是您添加的文件的文件名。这种功能在您将文件保存到临时文件名然后再将其通过电子邮件发送给某人时很有用。
另请参阅
CSMTPAttachment::GetTitle
CString GetTitle() const;
返回值
附件在电子邮件中显示的名称。
另请参阅
int AddRecipient(CSMTPAddress& recipient, RECIPIENT_TYPE RecipientType = TO);
返回值
新添加的收件人到消息的索引。
参数
recipient 要添加到此消息的收件人的引用。
RecipientType 要添加的收件人类型。RECIPIENT_TYPE 是一个枚举，具有以下三个值：TO、CC 和 BCC。
备注
将指定类型的收件人添加到消息。通常至少需要调用一次此函数，然后才能发送电子邮件消息。
另请参阅
void RemoveRecipient(int nIndex, RECIPIENT_TYPE RecipientType = TO);
返回值
无。
参数
nIndex 要删除的收件人的索引。
RecipientType "nIndex" 引用的收件人类型。RECIPIENT_TYPE 是一个枚举，具有以下三个值：TO、CC 和 BCC。
备注
AddRecipient 的对应函数。
另请参阅
CSMTPAddress GetRecipient(int nIndex, RECIPIENT_TYPE RecipientType = TO) const;
返回值
指定偏移量的收件人。
参数
nIndex 要检索的收件人的索引。
RecipientType "nIndex" 引用的收件人类型。RECIPIENT_TYPE 是一个枚举，具有以下三个值：TO、CC 和 BCC。
备注
允许访问与消息关联的收件人数组。
另请参阅
CSMTPMessage::GetNumberOfRecipients
int GetNumberOfRecipients(RECIPIENT_TYPE RecipientType = TO) const;
返回值
此消息的收件人数量。
参数
RecipientType 要检索大小的收件人类型。RECIPIENT_TYPE 是一个枚举，具有以下三个值：TO、CC 和 BCC。
备注
返回此消息的目标收件人数量。
另请参阅
int AddAttachment(CSMTPAttachment* pAttachment);
返回值
新添加的附件到消息的索引。
参数
pAttachment 要添加到此消息的文件附件的指针。
备注
将附件添加到消息。请注意，此函数内部会分配一个缓冲区，该缓冲区在发送附件时使用。这意味着“attachment”实例必须在 CSMTPConnection::SendMessage 调用期间保持有效。
另请参阅
CSMTPMessage::RemoveAttachment CSMTPConnection::SendMessage
CSMTPMessage::RemoveAttachment
void RemoveAttachment(int nIndex);
返回值
无。
参数
nIndex 要删除的附件的索引。
备注
AddAttachment 的对应函数。
另请参阅
CSMTPAttachment* GetAttachment(int nIndex) const;
返回值
指定偏移量的附件指针。
参数
nIndex 要检索的附件的索引。
备注
允许访问与消息关联的附件数组。
另请参阅
CSMTPMessage::GetNumberOfAttachments
int GetNumberOfAttachments() const;
返回值
此消息的附件数量。
参数
无。
备注
返回此消息包含的附件数量。
另请参阅
备注
这是发送邮件的发件人地址。在发送消息之前，通常会将其设置为您的电子邮件地址。
另请参阅
备注
消息的主题行，格式为 CString。在发送消息之前，通常会将其设置为有意义的内容。
void AddBody(const CString& sBody);
返回值
无。
参数
sBody 要添加到消息正文的文本的引用。
备注
此函数内部将确保字符串的内容符合 SMTP 消息的标准要求。在 v1.12 之前，提供了一个公共成员 m_sBody。客户端应用程序现在应该调用 AddBody。这确保了即使发送相同的消息多次，内部函数 FixSingleDot 也只会被调用一次。
另请参阅
CSMTPMessage::AddMultipleRecipients
BOOL AddMultipleRecipients(const CString& sRecipients);
返回值
如果字符串成功解析为收件人，则返回 TRUE，否则返回 FALSE。
.参数
sRecipients 包含多个收件人地址的字符串。
备注
此函数允许类快速添加多个收件人，而无需为每个收件人创建单个 CSMTPAddress。字符串中允许的分隔符是“;”和“,”，友好名称可以用“<”和“>”分隔符指定。有效字符串的示例如下：
face="Times New Roman">"PJ Naughter <pjn@indigo.ie> , My Boss <someboss@company.com> ; Joe <joe@ms.com>"
另请参阅
备注
将在电子邮件地址中包含的 X-Mailer 字段。默认情况下，它设置为 _T("CSMTPConnection v1.21")。您可以在从应用程序发送电子邮件消息之前自由更改它。
备注
这是回复此消息的人的地址。这是一个可选字段，通常不需要存在，因为您通常希望回复您的消息直接发送回消息的发送者。默认情况下，发送 SMTP 消息时不会发送此字段。
另请参阅
BOOL Connect(LPCTSTR pszHostName, int nPort = 25);
返回值
如果函数成功，则返回值为 TRUE。如果函数失败，则返回值为 FALSE。要获取扩展错误信息，请调用 ::GetLastError。
参数
pszHostName 要连接的套接字的网络地址：一个机器名称，如“mail.yourisp.com”，或一个点分十进制数，如“128.56.22.8”。
nPort 要连接的端口号。默认值为 25，这是默认的 SMTP 端口号。
备注
调用此成员函数以建立与 SMTP 邮件服务器的连接。
另请参阅
BOOL Disconnect();
返回值
如果函数成功，则返回值为 TRUE。如果函数失败，则返回值为 FALSE。要获取扩展错误信息，请调用 ::GetLastError。
参数
无。
备注
Connect 的对应函数。
另请参阅
CSMTPConnection::GetLastCommandResponse
CString GetLastCommandResponse() const;
返回值
来自服务器的最后一个命令响应，格式为 CString。
参数
无。
备注
CSMTPConnection 类可以在大多数错误的同时返回附加文本信息。可以通过在函数调用失败后使用 GetLastCommandResponse 函数来检索此扩展错误信息。GetLastCommandResponse 可以调用多次，直到调用另一个发送 SMTP 命令的 CSMTPConnection 函数为止。
另请参阅
CSMTPConnection::GetLastCommandResponseCode
CSMTPConnection::GetLastCommandResponseCode
int GetLastCommandResponseCode() const;
返回值
来自服务器的最后一个命令响应，格式为 CString。
参数
无。
备注
CSMTPConnection 类可以在大多数错误的同时返回附加文本信息。可以通过在函数调用失败后使用 GetLastCommandResponse 函数来检索此扩展错误信息。SMTP 响应中嵌入了一个 3 位数的错误代码。GetLastCommandResponseCode 检索此值。
另请参阅
CSMTPConnection::GetLastCommandResponse
DWORD GetTimeout() const;
返回值
代码将等待 SMTP 服务器响应的超时（以毫秒为单位）。
参数
无。
备注
由于 CSMTPConnection 提供同步 API，因此提供了超时机制。默认情况下，发布模式下的值为 2 秒，调试模式下的值为 20 秒。调试模式下的值较大，以防止代码在调试时超时。
另请参阅
void SetTimeout(DWORD dwTimeout) const;
返回值
无。
参数
dwTimeout 新的超时值（以毫秒为单位）。
备注
设置连接到 SMTP 服务器的超时值。
另请参阅
BOOL SendMessage(const CSMTPMessage& Message) const;
返回值
如果函数成功，则返回值为 TRUE。如果函数失败，则返回值为 FALSE。要获取扩展错误信息，请调用 ::GetLastError。
参数
Message 要发送的消息的 const 引用。
备注
使用当前连接到的服务器发送指定的消息。
另请参阅
计划增强功能
- 将代码打包成 OCX、COM 接口或 DLL，以允许非 MFC 应用程序使用该代码。
- 提供更好的示例应用程序。目前，它在很大程度上是一个测试所有函数的测试程序。
- 如果您有任何其他改进建议，请告诉我，以便我将其纳入下一个版本。