Struct XfaSession 

pub struct XfaSession { /* private fields */ }

Parse-once session over a single XFA PDF.

Holds the extracted packets, the parsed datasets DOM, the merged form tree, and the layout result. Field enumeration and value writes operate on the cached state; no re-parse or re-layout happens per call (Phase 1: value writes do not reflow the layout).

Implementations

impl XfaSession

pub fn open(pdf_bytes: &[u8]) -> Result<XfaSession, XfaError>

Open a session over the given PDF bytes.

Mirrors the flatten pipeline’s Extract → Bind → (static scripts) → saved-form-state → Layout stages, then caches everything.

Returns XfaError::PacketNotFound when the PDF has no XFA template packet (i.e. it is not an XFA form).

pub fn open_interactive(pdf_bytes: &[u8]) -> Result<XfaSession, XfaError>

Open a session in interactive mode (Phase 2).

Identical to open, then — when the xfa-js-sandboxed feature is compiled in — runs the interactive open lifecycle (initialize → docReady → calculate) with field.presence writes landing in the tree, re-layouts, and re-enumerates. The result reflects a dynamic form’s real initial visible state (the script-driven show/hide of conditional sections), not the static one-shot render.

Without the feature this is equivalent to open and commit_value degrades to a value write plus re-layout (no script-driven toggles).

pub fn page_count(&self) -> usize

Number of pages in the cached layout result.

pub fn page_size(&self, page: usize) -> Option<(f64, f64)>

Page dimensions (width, height) in points for a 0-based page index.

pub fn fields(&self) -> &[XfaFieldModel]

The enumerated field models, in document order.

pub fn field(&self, name: &str) -> Option<&XfaFieldModel>

Look up one field model by fully-qualified name. Accepts both the display name (a.b[2].c) and the explicit SOM path (a[0].b[2].c[0]).

pub fn set_value( &mut self, name: &str, value: XfaWriteValue<'_>, ) -> Result<XfaSetOutcome, XfaError>

Set a field’s value.

Updates the form-tree raw value, writes through to the bound datasets node (creating it on demand for default-bound fields), and records the change for save_to_bytes.

Rejects writes to read-only fields (XfaError::FieldReadOnly) and to non-fillable kinds (buttons, signatures, …). No change/click scripts run and the layout is not recomputed (Phase 1).

pub fn is_interactive(&self) -> bool

Whether interactive mode is active (the open lifecycle ran with presence writes and commits dispatch user-edit scripts). Only ever true with the xfa-js-sandboxed feature compiled in.

pub fn commit_value( &mut self, name: &str, value: XfaWriteValue<'_>, ) -> Result<XfaCommitOutcome, XfaError>

Phase 2 interactive commit. Set a field’s value, then run the dynamic effects: fire the field’s change/click scripts, a global calculate pass, re-layout, and re-enumerate the field/page model.

This is the interactive analogue of set_value: the data writeback is identical (so save_to_bytes still produces an Acrobat-reopenable PDF), but conditional sections that the committed value reveals or hides are reflected in the new fields / page_count.

Without the xfa-js-sandboxed feature this degrades to a value write plus re-layout: interactive == false, scripts_executed == 0, and no script-driven presence changes (a static value edit only).

pub fn script_report(&self) -> &XfaScriptReport

Scripts that did not run, over the whole session so far: FormCalc and other non-JavaScript scripts that were due, and JavaScript scripts that threw, timed out or were refused. Each script is counted once. Empty until the session is interactive.

pub fn save_to_bytes(&self) -> Result<Vec<u8>, XfaError>

Serialize the updated datasets (and form-packet value syncs) into a copy of the original PDF and return the new bytes.

pub fn write_into_document( &self, doc: &mut Document, ) -> Result<XfaWritebackReport, XfaError>

Apply the datasets/form-packet writeback to an already-loaded lopdf::Document (the SDK facade path: the caller owns the document and serializes it itself).

pub fn is_dirty(&self) -> bool

True when any value was changed since the session opened.