模块契约HTML 文本转义

线程

转义/解析 API 为无共享状态的纯函数，可任意线程并发调用。

错误

xhtmlerror 枚举定义 xrt.html 错误域中的稳定模块代码：

  • XHTML_ERROR_MODE：转义上下文无效；
  • XHTML_ERROR_UTF8：输入不是严格 UTF-8。

空指针、地址回绕和非法重叠使用 XERR_ARGUMENT，短缓冲使用 XERR_RANGE，长度 溢出使用统一范围错误，分配失败使用 XERR_MEMORY。

裁剪与依赖

模块宏会自动启用 XRT_FEATURE_HTML_ESCAPE 及其 unicode 依赖。未选择模块时， 类型、函数与实现都不会进入发布物。

上下文

xhtmlescapemode 明确区分两个输出位置：

  • XHTML_ESCAPE_TEXT：转义 &、<、>，用于普通 HTML 文本节点；
  • XHTML_ESCAPE_ATTRIBUTE：额外转义 " 和 '，用于由单引号或双引号包围的

属性值。

属性模式不支持无引号属性。调用方仍须为结果写入配对引号。

API 分层

xrtHtmlEscapeSize 严格校验 UTF-8，并返回不含末尾零的精确字节数。

xrtHtmlEscapeWrite 写入调用方缓冲区。容量必须比结果长度多一个末尾零字节； 输出为 NULL 且容量为零时只查询长度。输入和输出可以从同一地址开始，其他部分 重叠会被拒绝。容量不足时不修改输出，通过 pOutputSize 返回所需长度。

xrtHtmlEscape 创建零结尾结果，返回值由 xrtFree 释放。长度输出可以为 NULL，空输入仍返回独立、可释放的空字符串。

文本契约

输入使用 xstrview，因此允许嵌入零并始终按显式长度处理。模块严格拒绝非法 UTF-8，但不会删除或正规化其他 Unicode 字符，也不会替换 ASCII 控制字节。 输出长度不能使用 strlen 代替显式结果长度，除非调用方已经确定输入不含零。

安全边界

该模块是上下文转义器，不是 HTML 清洗器。它不解析标签，不移除危险元素或属性， 也不处理 JavaScript、CSS、URL、JSON 或 SQL 上下文。用户提供的整段 HTML 需要独立 的白名单清洗方案；脚本、样式和 URL 属性需要各自的编码与校验规则。

Template 保持通用文本模板语义，不会隐式调用本模块。模板变量进入 HTML 文本或 属性时，应在对应上下文显式转义，避免模板层替调用方猜测输出格式。

示例与测试

  • examples/text/html_escape/main.c
  • tests/text/test_html_escape.c
  • tests/text/test_html_escape_noalloc.c
  • tests/text/test_html_escape_oom.c
  • tests/single/test_single_html_escape.c

xhtmlescapemode类型

HTML 转义上下文；属性模式只适用于由引号包围的属性值。

值语义
XHTML_ESCAPE_TEXTXHTMLESCAPE文本
XHTML_ESCAPE_ATTRIBUTE属性上下文转义
typedef enum xhtmlescapemode { XHTML_ESCAPE_TEXT = 0, XHTML_ESCAPE_ATTRIBUTE } xhtmlescapemode;

xhtmlerror类型

HTML 文本原语的稳定错误代码。

值语义
XHTML_ERROR_MODEXHTML失败MODE
XHTML_ERROR_UTF8输入不是合法 UTF-8
typedef enum xhtmlerror { XHTML_ERROR_MODE = 1, XHTML_ERROR_UTF8 } xhtmlerror;

xrtHtmlEscapeSize函数

严格校验 UTF-8 并返回转义后的精确字节数（不含末尾零）。

bool xrtHtmlEscapeSize(xstrview Text, xhtmlescapemode Mode, size_t* pOutputSize)

参数

参数方向约束说明
Text输入借用、严格 UTF-8允许嵌入零
Mode输入枚举TEXT 只转 & < >；ATTRIBUTE 额外转 " '
pOutputSize输出非空接收精确字节数
返回值
返回含义失败时状态
true长度已写出—
false输入非法 UTF-8 或参数错误*pOutputSize 不变
错误
  • XERR_ARGUMENT — 指针为空
  • xrt.charset 域错误 — 非法 UTF-8（严格模式）

范例已编译验证

html/variants · 查询 · 观察

	if ( !xrtHtmlEscapeSize(XRT_STR_LITERAL("<a>"),
		XHTML_ESCAPE_TEXT, &iSize) ) {

xrtHtmlEscapeWrite函数

转义到调用方缓冲区；容量须含末尾零，空输出可只查询长度，同址扩张允许、部分重叠拒绝。

bool xrtHtmlEscapeWrite(xstrview Text, xhtmlescapemode Mode, char* sOutput, size_t iCapacity, size_t* pOutputSize)

参数

参数方向约束说明
Text输入借用、严格 UTF-8输入视图
Mode输入枚举转义模式
sOutput输出可空空+零容量 = 只查长度；可与输入同址
iCapacity输入—容量（含末尾零）
pOutputSize输出可空实际长度（不含零）
返回值
返回含义失败时状态
true已写出零结尾结果—
false容量不足、重叠非法或输入非法输出不变；*pOutputSize 给出所需长度
错误
  • XERR_RANGE — 容量不足（不修改输出）
  • XERR_ARGUMENT — 部分重叠或指针非法
  • xrt.charset 域错误 — 非法 UTF-8

范例已编译验证

html/variants · 写入 · 观察

	if ( !xrtHtmlEscapeWrite(XRT_STR_LITERAL("<a>"),
		XHTML_ESCAPE_TEXT, Buffer, sizeof(Buffer), &iSize) ) {

xrtHtmlEscape函数

创建由 xrtFree 释放的零结尾转义文本；空输入仍返回独立可释放的空字符串。

str xrtHtmlEscape(xstrview Text, xhtmlescapemode Mode, size_t* pOutputSize)

参数

参数方向约束说明
Text输入借用、严格 UTF-8输入视图
Mode输入枚举转义模式
pOutputSize输出可空接收长度（不含零）
返回值
返回含义失败时状态
非空零结尾结果，xrtFree 释放—
NULL输入非法或分配失败错误经 xrtGetError() 报告
错误
  • xrt.charset 域错误 — 非法 UTF-8
  • XERR_MEMORY — 分配失败

范例已编译验证

text/html_escape · 双模式 · 观察

	sText = xrtHtmlEscape(
		XRT_STR_LITERAL("状态：<ready> & 可用"),
		XHTML_ESCAPE_TEXT,
		NULL
	);

常量索引常量

以下常量在本页所属头文件中定义，语义见公共头注释。

常量说明
XHTML_ERROR_MODE见头文件注释
XHTML_ERROR_UTF8见头文件注释
XHTML_ESCAPE_ATTRIBUTE见头文件注释
XHTML_ESCAPE_TEXT见头文件注释