THPDFHeadlessDocument

HPDFHeadlessDocument 为原生 Linux 与 Windows 提供控制台文档 API，复用既有的 HotPDF 对象解析器、Direct File 辅助器、字体解码器、内容解释器、过滤器解码器与 xref 写入器

文档加载器接受经典交叉引用表、xref 流、hybrid xref 区段、增量 Prev 链、直接与压缩对象、继承页面资源、内容数组、Form XObject 以及 AcroForm 字段树

hybrid 侧流优先于随附的表，较新的修订优先于较旧的修订；对象流成员经共享对象解析器惰性解码与解析

生命周期与所有权

Create 使用 THPDFHeadlessDocumentOptions.Default，而选项重载接受显式预算与调用方自有的取消 Token

LoadFromFile 关闭上一个文档，以只读方式打开源文件，加载当前对象图，失败时关闭部分状态；Close 释放源与全部已加载对象

LoadFromFile(FileName, Password) 通过 THPDFHeadlessAES256Security 认证 Standard AES-256 R5 或 R6 文档；原有的单参数重载使用空密码

用户密码必须在文本提取或表单填充执行之前授予相应权限，而所有者密码绕过用户权限限制；错误密码、认证后的 Perms 不匹配、被拒绝的操作与畸变的密文负载各有独立的文档诊断

直接字符串与流经共享密码学代码解密，压缩成员只随其容器解密，加密的增量替换仍以原始密钥与权限策略保持加密

密码使用 UTF-8 字节并在 127 字节处截断，不做 SASLprep 规范化；不受支持的 handler、显式 Crypt 过滤器与 PDF MAC 策略会被诊断而不是忽略

编码的字典键与资源名在使用前解码，大小写保持敏感，解码后重复的键会被拒绝；字段标志与 MaxLen 必须落在受支持的非负 32 位范围内

实例不是线程安全的；每个 worker 使用一个实例，并保持其取消 Token 存活直到实例销毁

页面与文本

PageCount 报告页面树叶子数量；ExtractPageText(PageIndex) 接受从零开始的索引，返回由共享字形解释器组装的 Unicode 文本

ExtractPageTextBounded 在文本准备之前应用临时的字形与流限制，并在成功、失败或取消后恢复全部原始资源选项

GetObjectAccess 暴露只读的借用目录、信息与对象访问，带有限的索引分配，用于 原生结构与完整比较

文本解码遵循字体 encoding、encoding 差异、内嵌 ToUnicode CMap、显式宽度以及标准字体度量提供方；嵌套 Form XObject 应用其矩阵并使用自有或继承的资源字典

Linux 标准字体 fallback 需要 Fontconfig 与已安装的 TrueType 字体；复杂的文档字体必须提供受支持的解码策略，缺失字体资源会产生诊断

AppendPageText 添加可见或拟合的不可见 Unicode 文本，同时保留原始页面内容与加密安全策略

AppendImportedPages 克隆选定的页面资源图、继承几何与可见普通外观，同时保留既有目标修订与已认证的加密策略

AcroForm 文本值

FormFieldCount、GetFormField(FieldIndex) 与 FindFormField(Name) 使用全限定名以及继承的字段类型、标志、最大长度与值枚举终端字段；索引从零开始，找不到名称返回 -1

SetTextFieldValue(FieldIndex, Text) 接受可写的 Tx 字段，写入 UTF-16BE PDF 字符串，并在 AcroForm 字典上设置 NeedAppearances=true

这种只写值的方法依赖阅读器重新生成外观；不重新生成外观的阅读器可能继续显示旧外观或空控件

SetTextFieldValueWithAppearance 使用调用方提供的 TrueType 字体、真实字形度量、Identity-H encoding、ToUnicode 与完整 FontFile2 内嵌，为每个既有控件生成显式 Unicode 外观

该外观能力支持单行与多行文本、换行、comb 单元、四分之一旋转、固定尺寸或自适应、对齐，以及可选的原生 HarfBuzz/FriBidi 复杂 Shaping

SetChoiceFieldValuesWithAppearance 处理多选列表框、继承选项、排序的导出数组以及每个可见的选中行；单值辅助方法也支持 combo 的导出/显示标签

GetChoiceFieldValues 读取完整的选中导出数组；SetButtonFieldValueWithAppearance 与 SetPushButtonAppearance 生成真实的按钮状态与 caption

新的外观对象与流在字段变更前受限制约束，保存时仍按原始 AES 安全策略保持加密；原生 Linux Cairo 与独立阅读器消费同一批生成对象

只读字段、UTF-16 码元下长于 MaxLen 的值、非文本字段、XFA 表单、已签名字段以及认证文档权限都会被拒绝编辑

经验证的 DSS/VRI 证据在不改变既有 ByteRange 签名的前提下，向增量修订添加已认证的证书与吊销数据

签名验证

SignatureCount 枚举已签名的 AcroForm 签名字段，VerifySignature(SignatureIndex, Options) 使用共享解析器与流式 OpenSSL 3 CMS 提供方验证从零开始的签名

PDF 能力范围接受 adbe.pkcs7.detached 与自动识别的 ETSI.CAdES.detached，Contents 可为十六进制或标准 literal；CAdES 总是认证 ESS 签名证书绑定，而显式 CA 设置单独评估信任

带 ETSI.RFC3161 的 DocTimeStamp 自动认证真实的封装 TSTInfo、ESS、TSA 用途与签名者名称以及精确的 PDF imprint；配置的时间戳根与 CRL 单独评估 TSA 信任

验证校验包含定界符在内的精确未签名间隙，并在密码学验证之前把其解码字节绑定到当前签名字典

