From 3dbab589e32d3ed5bd98e0634255ba7dfab4c892 Mon Sep 17 00:00:00 2001
From: Jay Berkenbilt <ejb@ql.org>
Date: Fri, 9 Sep 2022 08:03:21 -0400
Subject: Add C API functions for using custom loggers

Expose functions to the C API to create new loggers and to setLogger
and getLogger for QPDF and QPDFJob.
---
 include/qpdf/qpdf-c.h       | 15 +++++++++++++++
 include/qpdf/qpdfjob-c.h    | 13 +++++++++++++
 include/qpdf/qpdflogger-c.h | 24 ++++++++++++++++++++----
 3 files changed, 48 insertions(+), 4 deletions(-)

(limited to 'include')

diff --git a/include/qpdf/qpdf-c.h b/include/qpdf/qpdf-c.h
index 434c4ede..8d1b0e2f 100644
--- a/include/qpdf/qpdf-c.h
+++ b/include/qpdf/qpdf-c.h
@@ -140,6 +140,7 @@
 #include <qpdf/Constants.h>
 #include <qpdf/DLL.h>
 #include <qpdf/Types.h>
+#include <qpdf/qpdflogger-c.h>
 #include <string.h>
 
 #ifdef __cplusplus
@@ -249,6 +250,20 @@ extern "C" {
     QPDF_DLL
     void qpdf_set_suppress_warnings(qpdf_data qpdf, QPDF_BOOL value);
 
+    /* LOG FUNCTIONS */
+
+    /* Set or get the current logger. You need to call
+     * qpdflogger_cleanup on the logger handles when you are done with
+     * the handles. The underlying logger is cleaned up automatically
+     * and persists if needed after the logger handle is destroyed.
+     * See comments in qpdflogger-c.h for details.
+     */
+
+    QPDF_DLL
+    void qpdf_set_logger(qpdf_data qpdf, qpdflogger_handle logger);
+    QPDF_DLL
+    qpdflogger_handle qpdf_get_logger(qpdf_data qpdf);
+
     /* CHECK FUNCTIONS */
 
     /* Attempt to read the entire PDF file to see if there are any
diff --git a/include/qpdf/qpdfjob-c.h b/include/qpdf/qpdfjob-c.h
index 961fece4..a1540d84 100644
--- a/include/qpdf/qpdfjob-c.h
+++ b/include/qpdf/qpdfjob-c.h
@@ -32,6 +32,7 @@
  */
 
 #include <qpdf/DLL.h>
+#include <qpdf/qpdflogger-c.h>
 #include <string.h>
 #ifndef QPDF_NO_WCHAR_T
 # include <wchar.h>
@@ -92,6 +93,18 @@ extern "C" {
     QPDF_DLL
     void qpdfjob_cleanup(qpdfjob_handle* j);
 
+    /* Set or get the current logger. You need to call
+     * qpdflogger_cleanup on the logger handles when you are done with
+     * the handles. The underlying logger is cleaned up automatically
+     * and persists if needed after the logger handle is destroyed.
+     * See comments in qpdflogger-c.h for details.
+     */
+
+    QPDF_DLL
+    void qpdfjob_set_logger(qpdfjob_handle j, qpdflogger_handle logger);
+    QPDF_DLL
+    qpdflogger_handle qpdfjob_get_logger(qpdfjob_handle j);
+
     /* This function wraps QPDFJob::initializeFromArgv. The return
      * value is the same as qpdfjob_run. If this returns an error, it
      * is invalid to call any other functions this job handle.
diff --git a/include/qpdf/qpdflogger-c.h b/include/qpdf/qpdflogger-c.h
index 6bf456e7..235efac1 100644
--- a/include/qpdf/qpdflogger-c.h
+++ b/include/qpdf/qpdflogger-c.h
@@ -38,16 +38,28 @@ extern "C" {
 
     /* To operate on a logger, you need a handle to it. call
      * qpdflogger_default_logger to get a handle for the default
-     * logger. The qpdf and qpdfjob functions may offer ways to get
-     * other logger handles. When you're done with the logger handler,
-     * call qpdflogger_cleanup. This does not destroy the underlying
-     * log object. It just cleans up the handle to it.
+     * logger. There are functions in qpdf-c.h and qpdfjob-c.h that
+     * also take or return logger handles. When you're done with the
+     * logger handler, call qpdflogger_cleanup. This cleans up the
+     * handle but leaves the underlying log object intact. (It uses a
+     * shared pointer and will be cleaned up automatically when it is
+     * no longer in use.) That means you can create a logger with
+     * qpdflogger_create(), pass the logger handle to a function in
+     * qpdf-c.h or qpdfjob-c.h, and then clean it up, subject to
+     * constraints imposed by the other function.
      */
 
     typedef struct _qpdflogger_handle* qpdflogger_handle;
     QPDF_DLL
     qpdflogger_handle qpdflogger_default_logger();
 
+    /* Calling cleanup on the handle returned by qpdflogger_create
+     * destroys the handle but not the underlying logger. See comments
+     * above.
+     */
+    QPDF_DLL
+    qpdflogger_handle qpdflogger_create();
+
     QPDF_DLL
     void qpdflogger_cleanup(qpdflogger_handle* l);
 
@@ -95,6 +107,10 @@ extern "C" {
     void qpdflogger_save_to_standard_output(
         qpdflogger_handle l, int only_if_not_set);
 
+    /* For testing */
+    QPDF_DLL
+    int qpdflogger_equal(qpdflogger_handle l1, qpdflogger_handle l2);
+
 #ifdef __cplusplus
 }
 #endif
-- 
cgit v1.2.3-70-g09d2