OpenSystemsDevelopment / qpdf

Commit 259eec3a94dbb688f9106f543c471bb648d86baa

Authored by Jay Berkenbilt
1 parent f95e0549

Clarify comments for QPDFObjectHandle::getOwningQPDF

Inline Side-by-side
Showing 1 changed file with 14 additions and 3 deletions
include/qpdf/QPDFObjectHandle.hh
  View file @259eec3
... ... @@ -969,9 +969,20 @@ class QPDFObjectHandle
969 969 int& min_suffix,
970 970 std::set<std::string>* resource_names = nullptr);
971 971  
972   - // Return the QPDF object that owns an indirect object. Returns
973   - // null for a direct object if allow_nullptr is set to true or
974   - // throws a runtime error otherwise.
  972 + // If this is an indirect object, return a pointer to the QPDF
  973 + // object that owns an indirect object. Direct objects are not
  974 + // owned by a QPDF. Usage notes:
  975 + //
  976 + // * When allow_nullptr is true, this method will return a null
  977 + // pointer if the object is not owned by a QPDF. Otherwise, an
  978 + // exception is thrown.
  979 + //
  980 + // * You should not retain the value returned by this method for
  981 + // longer than the lifetime of the owning QPDF object. If you
  982 + // retain a QPDFObjectHandle longer than the owning QPDF, when
  983 + // the QPDF object is destroyed, the QPDFObjectHandle will turn
  984 + // into a direct "null" object, and getOwningQPDF() called on it
  985 + // at that time will return a null pointer.
975 986 QPDF_DLL
976 987 QPDF* getOwningQPDF(
977 988 bool allow_nullptr = true, std::string const& error_msg = "") const;
... ...