Struct HostBindings 

pub struct HostBindings { /* private fields */ }

Host-side state shared by QuickJS binding closures.

Implementations

impl HostBindings

pub fn new() -> Self

Create empty host-binding state.

pub fn set_form_handle(&mut self, form: *mut FormTree, root_id: FormNodeId)

Install or clear the form pointer used by host bindings.

pub fn reset_per_document(&mut self)

Reset counters and invalidate all existing handles for a new document.

Note: data_dom is intentionally NOT cleared here. The caller sets it explicitly via set_data_handle before calling apply_dynamic_scripts_with_runtime, and reset_for_new_document (which calls this) runs inside the dispatch function — after set_data_handle. Clearing it here would wipe the pointer before any scripts execute. The caller is responsible for managing DataDom lifetime.

pub fn set_data_handle(&mut self, dom: *const DataDom)

Phase D-γ: install the DataDom pointer for the current document.

Safety

dom must outlive all script execution for this document.

pub fn reset_per_script( &mut self, current_id: FormNodeId, activity: Option<&str>, )

Reset per-script state and install the current event context.

pub fn set_static_page_count(&mut self, page_count: u32)

Cache the page count visible to read-only page-count bindings.

pub fn generation(&self) -> u64

Current handle generation. Handles capture this and are invalid after a document reset.

pub fn current_node(&self) -> Option<FormNodeId>

Current script node for this.

pub fn root_node(&mut self, generation: u64) -> Option<FormNodeId>

Root form node for xfa.form.

pub fn subform_scope_chain( &mut self, node_id: FormNodeId, generation: u64, ) -> Vec<String>

Return the names of subform ancestors of node_id from innermost to outermost. Used by the implicit-globals proxy to resolve bare names that belong to a <variables> block in an ancestor subform (D-ι.2 scope chain). Iterative DFS from root; O(n) worst case, acceptable for the small form trees XFA templates produce.

pub fn take_metadata(&mut self) -> RuntimeMetadata

Read and clear host metadata counters.

pub fn mutation_log(&self) -> &[MutationLogEntry]

Mutation log for tests and debug reporting.

pub fn get_raw_value( &mut self, node_id: FormNodeId, generation: u64, ) -> Option<String>

Read field.rawValue; returns None for stale handles, missing nodes, and non-field nodes.

pub fn node_name(&self, node_id: FormNodeId, generation: u64) -> Option<String>

Return the name attribute of any live node. Used by D-ι.2 to expose subformHandle.variables as the subform’s own variables namespace.

pub fn get_occur_property( &mut self, node_id: FormNodeId, generation: u64, property: &str, ) -> Option<i32>

Read a property from a node’s XFA occur object.

pub fn set_occur_property( &mut self, node_id: FormNodeId, generation: u64, property: &str, value: &str, ) -> bool

Write a property on a node’s XFA occur object when mutation is allowed.

pub fn set_raw_value( &mut self, node_id: FormNodeId, value: String, generation: u64, ) -> bool

Write field.rawValue when the activity and target are permitted.

pub fn resolve_node(&mut self, path: &str) -> Option<FormNodeId>

Resolve a SOM path to the first field node.

pub fn resolve_nodes(&mut self, path: &str) -> Vec<FormNodeId>

Resolve a SOM path to field handles, capped at MAX_RESOLVE_RESULTS.

pub fn resolve_implicit( &mut self, current_id: FormNodeId, name: &str, ) -> Option<FormNodeId>

Resolve an implicit JavaScript identifier from the current XFA scope.

Adobe’s XFA JavaScript environment makes sibling and ancestor-scoped SOM nodes visible as bare identifiers. This method searches from the supplied current node upward, returning the first descendant with the requested name at each scope.

pub fn resolve_implicit_candidates( &mut self, current_id: FormNodeId, name: &str, ) -> Vec<FormNodeId>

Resolve all viable implicit JavaScript identifier candidates from the current XFA scope. The first candidate is identical to [resolve_implicit]; later candidates preserve same-name alternatives so the JS proxy can filter them when a chained property supplies the next SOM segment.

pub fn resolve_child( &mut self, parent_id: FormNodeId, name: &str, ) -> Option<FormNodeId>

Resolve a direct child node for chained dotted JavaScript access.

pub fn resolve_child_candidates( &mut self, parent_ids: &[FormNodeId], name: &str, ) -> Vec<FormNodeId>

Resolve chained child candidates from an ordered parent candidate set.

Direct children are preferred. If none match, this uses the same bounded descendant heuristic as the implicit resolver inside each parent, which matches the historical permissiveness of XFA SOM dotted access without inventing handles when the form structure is absent.

pub fn resolve_scoped_candidates( &mut self, scope_ids: &[FormNodeId], name: &str, ) -> Vec<FormNodeId>

Resolve a property name from each candidate’s own implicit scope.

This is the last fallback used by JS-side candidate filtering, covering forms that author a later segment as an ancestor-scoped implicit name rather than as a direct child of the previous segment.

