JSON and C ABI Document Operations

export.structured exports selected pages as semantic HTML, XHTML, XML, or JSON; tables.export exports typed tables as CSV, JSON, or XLSX, retaining cross-page continuity, merged cells, and native value inference

Both operations require a binary output destination, preserve the document and existing signature fields, and expose bounded native export options

Structured and typed table exports

{"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":"."}}

Structured export accepts html, xhtml, xml, and json (default); table export accepts csv (default), json, and xlsx

Structured Boolean options are includeCoordinates, includeStyles, includeImages, includeTables, includeAccessibilitySemantics, preferTaggedStructure, fallbackToGeometricSemantics, includeNavigation, includeAnnotations, and includeFormControls; all default to true

imageMode accepts omit, metadata, and embedded-png (default); see Structured Loaded-Page Export for the semantic model and sensitive-field behaviour

Structured resource options are maxPageCount, maxGlyphsPerPage, maxImagesPerPage, maxStructureNodes, maxOutlineItems, maxInteractionsPerPage, maxFormOptionsPerField, maxOutputBytes, maxImageBytes, and maxTotalImageBytes

Table Boolean options are detectMergedCells, detectRepeatedHeaders, mergeAcrossPages, and inferValueTypes; all default to true

dateOrder accepts ymd (default), mdy, and dmy; separators must be individual printable characters, with an empty thousandsSeparator disabling it

minimumTableConfidence accepts 0 through 1 and defaults to 0.55; positive columnTolerance defaults to 12 page units

Table resource options are maxPageCount, maxGlyphsPerPage, maxTableCount, maxRowCount, maxCellCount, maxTextCharacters, and maxOutputBytes; see Typed Table Extraction for the cell model

Unknown option names, invalid types, unsupported formats, and nonpositive limits are rejected; requested native limits are capped by conservative memory and object budgets

Export staging is capped at the smaller of budget.outputBytes and one quarter of budget.memoryBytes; effectiveOutputLimit reports that cap, whilst tighter options.maxOutputBytes may apply

Native resource failures report budget-exceeded, metric nativeExportResources, and the native diagnostic; observed=1 and limit=0 denote a denied resource condition rather than measured byte usage

Both operations report documentUpdated: false, preserve source auto-launch and decode settings, stage output before publication, and retain existing file destinations after a failed file job

Deadline and ABI callback cancellation checks are cooperative at operation and publication checkpoints; native cancellation tokens also apply inside supported extraction stages, and native work is not forcibly interrupted

THPDFJobProcessor.ExecuteLoadedOperation and hpdf_document_execute_json_v1 share the same schema-versioned document operation engine

Discover the current operation names, formats, signing profile, callback behaviour, and default budgets with THPDFJobProcessor.Capabilities or hpdf_capabilities_json_to_io

Operations

Operation JSON uses UTF-8 and schemaVersion: 1; page indices are zero-based and selected page arrays cannot contain duplicates

Text replacement returns a partial status when the native replacement API cannot encode a match; inspect its per-page counts

External OCR jobs accept explicitly configured Tesseract CLI/DLL and RapidOCR CLI/DLL engines alongside the built-in ASCII default, with typed settings, engine timeouts, pixel caps and atomic publication

Mutations reject documents with existing signature fields, including unsigned placeholders; use the incremental signing profile or native incremental APIs to preserve signatures in those documents

Incremental PFX signing accepts an unmodified retained source, including supported encrypted PDFs with an explicit operation password, validates every old and new CMS, preserves original bytes and encryption, supports an existing empty field, checks encryption permissions and rejects source/output file aliases

Signing produces a signed artefact and restores the original handle, reporting documentUpdated: false; existing form fields remain available, temporary signature fields are removed, and the handle can be queried or used for another operation after signing

PDF/A-4 raster archival conversion

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

Place this object in a file job's operations array, or supply it directly through hpdf_document_execute_json_v1 with a loaded handle and binary output callbacks; the C ABI ignores file-job input/output paths and uses its adapters

acceptInformationLoss must be the JSON Boolean true, and iccProfileFile must name a nonempty, NUL-free path to a supported sRGB matrix/TRC ICC profile on the execution host; relative profile paths resolve against the process working directory

dpi defaults to 150 and accepts integers from 36 through 1,200; conversion covers every source page and rejects any pages member

The archive result object reports nativeValidationSucceeded, sourcePages, pagesRendered, rasterPixels, outputBytes, removedAnnotations, removedFormFields, and removedEmbeddedFiles

archive.lossy is true, and every flag in archive.lossProfile is false: searchableText, vectorContent, interactiveContent, originalSignatures, annotationAppearances, and structureIdentity

Page content becomes RGB pixels; annotations and widget appearances are omitted, and original signatures are not carried into the output. The loaded source remains available with documentUpdated: false, including after failed publication; its prior launch, decode, stream-threshold, cancellation, and render settings are restored

Binary output is required, and native PDF/A-4 validation must succeed before delivery. For rendering, colour, codec, source-alias, and conformance boundaries, see loaded PDF/A-4 raster conversion

Archival resource budgets

The optional options object accepts positive exact integers that tighten the following effective caps; unknown keys and values exceeding a cap reject the request rather than increasing the operation budget

The ICC file is capped at the smaller of 4 MiB and memoryBytes / 16 before allocation; these conservative allowances account for simultaneous staging, output buffers, image data, and decoder work, and do not establish a strict process-RSS limit

Increase the top-level job budgets when a larger archival workload is intentional; nested options only tighten the effective caps, and native maximums still apply

Archival checkpoints poll callback cancellation, the borrowed source cancellation token, elapsed time, and object counts during conversion. Budget and cancellation failures retain their structured status codes across the native converter

File jobs

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

THPDFJobProcessor.Execute accepts an operations array, up to 1,024 operations and 4 MiB of JSON; existing merge, split, optimise, encrypt, and validate jobs remain available

Each document operation supplies an input path and optional password; render, text.replace, forms.fill, forms.flatten, ocr.layer, redact, sign, and archive.pdfa4.raster require an output path

Artefacts are written to a temporary file beside the destination, flushed and validated, and then atomically published; failure preserves an existing destination and input/output may share a path

C callback contract

Zero-initialise hpdf_operation_v1, set struct_size to its native size, abi_version to HPDF_ABI_VERSION_1, and flags to zero; compare its size with hpdf_abi_operation_v1_size

The operation record carries JSON bytes and an exact length, optional random-access input, optional sequential binary output, and required sequential JSON-result output

Input callbacks, user data, and backing PDF bytes must remain valid until the handle is replaced or destroyed, because lazy parsing retains the adapter

Output/result callbacks exist only during the call; serialise calls for each handle and avoid callback re-entry

Callbacks use cdecl, partial transfers are retried, and successful writes must make positive progress; exceptions are converted to fixed status codes

Mutations commit only after both artefact and JSON-result delivery succeed; callback failure or cancellation rolls back changes, and callers discard any bytes already delivered

Replacement input is loaded before the mutation transaction and remains a separate state change

Budgets

The optional budget object accepts positive exact integers no greater than 9,007,199,254,740,991

General output/result budgets are each capped at half the memory budget; archival conversion applies the stricter caps above. These bound configured operation resources rather than total process memory

Cancellation and elapsed-time checks are cooperative at operation, page, input-read, and output-write checkpoints; a long native routine can continue until its next checkpoint

Reports carry schemaVersion, status, and statusCode; budget errors use status 8, cancellation 4, I/O failure 5, parse failure 6, invalid arguments 1, and execution failure 7