diff options
author | Jay Berkenbilt <ejb@ql.org> | 2022-09-06 16:08:46 +0200 |
---|---|---|
committer | Jay Berkenbilt <ejb@ql.org> | 2022-09-06 16:09:28 +0200 |
commit | 259eec3a94dbb688f9106f543c471bb648d86baa (patch) | |
tree | 88624e6f6db3abf37bc57a8a5d95048f900319a9 | |
parent | f95e0549cc6d402ab29f64306560e5677e528dad (diff) | |
download | qpdf-259eec3a94dbb688f9106f543c471bb648d86baa.tar.zst |
Clarify comments for QPDFObjectHandle::getOwningQPDF
-rw-r--r-- | include/qpdf/QPDFObjectHandle.hh | 17 |
1 files changed, 14 insertions, 3 deletions
diff --git a/include/qpdf/QPDFObjectHandle.hh b/include/qpdf/QPDFObjectHandle.hh index de085bb6..f26a7648 100644 --- a/include/qpdf/QPDFObjectHandle.hh +++ b/include/qpdf/QPDFObjectHandle.hh @@ -969,9 +969,20 @@ class QPDFObjectHandle int& min_suffix, std::set<std::string>* resource_names = nullptr); - // Return the QPDF object that owns an indirect object. Returns - // null for a direct object if allow_nullptr is set to true or - // throws a runtime error otherwise. + // If this is an indirect object, return a pointer to the QPDF + // object that owns an indirect object. Direct objects are not + // owned by a QPDF. Usage notes: + // + // * When allow_nullptr is true, this method will return a null + // pointer if the object is not owned by a QPDF. Otherwise, an + // exception is thrown. + // + // * You should not retain the value returned by this method for + // longer than the lifetime of the owning QPDF object. If you + // retain a QPDFObjectHandle longer than the owning QPDF, when + // the QPDF object is destroyed, the QPDFObjectHandle will turn + // into a direct "null" object, and getOwningQPDF() called on it + // at that time will return a null pointer. QPDF_DLL QPDF* getOwningQPDF( bool allow_nullptr = true, std::string const& error_msg = "") const; |