结果区分完整性、显式评估的 CA 信任以及已认证修订之后的未签名字节；不受支持的 PDF 签名能力范围产生类型化诊断

运行时要求见 HPDFVerifyHeadlessCMS，预算与信任设置见 THPDFHeadlessCMSOptions

增量批准签名

SignToFile 对既有可写、未签名的 Sig 字段签名，使用调用方提供的 PEM 证书与未加密 PEM 私钥发布独立的增量更新 PDF

AddSignatureField 创建页面控件及其 AcroForm 链接，包括在纯导入 PDF 上新建 AcroForm；SetSignatureFieldAppearance 生成其可见 caption，SignPFXToFile 加载带证书链的 PKCS12 证书/密钥身份

CertificationPermission 创建第一个 DocMDP 认证签名；P2 与 P3 允许在既有字段中继续添加批准签名，P1 拒绝进一步签名

原始源字节与已加载对象图保持不变；后续批准签名保留更早的签名字节及其已认证修订边界

Standard AES-256 R5 与 R6 加密、密码、ID 与权限保持生效，包括加密对象流源；签名 Contents 字符串遵循 PDF 的加密豁免

既有签名值、只读字段、认证文档策略、被拒绝的表单填充权限、不一致的取消 Token 与耗尽的输出预算都会被拒绝，不会发布输出

文档时间戳

TimestampToFile 在既有未签名签名字段中创建真实的 RFC 3161 文档时间戳，无需应用签名密钥，使用调用方自有的 TSA 传输与显式 TSA 信任

写入器保留原始修订与 AES 安全性，为 PDF 2.0 之前的输入声明 ESIC 扩展，并且只在 nonce、imprint、签名、证书、配置吊销与 seed 检查全部通过后才原子发布

DocMDP 与 FieldMDP 下允许必要的已认证文档时间戳变更；普通表单编辑与批准签名保留其原始限制

FDF 与 XFDF 表单交换

ExportFormData 返回有界的 Unicode 字段数据，包括真实的 choice 数组与 checkbox 或 radio 导出状态

ImportFormDataToFile 在私有已认证修订图上重新生成真实外观，并原子发布增量 PDF，同时保留已加载的源状态

ImportRichFormDataToFile 从 FDF RV 或 XFDF value-richtext 导入有界 XHTML profile，使用真实的常规、粗体、斜体与粗斜体字体程序

SaveRichTextFieldUpdatesToFile 在一个独立原子修订中应用 scalar 字段与原始 typed 富文本 run，保留真实字体程序与 PDF 数值精度；未变更的受保护字段要求每个控件都有匹配的已解码外观与已解析资源

既有加密、只读标志、已认证的 DocMDP 与 FieldMDP、原始签名、取消与资源预算继续强制执行；受支持语法与 scalar 交换边界见 原生 FDF 与 XFDF 表单数据

借用 Render 访问

GetRenderAccess(PageIndex) 通过 THPDFHeadlessRenderAccess 提供既有页面字典、继承资源、字体解析器、对象解析、权限检查、取消 Token 与有界的已解码流 callback

这是串行只读的借用视图；文档必须在 renderer 结束之前保持已加载且未变更，调用方不得修改其暴露的对象图

视图的 RequireOutputPath callback 对照源的规范路径与物理文件身份检查预期输出，不创建也不修改文件

独立输出

ExtractPageGlyphs 通过有界嵌套内容遍历器返回带位置的字形；AnalyzePageSemanticText 为 原生契约比较提供语义文本与源几何

SaveToFile(FileName) 复制原始字节并追加替换对象值、经典 xref 表以及通过 Prev 链接的 trailer；压缩对象成员在追加修订中被物化为直接对象，原始流字节保持不变

输出不得与源路径或文件身份互为别名；写入在目标目录独占创建暂存文件，刷新它，然后以原子重命名发布

预算、取消或序列化失败会保留既有目标并删除未发布的暂存文件；源保持只读

原生注释审阅 PDF 导出真实 Unicode 高亮与可见外观，带已认证的注释权限，保留原始已加载文档与签名修订

格式边界

当前能力范围支持 Standard AES-256 R5 与 R6 加密，对不受支持的安全 handler 与流过滤器显式诊断，并拒绝其写入器无法表达的废弃空闲对象代

Bootstrap xref 流要求直接字典值与直接有界的 Length；畸变宽度、子区段重叠、超过 Int64 的无符号偏移、压缩成员不匹配、引用循环与配置限制产生类型化诊断

已解码内容支持带受支持 predictor 与间接流长度的 Flate、ASCIIHex、ASCII85 与 LZW 过滤器；文本提取不解码图像负载

原生签名工作流覆盖签名字段、可见外观与认证；已认证的签名表单策略、时间戳与长期验证 API 保留其显式完整性与信任选项

验收

具名富文本字体族通过 SetRichTextFieldValueWithFamilies 与 ImportRichFormDataWithFamiliesToFile 添加多个真实提供的字体族，沿用既有的字段、安全与事务策略

原生富文本字段提供 typed 样式 run、真实内嵌样式字体外观、同步的 V 与 RV 值、加密增量输出与有界事务编辑；GetRichTextFieldValue 读取存储或继承的 XHTML

Tests/Linux/Run-HeadlessDocumentTests.sh 在清除桌面变量的情况下构建原生 ELF 可执行文件并检查 GUI 库依赖；Run-HeadlessDocumentTests-Windows.cmd Win32 与 Win64 演练同一共享文档 API

返回值与类型化诊断见 THPDFHeadlessFormField、EHPDFHeadlessDocumentError 与 THPDFHeadlessDiagnosticCode