diff options
| -rw-r--r-- | include/qpdf/QPDF.hh | 21 | ||||
| -rw-r--r-- | manual/qpdf-manual.xml | 32 |
2 files changed, 34 insertions, 19 deletions
diff --git a/include/qpdf/QPDF.hh b/include/qpdf/QPDF.hh index ad8503dc..58f6af6e 100644 --- a/include/qpdf/QPDF.hh +++ b/include/qpdf/QPDF.hh @@ -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 diff --git a/manual/qpdf-manual.xml b/manual/qpdf-manual.xml index 18abc013..4fde831a 100644 --- a/manual/qpdf-manual.xml +++ b/manual/qpdf-manual.xml @@ -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> |