Standard XFDF stamp appearance transport

Stamp annotations can export and import their actual PDF appearance streams and resource dictionaries through the Adobe XFDF appearance element

The stamp-typed-xml-v1 profile uses base64-encoded UTF-8 typed XML, as described by the Adobe XFDF 3 specification; the decoded payload represents PDF objects rather than a complete PDF or FDF file

Mapped resources

The top-level DICT KEY="AP" contains a required normal N Form stream and optional rollover R and down D streams

Forms retain their finite four-number BBox, optional six-number Matrix and supported resource graph, including fonts and their embedded programs, images and soft masks, color spaces, patterns, shadings, functions and graphics states

Typed values include DICT, STREAM, ARRAY, INT, FIXED, NAME, BOOL and NULL; dictionary keys and name values preserve their semantic PDF names, and valid source number tokens preserve decimal precision

Stream DATA supports MODE="RAW" or MODE="FILTERED" with ENCODING="HEX" or seven-bit ENCODING="ASCII"; RAW retains the encoded bytes and their Filter/DecodeParms, while FILTERED installs decoded bytes without stale filtering metadata

Export uses RAW hexadecimal data and regenerates stream Length from actual bytes; authenticated encrypted streams are decoded or decrypted before exchange and encrypted correctly in the saved revision

Shared acyclic resources are expanded as equivalent values and imported with independent object references; this profile does not preserve reference identity

Embedded font program bytes and their embedding flags are preserved without changing license bits or substituting a different font program

APIs and callbacks

Use HPDFExportHeadlessAnnotationsXFDF and SaveAnnotationsXFDFToFile for native transactions, or the bounded overloads of HPDFXFDFExportAnnotations and HPDFXFDFImportAnnotations for caller-owned graph adapters

The existing Windows file jobs and V1 callbacks and Linux V1 callbacks use their existing annotation operations and record layouts

Capabilities retain appearanceImport=false for general annotation appearances and add stampAppearanceImport=true, appearanceProfile="stamp-typed-xml-v1", appearanceTypes=["stamp"], appearanceDataModes=["RAW","FILTERED"], appearanceEncodings=["ASCII","HEX"] and appearanceResources="acyclic-expanded-graph"

Transactions and limits

Input XML, base64, names, stream encoding, resource types, semantic dictionary keys and Form geometry are validated before publication; malformed data, cycles, exhausted cumulative limits or cancellation fail the complete transaction

XFDF limits cover total input/output, XML and graph nodes, depth, stream storage and working reservations across the annotation operation

Import retains current unsaved graph state, AES R5/R6 security and authenticated certification restrictions; P1/P2 deny annotation changes and P3 preserves the original signed prefix and genuine signature integrity

An authorized empty import returns zero and preserves exact current PDF bytes when there are no unsaved changes; dirty graph changes are saved without being discarded

Windows and Linux callback contexts adopt a prepared PDF only after PDF output, JSON result output and the final cancellation check succeed; failed or partial callbacks retain the prior context, and the first failed writer remains sticky

Annotation-only import accepts empty fields containers and valueless field declarations as no-op metadata; actual form values and rich field updates require the separate authenticated form-data operation

Remaining work

General annotation AP transport, appearance state dictionaries, string resource values, nonempty DEFINE/REF references, cyclic graphs, Redact overlayappearance, annotation replacement/removal and FDF annotation exchange remain separate work

Geometric and text annotations without a transported stamp appearance retain their existing behavior; this operation does not synthesize arbitrary annotation appearances or execute actions

The shared bounded adapter reserves raw annotation keys and expanded AP graphs before payload conversion, and reserves base64 whitespace and decoded DATA before allocating those representations; PDF name conversion uses linear passes with cancellation checkpoints