原生 Linux C ABI 注释交换

hpdf_document_execute_json_v1 通过既有的版本化操作描述符和回调 IO 接口暴露 annotations.export 与 annotations.import

先把 PDF 加载进文档 context；注释导入用 InputIO 接收 XFDF 字节、OutputIO 输出保存的 PDF、ResultIO 输出 JSON 结果元数据

{"schemaVersion":1,"type":"annotations.export","format":"xfdf"}

导出把 UTF-8 XFDF 写到 OutputIO，并报告 annotationCount、skippedAnnotationCount、decodedAttachmentBytes 和 outputBytes

{"schemaVersion":1,"type":"annotations.import","format":"xfdf",
 "annotationLimits":{"maxBytes":1048576,"maxAnnotations":1000,
 "maxNodes":100000,"maxDepth":32,"maxWorkingBytes":67108864}}

导入报告 updated 和 annotationProfile，只有 PDF 与结果回调都成功之后才采纳保存的修订版

输入/输出回调失败、结果回调失败和取消都会保留与先前提交完全一致的 context；后面的回调失败发生时，外部回调可能已经收到部分流

能力 JSON 宣告 annotationData，含映射类型 profile、追加导入模式、内嵌数据、前向回复和 popup 对象；appearanceImport 为 false

注释限制只能调低操作容量，不能调高；MaxBytes 还受操作内存除以 64 约束，工作存储受操作内存一半约束，导出字节受输出上限约束

导入接受既有的 signaturePolicy 对象用于 CAdES、信任和时间戳校验设置，并执行注释权限与经认证的 DocMDP 策略

空 ABI 导入保留已提交的 PDF 字节，同时返回零更新

本地具名与显式目标以及 GoTo action通过共享注释编解码器保留真实页引用和设界的精确十进制坐标

ELF SONAME 和 HOTPDF_1.0 符号版本保持不变，既有 C 消费方继续使用同一公开操作描述符

映射 profile 与原生 API · Linux C ABI · Form 数据操作

标准 stamp 外观传输通过 base64 类型化 XML 保留真实的 Form 流以及有界的无环字体、图像和图形资源

FDF 对象图操作

{"schemaVersion":1,"type":"annotations.import","format":"fdf"}

二进制注释图选择 format="fdf"，沿用同一操作描述符与 InputIO、OutputIO、ResultIO 回调；annotations.export 把 FDF 字节写到 OutputIO

FDF profile 保留已提供的 AP 与 RO 资源、共享间接对象和上下文相关的本地 GoTo 页面引用；同一页面上匹配的注释 NM 标识要替换的注释，未命名或不匹配的注释会被追加

FDF 导入成功时报告 annotationProfile="pdf-object-graph-v1" 和整数 updated 计数；零更新的操作保留与最后一次提交完全一致的 PDF 字节

FDF annotationLimits 还接受 maxObjects；所有限制仍受外围操作约束，失败与取消保留既有回调事务保证

仅注释操作拒绝非空 Fields 和内嵌 Differences；action 数据只作为数据传输，不会被执行

参见FDF 图行为与边界和原生 FDF 限制

注释移除

{"schemaVersion":1,"type":"annotations.remove","annotations":[{"page":0,"name":"review-note"}]}

annotations.remove 使用当前文档或经 InputIO 提供的独立 PDF，先发布 PDF OutputIO 与 JSON ResultIO，之后才提交 context

结果报告 removed 和 annotationProfile="page-and-nm-removal-v1"；annotationLimits 限制注释计数、操作数、名称字节和工作存储

失败或取消保留已提交的 context；调用方需要自行暂存回调接收端，因为已写出的字节无法收回