JSON 與 C ABI 文件操作

export.structured 把選定頁面匯出為語意化 HTML、XHTML、XML 或 JSON;tables.export 把具型別表格匯出為 CSV、JSON 或 XLSX,保留跨頁連續性、合併儲存格與原生值推斷

兩種操作都需要二進位輸出目的地,保留文件與既有簽署欄位,並提供有界的原生匯出選項

結構化與具型別表格匯出

{"schemaVersion":1,"type":"export.structured","pages":[0,1],"format":"html",
 "options":{"imageMode":"metadata","includeFormControls":false}}

{"schemaVersion":1,"type":"tables.export","pages":[0,1],"format":"json",
 "options":{"mergeAcrossPages":true,"dateOrder":"dmy",
            "decimalSeparator":",","thousandsSeparator":"."}}

結構化匯出接受 html、xhtml、xml 與 json(預設);表格匯出接受 csv(預設)、json 與 xlsx

結構化布林選項有 includeCoordinates、includeStyles、includeImages、includeTables、includeAccessibilitySemantics、preferTaggedStructure、fallbackToGeometricSemantics、includeNavigation、includeAnnotations 與 includeFormControls,全部預設為 true

imageMode 接受 omit、metadata 與 embedded-png(預設);語意模型與敏感欄位行為請見結構化已載入頁面匯出

結構化資源選項有 maxPageCount、maxGlyphsPerPage、maxImagesPerPage、maxStructureNodes、maxOutlineItems、maxInteractionsPerPage、maxFormOptionsPerField、maxOutputBytes、maxImageBytes 與 maxTotalImageBytes

表格布林選項有 detectMergedCells、detectRepeatedHeaders、mergeAcrossPages 與 inferValueTypes,全部預設為 true

dateOrder 接受 ymd(預設)、mdy 與 dmy;分隔字元必須是單一可列印字元,空的 thousandsSeparator 表示停用

minimumTableConfidence 接受 0 到 1,預設 0.55;正的 columnTolerance 預設 12 個頁面單位

表格資源選項有 maxPageCount、maxGlyphsPerPage、maxTableCount、maxRowCount、maxCellCount、maxTextCharacters 與 maxOutputBytes;儲存格模型請見具型別表格擷取

未知選項名稱、無效型別、不支援的格式與非正數限制都會被拒絕;要求的原生限制會被保守的記憶體與物件預算封頂

匯出暫存上限取 budget.outputBytes 與 budget.memoryBytes 四分之一兩者中較小者;effectiveOutputLimit 回報該上限,較緊的 options.maxOutputBytes 也可能生效

原生資源失敗回報 budget-exceeded、指標 nativeExportResources 與原生診斷;observed=1 且 limit=0 代表資源被拒絕,而不是實測位元組用量

兩種操作都回報 documentUpdated: false,保留來源自動啟動與解碼設定,在發布前先暫存輸出,檔案作業失敗後保留既有檔案目的地

期限與 ABI 回呼取消檢查在操作與發布檢查點採合作式;原生取消權杖也在支援的擷取階段內生效,原生工作不會被強制中斷

THPDFJobProcessor.ExecuteLoadedOperation 與 hpdf_document_execute_json_v1 共用同一個帶結構描述版本的文件操作引擎

以 THPDFJobProcessor.Capabilities 或 hpdf_capabilities_json_to_io 探測目前的操作名稱、格式、簽署設定檔、回呼行為與預設預算

操作

操作 JSON 使用 UTF-8 與 schemaVersion: 1;頁面索引從 0 起算,選定頁面陣列不可含重複項

原生取代 API 無法編碼某個符合項時,文字取代回報部分狀態;請檢查其每頁計數

外部 OCR 工作在內建 ASCII 預設引擎之外接受明確設定的 Tesseract CLI/DLL 與 RapidOCR CLI/DLL 引擎，附型別化設定、引擎逾時、像素上限與原子發佈

變更操作會拒絕含既有簽署欄位的文件,包括未簽署的預留位置;這類文件請改用原生增量 API 來保留簽章

增量 PFX 簽章接受未更動的留存來源,包含帶明確操作密碼的受支援加密 PDF,驗證每一個新舊 CMS,保留原始位元組與加密,支援既有的空欄位,檢查加密權限,並拒絕來源/輸出檔案互為別名

簽署會產生已簽署產物並還原原控制代碼,回報 documentUpdated: false;既有表單欄位仍可用,暫存簽署欄位會被移除,簽署後控制代碼仍可查詢或用於其他操作

PDF/A-4 點陣封存轉換

{
  "schemaVersion": 1,
  "type": "archive.pdfa4.raster",
  "acceptInformationLoss": true,
  "iccProfileFile": "profiles/sRGB.icm",
  "dpi": 150,
  "input": "source.pdf",
  "output": "archive.pdf"
}

