Incremental save session

Component: TPdf · Unit: PDFium

Appends only changed or new indirect objects while preserving every previous output byte

Syntax

procedure BeginIncrementalSave(AllowSignedDocument: Boolean = False);

function CommitIncrementalSave(Stream: TStream; out Info: TPdfIncrementalCommitInfo): Boolean;

function CommitIncrementalSave(const FileName: string; out Info: TPdfIncrementalCommitInfo): Boolean;

procedure EndIncrementalSave;

property IncrementalSaveActive: Boolean;

AllowSignedDocument	Explicitly permits a session on a signed document; the default rejects it
Stream	TStream that receives the complete accumulated PDF after this commit
FileName	Output path replaced only after a sibling temporary file succeeds
Info	Per-commit statistics returned after the destination write succeeds

Commit Information

ChangedObjectCount	Number of changed or new indirect objects appended by this commit
AppendedByteCount	Bytes appended after the exact previous-output prefix
OutputByteCount	Total bytes in the complete output returned by this commit
RevisionCount	Number of non-empty revisions committed in the current session

Description

BeginIncrementalSave captures a stable PDFium semantic snapshot as both the comparison baseline and the first complete output

Each commit captures the current state, resolves active classic, hybrid, xref-stream, and object-stream objects, then compares object generation and exact body bytes

Only changed or new indirect objects are written after the previous output, followed by the smallest required xref and trailer revision

A classic-xref source continues with classic xref tables, while an xref-stream source continues with self-indexed xref streams

If nothing changed, the previous output is returned byte for byte, no revision is appended, and RevisionCount does not advance

The file overload writes a sibling temporary file, replaces the destination atomically, and restores session state if writing or replacement fails

Constraints

Encrypted documents are rejected because appended object bodies would require object-key-aware re-encryption
Signed documents are rejected unless AllowSignedDocument is True; explicit permission does not validate DocMDP or FieldMDP policy
Freeing an existing indirect object is not yet supported and raises EPdfError
The session snapshot path is independent of the Compressed property so object comparison remains stable
The current memory-backed object materialiser rejects states of 2 GiB or larger
Unloading the document ends the active session automatically

Example

var
  Info: TPdfIncrementalCommitInfo;
begin
  Pdf.BeginIncrementalSave;
  try
    Pdf.PageNumber := 1;
    Pdf.PageRotation := ro90;
    Pdf.CommitIncrementalSave('revision-1.pdf', Info);
    Pdf.PageRotation := ro180;
    Pdf.CommitIncrementalSave('revision-2.pdf', Info);
  finally
    Pdf.EndIncrementalSave;
  end;
end;