From 72c10d8617c799432e28dabf1679b1a6f5245c02 Mon Sep 17 00:00:00 2001
From: Jay Berkenbilt <ejb@ql.org>
Date: Fri, 10 Dec 2021 11:09:42 -0500
Subject: C API: overhaul error handling

* Handle error conditions that occur when using the object handle
  interfaces. In the past, some exceptions were not correctly
  converted to errors or warnings.
* Add more detailed information to qpdf-c.h
* Make it possible to work more explicitly with uninitialized objects
---
 manual/qpdf-manual.xml | 19 ++++++++++++++++---
 1 file changed, 16 insertions(+), 3 deletions(-)

(limited to 'manual/qpdf-manual.xml')

diff --git a/manual/qpdf-manual.xml b/manual/qpdf-manual.xml
index fd3bd6fb..f7d224e5 100644
--- a/manual/qpdf-manual.xml
+++ b/manual/qpdf-manual.xml
@@ -5229,6 +5229,19 @@ print "\n";
           discussion.
          </para>
         </listitem>
+        <listitem>
+         <para>
+          Overhaul error handling for the object handle functions in
+          the C API. See comments in the &ldquo;Object handling&rdquo;
+          section of <filename>include/qpdf/qpdf-c.h</filename> for
+          details. In particular, exceptions thrown by the underlying
+          C++ code when calling object accessors are caught and
+          converted into errors. The errors can be trapped by
+          registering an error handler with
+          <function>qpdf_register_oh_error_handler</function> or will
+          be written to stderr if no handler is registered.
+         </para>
+        </listitem>
         <listitem>
          <para>
           Add <function>qpdf_get_last_string_length</function> to the
@@ -5239,9 +5252,9 @@ print "\n";
         </listitem>
         <listitem>
          <para>
-          Add <function>qpdf_oh_is_initialized</function> to the
-          C API. While you can't directly create uninitialized objects
-          from the C API, you still have to be able to detect them.
+          Add <function>qpdf_oh_is_initialized</function> and
+          <function>qpdf_oh_new_uninitialized</function> to the C API
+          to make it possible to work with uninitialized objects.
          </para>
         </listitem>
         <listitem>
-- 
cgit v1.2.3-54-g00ecf