Allow regular C++ functions to interoperate with the C API

1 files changed, 26 insertions, 7 deletions

diff --git a/include/qpdf/qpdf-c.h b/include/qpdf/qpdf-c.h
index d4305602..f989ba15 100644
--- a/include/qpdf/qpdf-c.h
+++ b/include/qpdf/qpdf-c.h
@@ -21,21 +21,23 @@
 #define QPDF_C_H
 
 /*
- * This file defines a basic "C" API for qpdf.  It provides access to a subset of the QPDF library's
+ * This file defines a basic "C" API for qpdf. It provides access to a subset of the QPDF library's
  * capabilities to make them accessible to callers who can't handle calling C++ functions or working
- * with C++ classes.  This may be especially useful to Windows users who are accessing the qpdf DLL
+ * with C++ classes. This may be especially useful to Windows users who are accessing the qpdf DLL
  * directly or to other people programming in non-C/C++ languages that can call C code but not C++
- * code.
+ * code. Starting with qpdf 11.7, it is possible to write your own `extern "C"` functions that
+ * interoperate with the C API.
  *
  * There are several things to keep in mind when using the C API.
  *
  *     Error handling is tricky because the underlying C++ API uses exception handling. See "ERROR
  *     HANDLING" below for a detailed explanation.
  *
- *     The C API is not as rich as the C++ API.  For any operations that involve actually
- *     manipulating PDF objects, you must use the C++ API.  The C API is primarily useful for doing
- *     basic transformations on PDF files similar to what you might do with the qpdf command-line
- *     tool.
+ *     The C API is not as rich as the C++ API. For many operations, you must use the C++ API. The C
+ *     API is primarily useful for doing basic transformations on PDF files similar to what you
+ *     might do with the qpdf command-line tool. You can write your own `extern "C"` functions in
+ *     C++ that interoperate with the C API by using qpdf_c_get_qpdf and qpdf_c_wrap which were
+ *     introduced in qpdf 11.7.0.
  *
  *     These functions store their state in a qpdf_data object. Individual instances of qpdf_data
  *     are not thread-safe: although you may access different qpdf_data objects from different
@@ -990,6 +992,23 @@ extern "C" {
     QPDF_ERROR_CODE qpdf_remove_page(qpdf_data qpdf, qpdf_oh page);
 #ifdef __cplusplus
 }
+
+// These C++ functions make it easier to write C++ code that interoperates with the C API.
+// See examples/extend-c-api.
+
+# include <functional>
+# include <memory>
+
+# include <qpdf/QPDF.hh>
+
+// Retrieve the real QPDF object attached to this qpdf_data.
+QPDF_DLL
+std::shared_ptr<QPDF> qpdf_c_get_qpdf(qpdf_data qpdf);
+
+// Wrap a C++ function that may throw an exception to translate the exception for retrieval using
+// the normal QPDF C API methods.
+QPDF_DLL
+QPDF_ERROR_CODE qpdf_c_wrap(qpdf_data qpdf, std::function<void()> fn);
 #endif
 
 #endif /* QPDF_C_H */