pub fn instance_count(&mut self, parent_id: FormNodeId) -> u32

Count live sibling instances with the same name as parent_id.

pub fn instance_count_for_handle( &mut self, parent_id: FormNodeId, generation: u64, ) -> u32

Count live sibling instances for a JS handle with generation checking.

pub fn instance_index(&mut self, node_id: FormNodeId) -> u32

Return the zero-based sibling index among instances with the same name.

pub fn instance_index_for_handle( &mut self, node_id: FormNodeId, generation: u64, ) -> u32

Return the zero-based sibling index for a JS handle.

pub fn has_zero_instance_run( &mut self, parent_id: FormNodeId, generation: u64, name: &str, ) -> bool

Whether parent_id._name refers to an instance run that was explicitly set to zero during this document. This lets the JS shorthand return a read-only empty manager only for a real prior instance run, while keeping unrelated private-looking _id properties hidden.

pub fn instance_set(&mut self, parent_id: FormNodeId, n: u32) -> Result<u32, ()>

Replace the live same-name sibling run with exactly n instances, clamped to the prototype’s occur limits and the sandbox safety cap.

pub fn instance_set_for_handle( &mut self, parent_id: FormNodeId, generation: u64, n: u32, ) -> Result<u32, ()>

Generation-checked variant used by the QuickJS bridge.

pub fn instance_add(&mut self, parent_id: FormNodeId) -> Result<FormNodeId, ()>

Append one cloned instance to the end of the live same-name sibling run.

pub fn instance_add_for_handle( &mut self, parent_id: FormNodeId, generation: u64, ) -> Result<FormNodeId, ()>

Generation-checked variant used by the QuickJS bridge.

pub fn instance_remove( &mut self, parent_id: FormNodeId, index: u32, ) -> Result<(), ()>

Remove one live same-name sibling instance by zero-based index.

pub fn instance_remove_for_handle( &mut self, parent_id: FormNodeId, generation: u64, index: u32, ) -> Result<(), ()>

Generation-checked variant used by the QuickJS bridge.

pub fn list_clear(&mut self, field_id: FormNodeId) -> Result<(), ()>

Clear all runtime-populated listbox items on a field.

pub fn list_clear_for_handle( &mut self, field_id: FormNodeId, generation: u64, ) -> Result<(), ()>

Generation-checked variant used by the QuickJS bridge.

pub fn list_add( &mut self, field_id: FormNodeId, display: String, save: Option<String>, ) -> Result<(), ()>

Append one item to a field’s runtime listbox options.

pub fn list_add_for_handle( &mut self, field_id: FormNodeId, generation: u64, display: String, save: Option<String>, ) -> Result<(), ()>

Generation-checked variant used by the QuickJS bridge.

pub fn bound_item_for_handle( &mut self, field_id: FormNodeId, generation: u64, display_value: String, ) -> String

XFA 3.3 §App A boundItem — listbox display→save lookup.

Returns the save value associated with display_value for a listbox or dropdown field. Lookup order:

1. Runtime listbox items populated via D-β addItem (matched first).
2. Static <items> parsed from the template at merge time.

Adobe’s documented behaviour returns the input unchanged when no match exists (passthrough). Empty input returns empty string. Stale or non-field handles return the input unchanged.

pub fn num_pages(&mut self) -> u32

Read-only static page count visible to Phase C scripts.

pub fn metadata_binding_error(&mut self)

Record a binding-level failure for explicit no-op stubs.

pub fn metadata_resolve_failure(&mut self)

Record use of an intentionally approximate read-only stub.

pub fn data_children(&mut self, raw_id: usize) -> Vec<usize>

Phase D-γ: children of a DataDom node, returned as raw indices. Capped at MAX_RESOLVE_RESULTS. Returns empty vec on invalid input.

pub fn data_value(&mut self, raw_id: usize) -> Option<String>

Phase D-γ: text value of a DataValue node. Returns None for DataGroup nodes or out-of-bounds indices.

pub fn data_child_by_name( &mut self, parent_raw: usize, name: &str, ) -> Option<usize>

Phase D-γ: first child of parent_raw whose name matches name. Returns None if not found or parent is out-of-bounds.

pub fn data_bound_record( &mut self, form_node_id: FormNodeId, generation: u64, ) -> Option<usize>

Phase D-γ: raw DataDom index bound to a FormTree node. Returns None when the node is unbound or the handle is stale.

pub fn data_resolve_node(&mut self, path: &str) -> Option<usize>

Phase D-γ: resolve a data SOM path to the first matching node. Consumes one resolve-call budget slot. Returns None on budget exhaustion, parse failure, or no match.

pub fn data_resolve_nodes(&mut self, path: &str) -> Vec<usize>

Phase D-γ: resolve a data SOM path to all matching nodes (capped). Consumes one resolve-call budget slot.

Trait Implementations

impl Debug for HostBindings

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for HostBindings

fn default() -> Self

Returns the “default value” for a type.