PdfObjectCopier Class

Definition

One copy session: copies object graphs of a source document into a target document, with every indirect reference remapped to the target's copy of the object it names.

public sealed class PdfObjectCopier

Remarks

ISO 32000-2 §7.3.10. An indirect object of the source becomes a new indirect object of the target, numbered as AddObject(CosObject) numbers it, the first time the session reaches it; every later reference to it, in the same call or a later one, is the same target reference. So objects that several copied graphs share (a font, an image, a form XObject two pages paint) are copied once per session. Cycles are followed once, and the graph is walked without recursion, so neither a cyclic nor a deeply nested graph exhausts the stack. Direct objects are copied wherever they appear; immutable values are shared.

Pages. The page tree is never copied: the Parent entry of a page or page tree node is left out, and a reference to a page tree node (§7.7.3.2) copies as null. A page is copied by CopyPage(PdfPage) (or as the object Copy(CosObject) is given), with the attributes it inherits (Resources, MediaBox, CropBox, Rotate, §7.7.3.4) made its own, ready for the target's page tree. An Annots the page reads from a page tree node above it is made its own too: it is not inheritable (Table 31), but it is read as viewers read it (§7.7.3.3), so the copy shows the same annotations; the source records AnnotsInherited for it before the target changes. A reference to any other page that a copied graph reaches, such as an annotation's destination or a structure element's page, is not followed: it names the page's copy once the session copies that page, before or after, and is null until then (an array keeps a null element in its place; a dictionary has no entry).

Streams are copied encoded: their data as stored, the filters their dictionaries name and a direct Length written on save (§7.3.8). Data is read from the source when the stream is copied, so the source may be disposed once copying is done. The objects of an encrypted source copy decrypted (§7.6.2): strings and stream data as the document reads them, a stream's Crypt filter left out of its Filter and DecodeParms (§7.4.10), and the source's encryption dictionary copied as null. The target encrypts on save as its own options say. Everything else is copied unchanged, including what the library only preserves (JavaScript, 3D and RichMedia annotations and their assets, XFA).

Versions. The features of the version table that the copied objects use (associated files, a file specification's UF or Desc, embedded file streams, FlateDecode, structure elements and namespaces, outline item styles, FitB destinations) are recorded in the target as its own writing APIs record theirs, so its next save raises its version to the highest of them, or refuses in strict mode before writing (ISO 32000-2 §7.5.2). A copy between documents of the same version raises nothing the source did not already need.

A session mutates the target: no read of the target may run concurrently with a copy. The source is only read, and may be read concurrently by others.

Constructors (1)

Properties (2)

Methods (2)