Writes the document to stream as a complete file.
public void Save(Stream stream, PdfSaveOptions options)
Where to write, from its current position. It is not disposed.
How to lay the file out.
ISO 32000-2 §7.5: a header, every object, the cross-reference information and the trailer. Objects keep their numbers and
generations unless ObjectNumbering renumbers them, or the numbering is too large or too sparse to
write compactly. A number past 8,388,607 (ISO 32000-1 Annex C, Table C.1), such as a damaged file's scan may find, renumbers
the file with an ObjectNumberOutOfRange diagnostic (Information; in strict mode, a refusal); the cross-reference
information never costs more than the objects written (§7.5.4, §7.5.8.2). RemoveUnreachableObjects
leaves out objects the trailer does not reach. An object that has not changed since it was read, was read without any repair and holds no reference that was renumbered is written with
exactly the bytes it was read from; other objects are serialized, stream data as stored. The revisions of an incrementally
updated file collapse into one, and a linearized file is written unlinearized (Annex F) unless
Linearize lays the file out linearized again.
Unfiltered streams that are new or changed are written compressed with the engine's FlateDecode encoder when that makes
them smaller (§7.4.4); StreamCompression and CompressionLevel change
which and how hard. The document's own streams are not changed.
The header keeps the document's version, raised to the highest minimum version of the features the file uses: 1.5
for cross-reference and object streams, 1.2 for FlateDecode compression, the encryption's version, the BaseVersion
of each developer extension (§7.12.4). An incremental update writes no header: it raises the catalog's Version entry
instead (§7.5.6, §7.7.2 Table 29). A raise above Version is recorded as a VersionRaised diagnostic
(Information); in strict mode it is refused, and the save throws naming the features, before anything is written. A feature of an
ISO/TS extension (AES-GCM encryption, ISO/TS 32003; an integrity MAC, ISO/TS 32004) adds its developer extension to the
catalog's Extensions (§7.12),
keeping every other declaration. The trailer's first
file identifier is kept; the second is derived from the written bytes, so saving the same document the same way always writes
the same bytes (§14.4).
An encrypted document is saved encrypted with the key it was opened with, unless Encryption gives
new password encryption, PublicKeyEncryption new encryption for certificate recipients (§7.6.5), or
RemoveEncryption drops it (§7.6). Either way every object of an encrypted
document, or of an encrypted file, is serialized and its strings and streams encrypted again under its written number; nothing
is copied from the source, whose bytes are ciphertext. New encryption raises the header to the version its algorithm needs, and
encrypted output is not deterministic (random keys, salts and IVs). Saving with RC4 or AES-128, new or kept, records an
EncryptionDeprecated warning first, so strict mode refuses it. A file with an integrity MAC (ISO/TS 32004), new
(IntegrityProtection) or the document's own, gets a standalone PDF MAC token in its trailer's
AuthCode, computed over every byte of the file but the token; an incremental update computes it over the whole updated file.
A save checks everything that can refuse it before it changes the document: a save that throws has written nothing and left the document as it was. Only a save that goes ahead dates the modification (UpdateModificationDate, §14.3.4), subsets the fonts filled fields grew, and declares extensions and a raised version in the catalog.
With IncrementalUpdate, the file is instead the document's file followed by an incremental update holding only what changed (§7.5.6), and once its last byte is written the document reads from it: a mutation, which no read may run concurrently with.