octoleo
/
qpdf
mirror of https://github.com/qpdf/qpdf.git
2
1
Fork 0
Code Issues Releases Wiki Activity

Clarify documentation on copyForeignObject (fixes #69) 

Be explicit about the need to keep the source QPDF object around.
This commit is contained in:
Jay Berkenbilt 2017-07-29 09:25:25 -04:00
parent ba2bae4acc
commit 4647acbe3c
2 changed files with 34 additions and 19 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

21
include/qpdf/QPDF.hh
View File

@ -207,14 +207,19 @@ class QPDF
replaceReserved(QPDFObjectHandle reserved,
QPDFObjectHandle replacement);
// Copy an object from another QPDF to this one. The return value
// is an indirect reference to the copied object in this file.
// This method is intended to be used to copy non-page objects and
// will not copy page objects. To copy page objects, pass the
// foreign page object directly to addPage (or addPageAt). If you
// copy objects that contain references to pages, you should copy
// the pages first using addPage(At). Otherwise references to the
// pages that have not been copied will be replaced with nulls.
// Copy an object from another QPDF to this one. Please note that
// the QPDF object containing the object being copied must stick
// around because it is still used to retrieve any stream data
// referenced by the copied objects.
//
// The return value is an indirect reference to the copied object
// in this file. This method is intended to be used to copy
// non-page objects and will not copy page objects. To copy page
// objects, pass the foreign page object directly to addPage (or
// addPageAt). If you copy objects that contain references to
// pages, you should copy the pages first using addPage(At).
// Otherwise references to the pages that have not been copied
// will be replaced with nulls.
// When copying objects with this method, object structure will be
// preserved, so all indirectly referenced indirect objects will

32
manual/qpdf-manual.xml
View File

@ -1983,24 +1983,26 @@ outfile.pdf</option>
Version 3.0 of qpdf introduced the ability to copy objects into a
<classname>QPDF</classname> object from a different
<classname>QPDF</classname> object, which we refer to as
<firstterm>foreign objects</firstterm>. This allows arbitrary
merging of PDF files. The <command>qpdf</command> command-line
tool provides limited support for basic page selection, including
merging in pages from other files, but the library's API makes it
possible to implement arbitrarily complex merging operations. The
main method for copying foreign objects is
<function>QPDF::copyForeignObject</function>. This takes an
<firstterm>foreign objects</firstterm>. This allows arbitrary
merging of PDF files. The &ldqo;from&rdqo;
<classname>QPDF</classname> object must remain valid after the
copy as discussed in the note below. The <command>qpdf</command>
command-line tool provides limited support for basic page
selection, including merging in pages from other files, but the
library's API makes it possible to implement arbitrarily complex
merging operations. The main method for copying foreign objects is
<function>QPDF::copyForeignObject</function>. This takes an
indirect object from another <classname>QPDF</classname> and
copies it recursively into this object while preserving all object
structure, including circular references. This means you can add
a direct object that you create from scratch to a
structure, including circular references. This means you can add a
direct object that you create from scratch to a
<classname>QPDF</classname> object with
<function>QPDF::makeIndirectObject</function>, and you can add an
indirect object from another file with
<function>QPDF::copyForeignObject</function>. The fact that
<function>QPDF::copyForeignObject</function>. The fact that
<function>QPDF::makeIndirectObject</function> does not
automatically detect a foreign object and copy it is an explicit
design decision. Copying a foreign object seems like a
design decision. Copying a foreign object seems like a
sufficiently significant thing to do that it should be done
explicitly.
</para>
@ -2012,6 +2014,14 @@ outfile.pdf</option>
automatically distinguishes between indirect objects in the
current file, foreign objects, and direct objects.
</para>
<para>
Please note: when you copy objects from one
<classname>QPDF</classname> to another, the source
<classname>QPDF</classname> object must remain valid until you
have finished with the destination object. This is because the
original object is still used to retrieve any referenced stream
data from the copied object.
</para>
</sect1>
<sect1 id="ref.rewriting">
<title>Writing PDF Files</title>