Use a specific error code for type warnings and clarify docs

2 files changed, 55 insertions, 4 deletions

diff --git a/include/qpdf/Constants.h b/include/qpdf/Constants.h
index 45b87d4d..4e4c9e01 100644
--- a/include/qpdf/Constants.h
+++ b/include/qpdf/Constants.h
@@ -38,6 +38,7 @@ enum qpdf_error_code_e
     qpdf_e_password,		/* incorrect password for encrypted file */
     qpdf_e_damaged_pdf,		/* syntax errors or other damage in PDF */
     qpdf_e_pages,               /* erroneous or unsupported pages structure */
+    qpdf_e_object,              /* type/bounds errors accessing objects */
 };
 
 /* Write Parameters. See QPDFWriter.hh for details. */
diff --git a/include/qpdf/QPDFObjectHandle.hh b/include/qpdf/QPDFObjectHandle.hh
index 65531fa6..31afd01b 100644
--- a/include/qpdf/QPDFObjectHandle.hh
+++ b/include/qpdf/QPDFObjectHandle.hh
@@ -609,15 +609,65 @@ class QPDFObjectHandle
     QPDF_DLL
     bool hasObjectDescription();
 
-    // 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.
+    // Accessor methods
+    //
+    // (Note: this comment is referenced in qpdf-c.h and the manual.)
+    //
+    // In PDF files, objects have specific types, but there is nothing
+    // that prevents PDF files from containing objects of types that
+    // aren't expected by the specification. Many of the accessors
+    // here expect objects of a particular type. Prior to qpdf 8,
+    // calling an accessor on a method of the wrong type, such as
+    // trying to get a dictionary key from an array, trying to get the
+    // string value of a number, etc., would throw an exception, but
+    // since qpdf 8, qpdf issues a warning and recovers using the
+    // following behavior:
+    //
+    // * Requesting a value of the wrong type (int value from string,
+    //   array item from a scalar or dictionary, etc.) will return a
+    //   zero-like value for that type: false for boolean, 0 for
+    //   number, the empty string for string, or the null object for
+    //   an object handle.
+    //
+    // * Accessing an array item that is out of bounds will return a
+    //   null object.
+    //
+    // * Attempts to mutate an object of the wrong type (e.g.,
+    //   attempting to add a dictionary key to a scalar or array) will
+    //   be ignored.
+    //
+    // When any of these fallback behaviors are used, qpdf issues a
+    // warning. Starting in qpdf 10.5, these warnings have the error
+    // code qpdf_e_object. Prior to 10.5, they had the error code
+    // qpdf_e_damaged_pdf. If the QPDFObjectHandle is associated with
+    // a QPDF object (as is the case for all objects whose origin was
+    // a PDF file), the warning is issued using the normal warning
+    // mechanism (as described in QPDF.hh), making it possible to
+    // suppress or otherwise detect them. If the QPDFObjectHandle is
+    // not associated with a QPDF object (meaning it was created
+    // programmatically), an exception will be thrown.
+    //
+    // The way to avoid getting any type warnings or exceptions, even
+    // when working with malformed PDF files, is to always check the
+    // type of a QPDFObjectHandle before accessing it (for example,
+    // make sure that isString() returns true before calling
+    // getStringValue()) and to always be sure that any array indices
+    // are in bounds.
+    //
+    // For additional discussion and rationale for this behavior, see
+    // the section in the QPDF manual entitled "Object Accessor
+    // Methods".
 
     // Methods for bool objects
     QPDF_DLL
     bool getBoolValue();
 
-    // Methods for integer objects
+    // Methods for integer objects. Note: if an integer value is too
+    // big (too far away from zero in either direction) to fit in the
+    // requested return type, the maximum or minimum value for that
+    // return type may be returned. For example, on a system with
+    // 32-bit int, a numeric object with a value of 2^40 (or anything
+    // too big for 32 bits) will be returned as INT_MAX.
     QPDF_DLL
     long long getIntValue();
     QPDF_DLL