octoleo/qpdf
2
1
Fork 0
mirror of https://github.com/qpdf/qpdf.git synced 2024-06-17 01:12:21 +00:00
Code Issues Releases Wiki Activity

Clarify documentation on copyForeignObject (fixes #69)

Browse Source 
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, replaceReserved(QPDFObjectHandle reserved,
QPDFObjectHandle replacement); QPDFObjectHandle replacement);
// Copy an object from another QPDF to this one. The return value // Copy an object from another QPDF to this one. Please note that
// is an indirect reference to the copied object in this file. // the QPDF object containing the object being copied must stick
// This method is intended to be used to copy non-page objects and // around because it is still used to retrieve any stream data
// will not copy page objects. To copy page objects, pass the // referenced by the copied objects.
// foreign page object directly to addPage (or addPageAt). If you //
// copy objects that contain references to pages, you should copy // The return value is an indirect reference to the copied object
// the pages first using addPage(At). Otherwise references to the // in this file. This method is intended to be used to copy
// pages that have not been copied will be replaced with nulls. // 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 // When copying objects with this method, object structure will be
// preserved, so all indirectly referenced indirect objects will // 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 Version 3.0 of qpdf introduced the ability to copy objects into a
<classname>QPDF</classname> object from a different <classname>QPDF</classname> object from a different
<classname>QPDF</classname> object, which we refer to as <classname>QPDF</classname> object, which we refer to as
<firstterm>foreign objects</firstterm>. This allows arbitrary <firstterm>foreign objects</firstterm>. This allows arbitrary
merging of PDF files. The <command>qpdf</command> command-line merging of PDF files. The &ldqo;from&rdqo;
tool provides limited support for basic page selection, including <classname>QPDF</classname> object must remain valid after the
merging in pages from other files, but the library's API makes it copy as discussed in the note below. The <command>qpdf</command>
possible to implement arbitrarily complex merging operations. The command-line tool provides limited support for basic page
main method for copying foreign objects is selection, including merging in pages from other files, but the
<function>QPDF::copyForeignObject</function>. This takes an 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 indirect object from another <classname>QPDF</classname> and
copies it recursively into this object while preserving all object copies it recursively into this object while preserving all object
structure, including circular references. This means you can add structure, including circular references. This means you can add a
a direct object that you create from scratch to a direct object that you create from scratch to a
<classname>QPDF</classname> object with <classname>QPDF</classname> object with
<function>QPDF::makeIndirectObject</function>, and you can add an <function>QPDF::makeIndirectObject</function>, and you can add an
indirect object from another file with 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 <function>QPDF::makeIndirectObject</function> does not
automatically detect a foreign object and copy it is an explicit 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 sufficiently significant thing to do that it should be done
explicitly. explicitly.
</para> </para>
@ -2012,6 +2014,14 @@ outfile.pdf</option>
automatically distinguishes between indirect objects in the automatically distinguishes between indirect objects in the
current file, foreign objects, and direct objects. current file, foreign objects, and direct objects.
</para> </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>
<sect1 id="ref.rewriting"> <sect1 id="ref.rewriting">
<title>Writing PDF Files</title> <title>Writing PDF Files</title>