Windows annotation FDF and XFDF exchange

Windows file jobs and hpdf_document_execute_json_v1 export mapped annotations and append XFDF annotations through the authenticated Windows transaction bridge

The mapped types and properties are shared with native annotation XFDF, including bounded binary attachment/sound streams, Unicode rich contents, popup objects and forward replies

File jobs

{
  "schemaVersion": 1, "type": "annotations.import", "format": "xfdf",
  "input": "source.pdf", "annotationInput": "annotations.xfdf",
  "output": "annotated.pdf", "password": "owner",
  "annotationLimits": {"maxBytes": 1048576, "maxAnnotations": 1000},
  "budget": {"memoryBytes": 268435456, "outputBytes": 134217728,
    "timeMilliseconds": 60000, "resultBytes": 16777216}
}

annotations.export uses the same format, input, output and optional password, writing UTF-8 XFDF rather than a PDF; import requires annotationInput

Output must not alias the PDF input, XFDF input or supplied trust/evidence files, including an existing hard link; publication reserves an exclusive temporary sibling, validates bounded results, flushes and closes the candidate, then atomically replaces the target

Failure and cancellation preserve an existing complete target and remove the operation's temporary file

Original V1 callbacks

Use the unchanged hpdf_operation_v1 and hpdf_io_v1 from hotpdf_abi.h; annotation exchange requires no font extension

Load the destination PDF with hpdf_document_load_from_io first; import reads XFDF from InputIO, writes the candidate PDF to OutputIO and writes bounded JSON to ResultIO; export reads the active owned PDF and writes XFDF to OutputIO

For encrypted input, repeat the operation password used to authenticate the loaded PDF; this operation does not retain an implicit password from the earlier load call

Only successful PDF and result callbacks followed by the final cancellation checkpoint adopt the new document and owned revision; failed input, output or result callbacks, malformed XML, exhausted limits and cancellation retain the prior context

Callbacks may receive candidate bytes before a later failure; publish a caller-owned destination only after HPDF_STATUS_OK returns

Policy, limits and results

Import authenticates existing signature integrity and ESS signer binding; P1 and P2 certification deny annotation changes, whilst P3 permits an annotation revision that retains the original signed bytes

AES-256 R5/R6 imports preserve encryption parameters and the original revision prefix; an empty import authenticates policy and preserves the exact current bytes

signaturePolicy accepts the existing Boolean trust/timestamp/revocation requirements and explicit trust paths described in Windows form-data exchange

annotationLimits can lower maxBytes, maxAnnotations, maxNodes, maxDepth and maxWorkingBytes; values are positive integer JSON numbers and cannot raise the computed defaults

Working, output, result, object and page budgets also apply; callback operations accept elapsedMilliseconds as an additional tighter deadline

Export reports annotationCount, skippedAnnotationCount, decodedAttachmentBytes and outputBytes; import reports updated, outputBytes and annotationProfile equal to mapped-annotations-v1

Boundaries

Capabilities advertise annotation exchange through file-job and execute-json-v1, with append-only import, general appearanceImport=false and scoped stampAppearanceImport=true

Standard stamp appearance transport preserves actual Form streams and bounded acyclic font, image and graphics resources through base64 typed XML

General XFDF AP syntax, XFDF annotation replacement/removal and wider XFDF actions remain separate work; remote GoToR actions and local destinations use their existing bounded profiles

The generic ExecuteLoadedOperation and older job-handle callback record are separate entry points; Pascal callers can use the explicit transaction class

Binary FDF exchange

The same file jobs and V1 callbacks accept format="fdf"; file imports read binary FDF from annotationInput, and exports write binary FDF to the selected output

The FDF object-graph profile preserves supplied appearance resources and shared indirect objects, and supports replacement by a matching nonempty annotation NM on the same page

FDF import returns annotationProfile="pdf-object-graph-v1"; updated counts actual annotation changes, and an equivalent import preserves the exact current revision

FDF adds maxObjects to the positive integer annotationLimits controls and uses the existing authenticated policy, bounded candidate publication and callback ownership rules

Pascal callers can use THPDFWindowsFormDataTransaction.ExportAnnotationsFDF and ImportAnnotationsFDF; ChangedAnnotations reports actual changes for this profile

Nonempty FDF Fields and embedded Differences require separate handling and fail annotation-only operations before publication

Windows annotation removal provides a separate prepared transaction and JSON job for exact page-and-NM identities without changing mapped XFDF append semantics