Native annotation XFDF exchange

HPDFHeadlessXFDF exports mapped annotations from a loaded native PDF graph and prepares XFDF annotation imports as an independent incremental revision

Use HPDFExportHeadlessAnnotationsXFDF for UTF-8 XML bytes and SaveAnnotationsXFDFToFile to append annotations to an existing document without changing the loaded source graph

Mapped annotation profile

The profile maps Text, FreeText, Line, Square, Circle, Polygon, PolyLine, Highlight, Underline, StrikeOut, Squiggly, Stamp, Ink, Caret, FileAttachment, Sound, Redact and Link

Common values include page, rectangle, Unicode contents, author, annotation name, dates, subject, flags, opacity, colours and supported border properties

Type-specific values include quadrilateral coordinates, vertices, ink gestures, line endings and leader geometry, FreeText intent/callout/fringe/default text properties, Redact repeat state, URI or Named link actions, remote GoToR actions and named or explicit local destinations and GoTo actions

Empty colour component arrays preserve transparent colours; Gray and CMYK source colours are mapped to XFDF RGB values, and RGB components are quantised to the format's six-digit hexadecimal representation

FileAttachment exports prefer the Unicode file name and preserve external file metadata even when no embedded stream exists; embedded file and sound data are decoded into bounded canonical base64 and imported as actual indirect streams, including empty streams

Popup annotations are represented as nested popup elements and imported with indirect Parent, Popup and page links; replies resolve in a second pass against existing and newly appended annotation names, including forward references

Rich contents preserve the XHTML namespace, ordered mixed text and inherited namespace bindings

Transactions and permissions

Imports append annotations and reject duplicate names, ambiguous or missing reply targets and invalid mapped values before publication

A failed or cancelled import preserves the destination file and the loaded source graph; a successful import also leaves the loaded source unchanged, so load the saved file when you want to adopt its new revision

Export requires extraction permission and import requires annotation permission; AES-256 R5/R6 security remains in the saved revision

Actual certification policy is authenticated through the native signature workflow: P1 and P2 prevent annotation changes, whilst P3 permits an annotation revision that preserves the original signed bytes

Bounds

THPDFHeadlessXFDFOptions bounds input/output bytes, annotation count, graph and XML nodes, depth and working storage, with cooperative cancellation

Mapped numbers must be finite and within an absolute value of one million, with additional constraints for coordinate counts, opacity, sample sizes and other typed values

Whole-document XML admission checks encoding, namespaces, duplicate attributes, entities and complete structure before annotation mapping; DTD and external entity processing are disabled

Operation boundaries

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

General annotation AP transport, custom annotation dictionaries, annotation replacement/removal, arbitrary actions and FDF annotation data remain separate work

Annotation appearance synthesis and rendering are separate operations; importing geometric and text properties does not create an AP stream

Other source annotation subtypes are skipped during export and counted in the result; malformed selected mapped values fail the operation with no partial returned XML

The native Pascal API works on Windows and Linux; the versioned Linux C ABI also exposes callback-based JSON annotation operations, and Windows file jobs and V1 callbacks expose the same mapped annotation exchange

Explicit annotation removal

Page-and-name annotation removal is a separate operation; omitting an annotation from imported FDF or XFDF does not delete it

Widget field-tree deletion and secure erasure require separate operations; incremental removal retains previous PDF bytes