Add concept of reserved objects

QPDFObjectHandle::{new,is,assert}Reserved, QPDF::replaceReserved
provide a mechanism to add objects to a PDF file when there are
circular references.  This is a prerequisite to copying objects from
one PDF to another.

2 files changed, 34 insertions, 1 deletions

diff --git a/include/qpdf/QPDF.hh b/include/qpdf/QPDF.hh
index fbac2ab2..b5c07abb 100644
--- a/include/qpdf/QPDF.hh
+++ b/include/qpdf/QPDF.hh
@@ -161,7 +161,8 @@ class QPDF
     // be associated with the PDF file.  Note that replacing an object
     // with QPDFObjectHandle::newNull() effectively removes the object
     // from the file since a non-existent object is treated as a null
-    // object.
+    // object.  To replace a reserved object, call replaceReserved
+    // instead.
     QPDF_DLL
     void replaceObject(int objid, int generation, QPDFObjectHandle);
 
@@ -180,6 +181,15 @@ class QPDF
     void swapObjects(int objid1, int generation1,
 		     int objid2, int generation2);
 
+    // Replace a reserved object.  This is a wrapper around
+    // replaceObject but it guarantees that the underlying object is a
+    // reserved object.  After this call, reserved will be a reference
+    // to replacement.
+    QPDF_DLL
+    void
+    replaceReserved(QPDFObjectHandle reserved,
+                    QPDFObjectHandle replacement);
+
     // Encryption support
 
     enum encryption_method_e { e_none, e_unknown, e_rc4, e_aes };
diff --git a/include/qpdf/QPDFObjectHandle.hh b/include/qpdf/QPDFObjectHandle.hh
index daa71faa..b21a3b0c 100644
--- a/include/qpdf/QPDFObjectHandle.hh
+++ b/include/qpdf/QPDFObjectHandle.hh
@@ -81,6 +81,8 @@ class QPDFObjectHandle
     bool isDictionary();
     QPDF_DLL
     bool isStream();
+    QPDF_DLL
+    bool isReserved();
 
     // This returns true in addition to the query for the specific
     // type for indirect objects.
@@ -148,6 +150,24 @@ class QPDFObjectHandle
     QPDF_DLL
     static QPDFObjectHandle newStream(QPDF* qpdf, std::string const& data);
 
+    // A reserved object is a special sentinel used for qpdf to
+    // reserve a spot for an object that is going to be added to the
+    // QPDF object.  Normally you don't have to use this type since
+    // you can just call QPDF::makeIndirectObject.  However, in some
+    // cases, if you have to create objects with circular references,
+    // you may need to create a reserved object so that you can have a
+    // reference to it and then replace the object later.  Reserved
+    // objects have the special property that they can't be resolved
+    // to direct objects.  This makes it possible to replace a
+    // reserved object with a new object while preserving existing
+    // references to them.  When you are ready to replace a reserved
+    // object with its replacement, use QPDF::replaceReserved for this
+    // purpose rather than the more general QPDF::replaceObject.  It
+    // is an error to try to write a QPDF with QPDFWriter if it has
+    // any reserved objects in it.
+    QPDF_DLL
+    static QPDFObjectHandle newReserved(QPDF* qpdf);
+
     // Accessor methods.  If an accessor method that is valid for only
     // a particular object type is called on an object of the wrong
     // type, an exception is thrown.
@@ -430,6 +450,8 @@ class QPDFObjectHandle
     void assertDictionary();
     QPDF_DLL
     void assertStream();
+    QPDF_DLL
+    void assertReserved();
 
     QPDF_DLL
     void assertScalar();
@@ -459,6 +481,7 @@ class QPDFObjectHandle
     int objid;			// 0 for direct object
     int generation;
     PointerHolder<QPDFObject> obj;
+    bool reserved;
 };
 
 #endif // __QPDFOBJECTHANDLE_HH__