Embedded FDF packages and held imports

HPDFFDFPackage opens an FDF package in memory, describes embedded file entries, extracts stored or decoded child bytes, and adds or replaces embedded children without opening referenced file paths or executing actions

The package API is separate from PDF document encryption and from applying an embedded document revision; importing a selected FDF child applies its supported field values and optionally its annotation graph to a loaded PDF

Explicit child paths

Each THPDFFDFChildSelection contains an entry Index, an explicit FileKey, an explicit Mode and password bytes; admitted file keys are F, UF, DOS, Mac and Unix

femPlain selects an unencrypted child and femRevision1 selects the supported embedded FDF encryption revision 1; the declared mode must match the stream metadata, and password bytes apply only to revision 1

HPDFSelectEmbeddedFDF requires a nonempty path and follows only those explicitly selected children; it never falls back to an arbitrary entry, guesses a password or automatically imports every embedded file

A child returned by DecodeChild owns its graph and retains a reference to the same session budget, so it can outlive the parent package

Held document imports

PrepareEmbeddedFormDataFDF selects and decodes the child once, retains its typed fields and annotation projection, and returns a THPDFHeadlessPreparedEmbeddedFDF for planning and publication

CopyFields returns a separately owned field array and value arrays; the held plan also owns copies of mutable style-sheet, selector and image-resource arrays, including each image byte buffer

SavePreparedEmbeddedFormDataFDFToFile uses the same held input and cumulative budget instead of selecting or decoding the package again; the result reports changed fields and changed annotations separately

IncludeAnnotations defaults to True on the native preparation method; pass False for a field-only import and supply actual regular, bold, italic and bold-italic fonts required by the selected rich values

The convenience method SaveEmbeddedFormDataFDFToFile prepares and publishes a mixed field-and-annotation import in one call; use the held API when planning must inspect the selected fields first

Ownership, failure and adoption

A held plan belongs to the document instance and loaded source lifetime that created it; another document, a source reload or source destruction invalidates its use

Successful atomic publication marks the plan committed and prevents another publication with that plan; failure leaves it uncommitted, allowing a retry with its existing cumulative budget

A failed attempt does not reset budget charges already incurred; a later retry can therefore exceed the remaining allowance

Native save methods leave the loaded document unchanged after both success and failure; load the saved PDF explicitly to adopt it, and free the plan before adopting a new source

Source aliases, empty or NUL-containing output paths, invalid selected values, cancellation and policy failures preserve an existing destination; unpublished private files are removed

Limits and policy

THPDFFDFPackageOptions combines per-graph limits with cumulative byte, node, object, operation, working-storage and package-depth allowances; descendants, planning and commit retain the same budget identity

Supported byte filters include ASCIIHex, ASCII85, Flate, RunLength and LZW, with the implemented TIFF and PNG predictor profiles; decoding validates malformed data and rejects expansion beyond the configured allowance

Selected field changes retain AcroForm, read-only, DocMDP and FieldMDP checks; selected annotation changes retain their separate annotation permission and certification-policy checks

Applying embedded PDF Differences, arbitrary actions and incremental FDF revision histories is outside this import API; embedded revision-1 decryption does not grant permission to alter the destination PDF

The working allowance is an admission budget for the implemented paths, not an exact process-heap limit; workspace-aware rich-layout, font, image, shaping and ordering paths use a shared borrowed owner, with temporary storage and retained PDF identities tracked separately

Native field interchange · Binary annotation graphs · Package API

A package carrying a Differences stream feeds the FDF Differences transport through DecodeDifferences

See workspace admission for compatible native runtimes, cancellation and result lifetimes