283 函数 · 四库分组 · 与二进制同版本

邮件函数参考

有序字节流上的二进制应用层协议帧库:build.bat xtp 编入,32 字节头、四型消息(REQUEST / RESPONSE / PUSH / EVENT)、流式增量解析、完整 limits 体系。两个 inline 辅助(xtp2_text / xtp2_wants_reply)留在头文件里由脚本侧内联。

MIME 层(xmail,89 函数)

构建变体 build.bat xmail(或任一协议变体自动携带)编入。MIME 收发的公共地基:#include <xmail.h> 拉通全部声明(模块头以 VFS 的 xrt/ 子路径提供)。

xrtMailTreeParse / TreeLimitsInit 解析

原始邮件 → 带限额的消息树(深度/数量/大小三向防护,防恶意嵌套)。

bool xrtMailTreeParse(xstrview Message, const xrtMailTreeLimits* pLimits, xrtMailNode** ppTree);

xrtMailBuilderInit / Header / Body / Multipart / Finish 构造

流式构造:头(含编码字与地址规范化)、正文(QP/Base64 自动选择)、多部件边界、一步收尾。零中间拷贝。

void xrtMailBuilderInit(xrtMailBuilder* pBuilder, xbuffer* pBuffer); bool xrtMailBuilderBody(xrtMailBuilder* pBuilder, xbytesview Body, xrtMailCodec Codec);

xrtMailQp / Base64 系列 编解码

QP 与 Base64 的编码/解码,各带 Write(入缓冲)与直接返回(xrtFree 释放)两种形态。

xrtMailAddress / Word / Date / Param / MessageId 字段解析

地址列表游标、编码字(RFC 2047)解码、日期(RFC 5322)、Content-Type/Disposition 参数与 Message-ID——全部借用视图,游标式迭代。

SMTP 客户端(44 函数)

xrtSmtpClientOpen / Capabilities / Auth / Close 会话

建连(明文/STARTTLS/SSL 由配置决定)、能力协商、SASL 认证、优雅关闭。

xsmtpclient* xrtSmtpClientOpen(const xsmtpclientconfig* pConfig, xnetengine* pEngine, xerror* pError);

xrtSmtpClientMail / Rcpt / Data / Bdat 投递

信封(MAIL FROM/RCPT TO)与内容(DATA 或 BDAT 分块)两段式投递;SizeLimit 预检容量。

xrtSmtpSubmit 一步

整封信一步投递(构造→信封→内容→关闭),内部复用会话式 API。

bool xrtSmtpSubmit(const xsmtpsubmitconfig* pConfig, xnetengine* pEngine, xerror* pError);

xrtSmtpReplyLineParse / CapabilityParse 解析器

应答行与能力行解析,独立于网络——离线可测。

POP3 客户端(48 函数)

xrtPop3ClientOpen / Stat / List / Uidl 清点

会话建立与三件清点(数量/大小、列表、唯一 ID)。

xrtPop3ClientRetr / Top / RetrTree 取信

整信取回、取头+N 行、直取消息树(内部走 MIME 层)。

bool xrtPop3ClientRetrTree(xpop3client* pClient, uint64 uMessage, const xrtMailTreeLimits* pLimits, xrtMailNode** ppTree);

xrtPop3ClientDelete / Reset / Noop / Quit 管理

删除标记(QUIT 时生效)、复位、保活与退出。

IMAP 客户端(102 函数)

xrtImapClientOpen / Select / Examine 会话

会话与选箱(读写/只读),返回箱元数据(存在数/最近数/UIDNEXT)。

xrtImapClientBeginSearch / BeginFetch / BeginStore 操作

检索(序列集/条件)、取信(头/体/旗标按需)、旗标修改——Begin* 系列发起后用 Next/Refresh 流式消费。

xrtImapClientAppend / BeginIdle / EndIdle 高级

归档邮件、IDLE 推送等待(服务器主动通知新邮件)、COMPRESS 压缩会话。

xrtImapResponseParse / DataCursor 系列 解析器

应答与数据项(flag/status/search/fetch/body)解析,独立可测。

共享 SASL 与传输

三协议共用一套 SASL 机(PLAIN / XOAUTH2 / OAUTHBEARER)与传输层(TCP + 可选 TLS + 可选压缩),凭据经各自 AuthConfig 传入。机密走环境或 Custom(配置参考),TLS 校验默认开启。

构造与存储约定

所有权:客户端句柄库分配(Close 断连 / Destroy 释放);解析结果与应答是借用视图,出函数前用 Write/Bytes 系列拷贝。变体组合:xsmtp/xpop3/ximap 经 requires 自动携带 xmail;运行期探测用 xsExtensionEnabled("xsmtp")。教学见第 36 章。

完整逐函数签名见仓库 lib/{xmail,xsmtp,xpop3,ximap}/include(Gitee 同步);本页按族给出主链路与常用组合。