把這個物件放進檔案作業的 operations 陣列,或透過 hpdf_document_execute_json_v1 以已載入控制代碼與二進位輸出回呼直接提供;C ABI 會忽略檔案作業的輸入/輸出路徑,改用其配接器

acceptInformationLoss 必須是 JSON 布林值 true,iccProfileFile 必須指向非空、不含 NUL 的路徑,對應執行主機上受支援的 sRGB matrix/TRC ICC 設定檔;相對設定檔路徑以行程工作目錄為基準解析

dpi 預設 150,接受 36 到 1,200 的整數;轉換涵蓋每個來源頁面,並拒絕任何 pages 成員

archive 結果物件回報 nativeValidationSucceeded、sourcePages、pagesRendered、rasterPixels、outputBytes、removedAnnotations、removedFormFields 與 removedEmbeddedFiles

archive.lossy 為 true,而 archive.lossProfile 中每個旗標都是 false:searchableText、vectorContent、interactiveContent、originalSignatures、annotationAppearances 與 structureIdentity

頁面內容變成 RGB 像素;註解與 widget 外觀會被省略,原始簽章不會帶入輸出。已載入來源仍然可用,包括 documentUpdated: false 與發布失敗之後;它先前的啟動、解碼、串流門檻、取消與轉譯設定都會還原

必須提供二進位輸出,且原生 PDF/A-4 驗證必須在交付前成功;轉譯、色彩、編解碼器、來源別名與符合性邊界請見已載入 PDF/A-4 點陣轉換

封存資源預算

選用的 options 物件接受正精確整數,用於收緊下列有效上限;未知鍵與超過上限的值會拒絕請求,而不是放大操作預算

ICC 檔在配置前上限取 4 MiB 與 memoryBytes / 16 中較小者;這些保守額度已考慮同時進行的暫存、輸出緩衝、影像資料與解碼工作,並不構成嚴格的行程 RSS 上限

封存工作量的確需要更大時,請調高頂層作業預算;巢狀選項只能收緊有效上限,原生最大值仍然適用

封存檢查點在轉換期間輪詢回呼取消、借用的來源取消權杖、經過時間與物件計數;預算與取消失敗在原生轉換器之間保留其結構化狀態碼

檔案作業

{
  "operations": [
    {"type": "capabilities"},
    {"schemaVersion": 1, "type": "text.extract", "input": "input.pdf",
     "pages": [0, 1], "output": "text.txt"}
  ]
}

THPDFJobProcessor.Execute 接受 operations 陣列,最多 1,024 個操作與 4 MiB JSON;既有的合併、分割、最佳化、加密與驗證作業仍然可用

每個文件操作都提供輸入路徑與選用密碼;render、text.replace、forms.fill、forms.flatten、ocr.layer、redact、sign 與 archive.pdfa4.raster 需要輸出路徑

產物會寫到目的地旁的暫存檔,沖刷並驗證後再原子式發布;失敗時保留既有目的地,輸入/輸出可共用同一路徑

C 回呼合約

將 hpdf_operation_v1 歸零初始化,struct_size 設為其原生大小,abi_version 設為 HPDF_ABI_VERSION_1,flags 設為零;並把其大小與 hpdf_abi_operation_v1_size 比對

操作記錄承載 JSON 位元組與精確長度、選用的隨機存取輸入、選用的循序二進位輸出,以及必要的循序 JSON 結果輸出

輸入回呼、使用者資料與底層 PDF 位元組必須保持有效,直到控制代碼被取代或銷毀,因為延遲解析會保留該配接器

輸出/結果回呼只在呼叫期間存在;每個控制代碼的呼叫請序列化,並避免回呼重入

回呼使用 cdecl,部分傳輸會重試,成功寫入必須有實質進度;例外會轉成固定狀態碼

變更只在產物與 JSON 結果都成功送達後才提交;回呼失敗或取消會回滾變更,呼叫端須丟棄已送達的位元組

取代輸入在變更交易之前載入,仍然是獨立的狀態變更

預算

選用的預算物件接受不超過 9,007,199,254,740,991 的正精確整數

一般輸出/結果預算各自以記憶體預算的一半封頂;封存轉換適用前述更緊的上限。這些限制約束的是已配置的操作資源,而不是行程總記憶體

取消與經過時間檢查在操作、頁面、輸入讀取與輸出寫入檢查點採合作式;長的原生常式可以繼續跑到下一個檢查點

報告攜帶 schemaVersion、status 與 statusCode;預算錯誤用 status 8,取消 4,I/O 失敗 5,解析失敗 6,無效引數 1,執行失敗 7