From 05a49cecf1b1caa12575fa34fa478560ba25e31b Mon Sep 17 00:00:00 2001 From: m-holger Date: Sat, 20 May 2023 19:56:01 +0100 Subject: Add new method QPDF::newReserved --- include/qpdf/QPDF.hh | 18 ++++++++++++++++++ include/qpdf/QPDFObjectHandle.hh | 3 ++- 2 files changed, 20 insertions(+), 1 deletion(-) (limited to 'include') diff --git a/include/qpdf/QPDF.hh b/include/qpdf/QPDF.hh index f1dcb7f7..677c009b 100644 --- a/include/qpdf/QPDF.hh +++ b/include/qpdf/QPDF.hh @@ -413,6 +413,24 @@ class QPDF QPDF_DLL QPDFObjectHandle newStream(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 + QPDFObjectHandle newReserved(); + // Install this object handle as an indirect object and return an // indirect reference to it. QPDF_DLL diff --git a/include/qpdf/QPDFObjectHandle.hh b/include/qpdf/QPDFObjectHandle.hh index eaab6dc6..aeca4bf6 100644 --- a/include/qpdf/QPDFObjectHandle.hh +++ b/include/qpdf/QPDFObjectHandle.hh @@ -668,7 +668,8 @@ class QPDFObjectHandle // 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. + // any reserved objects in it. From QPDF 11.4, you can + // call QPDF::newReserved() instead. QPDF_DLL static QPDFObjectHandle newReserved(QPDF* qpdf); -- cgit v1.2.3-54-g00ecf