THPDFHeadlessDocument
HPDFHeadlessDocument 使用既有的 HotPDF 物件解析器、Direct File 輔助器、字型解碼器、內容直譯器、filter 解碼器與 xref 寫入器，為原生 Linux 與 Windows 提供主控台文件 API
文件載入器接受傳統交叉參照表、xref 串流、混合 xref 區段、增量 Prev 鏈、直接與壓縮物件、繼承的頁面資源、內容陣列、Form XObject 與 AcroForm 欄位樹
混合側串流優先於伴隨的表，較新修訂版優先於較舊修訂版；object-stream 成員透過共享物件解析器延遲解碼與解析
生命週期與所有權
Create 使用 THPDFHeadlessDocumentOptions.Default，選項多載則接受明確預算與呼叫端自有的取消 token
LoadFromFile 關閉先前文件，以唯讀開啟來源，載入目前物件圖，失敗時關閉部分狀態；Close 釋放來源與所有已載入物件
LoadFromFile(FileName, Password) 透過 THPDFHeadlessAES256Security 認證 Standard AES-256 R5 或 R6 文件；原始單參數多載使用空密碼
user password 必須在那些操作執行前授予文字抽取或表單填寫權限，owner password 則繞過使用者權限限制；錯誤密碼、認證 Perms 不符、被拒操作與格式錯誤的加密負載各有獨立的文件診斷
直接字串與串流透過共享密碼學程式碼解密，壓縮成員只隨其容器解密，加密增量替換在原始金鑰與權限政策下保持加密
密碼使用 UTF-8 bytes，在 127 bytes 處截斷，不做 SASLprep 正規化；不支援的 handler、明確 Crypt filter 與 PDF MAC 政策會被診斷而非忽略
編碼的字典鍵與資源名稱使用前解碼，大小寫維持敏感，重複的解碼鍵會被拒絕；欄位旗標與 MaxLen 必須落在受支援的非負 32 位元範圍
實例不具執行緒安全；每個 worker 用一個實例，並保持其取消 token 存活直到實例銷毀
頁面與文字
PageCount 回報頁面樹葉節點數；ExtractPageText(PageIndex) 接受以零起算的索引，回傳由共享字形直譯器組裝的 Unicode 文字
ExtractPageTextBounded 在文字準備前套用暫時的字形與串流上限，並在成功、失敗或取消後還原所有原始資源選項
GetObjectAccess 暴露唯讀借用的 catalog、information 與物件存取，帶有界索引配置，供 原生結構與完整比較使用
文字解碼遵循字型編碼、編碼差異、內嵌 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
這個僅值方法依賴檢視器重新產生外觀；不重新產生外觀的檢視器可能繼續顯示舊外觀或空的 widget
SetTextFieldValueWithAppearance 使用呼叫端提供的 TrueType 字型、實際字形度量、Identity-H 編碼、ToUnicode 與完整 FontFile2 內嵌，為每個既有 widget 產生明確的 Unicode 外觀
外觀設定檔支援單行與多行文字、換行、comb 儲存格、直角旋轉、固定大小或自動調適、對齊，以及選填的原生 HarfBuzz/FriBidi 複雜 shaping
SetChoiceFieldValuesWithAppearance 處理多選清單方塊、繼承選項、排序匯出陣列與每個可見的選取列；單值輔助方法也支援 combo 匯出/顯示標籤
GetChoiceFieldValues 讀取完整的選取匯出陣列；SetButtonFieldValueWithAppearance 與 SetPushButtonAppearance 產生實際的按鈕狀態與標題
新外觀物件與串流在欄位變更前受有界約束，儲存時在原始 AES 安全政策下保持加密；原生 Linux Cairo 與獨立閱讀器消費相同的產生物件
文字欄位方法強制唯讀旗標、以 UTF-16 code unit 計的 MaxLen 與欄位型別檢查；choice 與 button 欄位使用各自的外觀方法，而 XFA 表單不在這個文件載入器的 AcroForm profile 之內
已簽章文件使用經驗證的 DocMDP 與 FieldMDP 政策：獲准的表單更新保留既有已簽章修訂版，而鎖定欄位、P1 限制與覆寫已簽章簽章欄位的嘗試都會被拒絕
驗證過的 DSS/VRI 證據為增量修訂版加入認證的憑證與撤銷資料，不改變既有 ByteRange 簽章
簽章驗證
SignatureCount 列舉已簽章的 AcroForm 簽章欄位，VerifySignature(SignatureIndex, Options) 使用共享解析器與串流 OpenSSL 3 CMS provider 驗證以零起算的簽章
PDF 設定檔接受 adbe.pkcs7.detached 與自動識別的 ETSI.CAdES.detached，Contents 可為十六進位或標準 literal；CAdES 一律認證 ESS signing-certificate 綁定，明確 CA 設定則另行評估信任
帶 ETSI.RFC3161 的 DocTimeStamp 自動認證真實的封裝 TSTInfo、ESS、TSA 用途與簽署者名稱，以及精確的 PDF imprint；設定的時間戳記根憑證與 CRL 另行評估 TSA 信任
驗證會檢查精確的未簽章間隙（含其分隔符），並在密碼學驗證前把解碼 bytes 綁定到目前簽章字典
結果區分完整性、明確評估的 CA 信任，以及認證修訂版之後的未簽章 bytes；不支援的 PDF 簽章設定檔產生帶類型的診斷
執行期需求見 HPDFVerifyHeadlessCMS，預算與信任設定見 THPDFHeadlessCMSOptions
增量核可簽章
SignToFile 簽署既有的可寫、未簽章 Sig 欄位，並使用呼叫端提供的 PEM 憑證與未加密 PEM 私鑰發布獨立的增量更新 PDF
AddSignatureField 建立頁面 widget 與其 AcroForm 連結，包括在純匯入 PDF 上建立新 AcroForm；SetSignatureFieldAppearance 產生其可見標題，SignPFXToFile 載入帶鏈的 PKCS12 憑證/金鑰身分
CertificationPermission 建立第一個 DocMDP 認證簽章；P2 與 P3 允許在既有欄位中後續核可簽章，P1 則拒絕進一步簽章
原始來源 bytes 與已載入物件圖保持不變；後續核可簽章保留較早的簽章 bytes 與其認證修訂版邊界
Standard AES-256 R5 與 R6 加密、密碼、ID 與權限持續生效，包括加密 object-stream 來源；簽章 Contents 字串遵循 PDF 的加密豁免
既有簽章值、唯讀欄位、認證文件政策、被拒的表單填寫權限、分歧的取消 token 與耗盡的輸出預算都會被拒絕，不發布輸出
文件時間戳記
TimestampToFile 在既有未簽章簽章欄位中建立真實的 RFC 3161 文件時間戳記，不需要應用程式簽章金鑰，使用呼叫端自有的 TSA 傳輸與明確 TSA 信任
寫入器保留原始修訂版與 AES 安全性，為 PDF 2.0 之前的輸入宣告 ESIC 擴充，並只在 nonce、imprint、簽章、憑證、設定的撤銷與 seed 檢查都通過後原子發布
必要的認證文件時間戳記變更在 DocMDP 與 FieldMDP 下允許；一般表單編輯與核可簽章保留其原始限制
FDF 與 XFDF 表單交換
ExportFormData 回傳有界的 Unicode 欄位資料，包括實際 choice 陣列與核取方塊或選鈕匯出狀態
ImportFormDataToFile 在私有認證修訂版圖形上重新產生真實外觀，並原子發布增量 PDF，同時保留已載入來源狀態
ImportRichFormDataToFile 從 FDF RV 或 XFDF value-richtext 匯入有界 XHTML 設定檔，使用實際的 regular、bold、italic 與 bold-italic 字型程式
SaveRichTextFieldUpdatesToFile 在單一獨立原子修訂版中套用純量欄位與原始輸入富 run，保留實際字型程式與 PDF 數值精度；未變更的受保護欄位要求每個 widget 的解碼外觀與解析資源都相符
既有加密、唯讀旗標、認證 DocMDP 與 FieldMDP、原始簽章、取消與資源預算持續強制執行；受支援語法與純量交換邊界見 原生 FDF 與 XFDF 表單資料
ExportAnnotationsFDF 匯出有界註解物件圖形及其共用外觀資源；SaveAnnotationsFDFToFile 在獨立的原子 PDF 修訂版中準備具名替換並執行附加
二進位 FDF 註解 profile 保留已驗證文件的加密與簽章政策、情境相關的本地 GoTo 頁面參照，以及精確的未變更發佈；儲存後已載入文件保持不變
SaveAnnotationsXFDFToFile 把有界映射註解附加到獨立的增量修訂版；HPDFExportHeadlessAnnotationsXFDF 回傳其 XFDF 位元組
借用的轉譯存取
GetRenderAccess(PageIndex) 透過 THPDFHeadlessRenderAccess 提供既有頁面字典、繼承資源、字型解析器、物件解析、權限檢查、取消 token 與有界解碼串流回呼
這是序列唯讀借用視圖；文件必須在轉譯器完成前保持載入且不變，呼叫端不得變更其暴露的物件圖
視圖的 RequireOutputPath 回呼對照來源的標準路徑與實體檔案識別檢查預期輸出，不建立或修改檔案
獨立輸出
ExtractPageGlyphs 透過有界巢狀內容走訪器回傳帶位置的字形；AnalyzePageSemanticText 為 原生契約比較提供語意文字與來源幾何
SaveToFile(FileName) 複製原始 bytes 並附加替換物件值、傳統 xref 表，以及透過 Prev 連結的 trailer；壓縮物件成員在附加修訂版中具現化為直接物件，原始串流 bytes 保留
輸出不得別名來源路徑或檔案識別；寫入使用目的地目錄中獨佔建立的暫存檔，沖寫後以原子改名發布
預算、取消或序列化失敗會保留既有目的地並刪除未發布的暫存檔；來源保持唯讀
原生標註審閱 PDF 匯出實際 Unicode 高亮與可見外觀，附認證註解權限，保留原始已載入文件與簽章修訂版
格式界限
目前設定檔支援 Standard AES-256 R5 與 R6 加密，明確診斷不支援的安全 handler 與串流 filter，並拒絕其寫入器無法表達的退役自由物件代
Bootstrap xref 串流要求直接字典值與直接有界 Length；格式錯誤的寬度、子區段重疊、超過 Int64 的無號偏移、壓縮成員不符、參照循環與設定的上限都產生帶類型診斷
解碼內容支援 Flate、ASCIIHex、ASCII85 與 LZW filter，含受支援的預測器與間接串流長度；影像負載不為文字抽取解碼
原生簽章工作流程涵蓋簽章欄位、可見外觀與認證；認證簽章表單政策、時間戳記與長期驗證 API 保留其明確完整性與信任選項
驗收
具名富字族透過 SetRichTextFieldValueWithFamilies 與 ImportRichFormDataWithFamiliesToFile 加入多個實際提供的字族，沿用既有的欄位、安全性與交易政策
原生富文字欄位提供帶型別樣式 run、實際內嵌樣式字型外觀、同步的 V 與 RV 值、加密增量輸出與有界交易式編輯；GetRichTextFieldValue 讀取儲存或繼承的 XHTML
Tests/Linux/Run-HeadlessDocumentTests.sh 以清除桌面變數建置原生 ELF 執行檔，並檢查 GUI 程式庫依賴；Run-HeadlessDocumentTests-Windows.cmd Win32 與 Win64 對相同的共享文件 API 做演練
回傳值與帶類型診斷見 THPDFHeadlessFormField、EHPDFHeadlessDocumentError 與 THPDFHeadlessDiagnosticCode
註解移除
透過 SaveAnnotationRemovalsToFile 按精確頁面與 Unicode NM 識別移除頁面註解，包含 popup 與回覆級聯、有界準備以及原子的獨立輸出
已載入文件保持不變；未變更的選取會複製精確的目前修訂版，增量移除保留歷史位元組