THotPDF.SaveIncrementalUpdate Method

Home المحتويات Overview

THotPDF.SaveIncrementalUpdate

THotPDF

Previous Methods THotPDF

Writes a sparse incremental revision while preserving every original source byte

Delphi syntax:

procedure SaveIncrementalUpdate(const TargetFile: TFileName);

C++ syntax:

void __fastcall SaveIncrementalUpdate(System::Sysutils::TFileName TargetFile);

procedure SaveIncrementalUpdate(const TargetFile: TFileName); overload;

Bounded overload

procedure SaveIncrementalUpdate(const TargetFile: TFileName;
  MaxOutputBytes: Int64; Checkpoint: TNotifyEvent); overload;

A positive MaxOutputBytes requires BeginIncrementalUpdate and bounds the full original prefix plus appended delta; negative limits are invalid, while zero retains the legacy unbounded behavior

The positive-limit overload spools its delta to temporary storage and raises EHPDFIncrementalOutputBudget before publication when serialization exceeds the cap, preserving an existing target in that failure path

Checkpoint receives the document during object traversal and publication copies, and the internal spool during writes; do not depend on a particular Sender type

This low-level save is not an atomic replacement API for a distinct target; cancellation or an I/O failure during publication can leave a partial file, so use a private candidate or the validated incremental signing job for atomic external publication

Description

SaveIncrementalUpdate completes the workflow started by BeginIncrementalUpdate. Only changed, new, and deleted objects are visited and emitted, together with sparse xref subsections and a trailer whose /Prev points to the previous revision

For a different target, the original prefix is copied sequentially from the file-backed source before the completed delta is appended. For the same target, HotPDF validates the source identity, length, and write time, releases lazy source handles, appends directly, flushes the file, and truncates back to the original length if the append fails. Both paths preserve existing byte ranges and earlier signatures

When no object is dirty or deleted, the target is byte-identical to the source and no xref section, trailer, newline, or EOF marker is appended. When a revision is required, the first trailer ID remains stable and only the second modification ID is rotated

For an encrypted source, the appended trailer preserves the original /Encrypt representation: an indirect dictionary retains its object and generation reference, while a direct trailer dictionary retains its unchanged security-handler bytes. Rewritten strings and streams remain protected by the source security handler, and the resulting document continues to accept the original Standard user and owner passwords or public-key recipient credentials

A successful same-target append consumes the held source because the original revision has changed in place. Call BeginIncrementalUpdate again before creating another revision. GetIncrementalUpdateSourceInfo exposes retained bytes, probe bytes, copy and append counts, tracked changes, visited objects, xref entries, locking, and consumption state

Destructive edits automatically rebuild the complete active free-object chain. Existing free generations are preserved, newly freed generations advance up to 65535, rewritten objects keep their original generations, and every emitted entry is ordered by object number. GetLastIncrementalXRefRebuildInfo returns the source, transition, saturation, and rebuilt-chain counts after the save

Call this method before preparing or inserting a new signature when adding a later signature revision. After the appended file exists, use the normal signing helpers to reserve and fill the new signature value

For certified or usage-rights documents, SaveIncrementalUpdateAuthenticated writes a same-directory candidate, authenticates each policy-bearing signature, enforces every later revision, and atomically replaces the target only after all policies accept the update