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

9 files changed, 228 insertions, 1 deletions

diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
index 9af85fe2..614047d5 100644
--- a/examples/CMakeLists.txt
+++ b/examples/CMakeLists.txt
@@ -34,6 +34,11 @@ foreach(PROG ${EXAMPLE_C_PROGRAMS})
 endforeach()
 target_include_directories(pdf-create PRIVATE ${JPEG_INCLUDE})
 
+# extend-c-api contains a mixture of C and C++ files.
+add_executable(extend-c-api extend-c-api-impl.cc extend-c-api.c)
+set_property(TARGET extend-c-api PROPERTY LINKER_LANGUAGE CXX)
+target_link_libraries(extend-c-api libqpdf)
+
 add_test(
   NAME examples
   COMMAND ${RUN_QTEST}
@@ -47,7 +52,7 @@ add_test(
   --tc "${qpdf_SOURCE_DIR}/examples/*.cc"
   --tc "${qpdf_SOURCE_DIR}/examples/*.c")
 
-file(GLOB EXAMPLES_SRC "*.c" "*.cc")
+file(GLOB EXAMPLES_SRC "*.c" "*.cc" "*.h")
 if(INSTALL_EXAMPLES)
   install(FILES ${EXAMPLES_SRC}
     DESTINATION ${CMAKE_INSTALL_DOCDIR}/examples
diff --git a/examples/extend-c-api-impl.cc b/examples/extend-c-api-impl.cc
new file mode 100644
index 00000000..680d957b
--- /dev/null
+++ b/examples/extend-c-api-impl.cc
@@ -0,0 +1,29 @@
+// This is an example of how to write C++ functions and make them usable with the qpdf C API. It
+// consists of three files:
+// - extend-c-api.h -- a plain C header file
+// - extend-c-api.c -- a C program that calls the function
+// - extend-c-api.cc -- a C++ file that implements the function
+
+#include "extend-c-api.h"
+
+// Here, we add a function to get the number of pages in a PDF file and make it callable through the
+// C API.
+
+// This is a normal C++ function that works with QPDF in a normal way. It doesn't do anything
+// special to be callable from C.
+int
+numPages(std::shared_ptr<QPDF> qpdf)
+{
+    return qpdf->getRoot().getKey("/Pages").getKey("/Count").getIntValueAsInt();
+}
+
+// Now we define the glue that makes our function callable using the C API.
+
+// This is the C++ implementation of the C function.
+QPDF_ERROR_CODE
+num_pages(qpdf_data qc, int* npages)
+{
+    // Call qpdf_c_wrap to convert any exception our function might through to a QPDF_ERROR_CODE
+    // and attach it to the qpdf_data object in the same way as other functions in the C API.
+    return qpdf_c_wrap(qc, [&qc, &npages]() { *npages = numPages(qpdf_c_get_qpdf(qc)); });
+}
diff --git a/examples/extend-c-api.c b/examples/extend-c-api.c
new file mode 100644
index 00000000..aa603845
--- /dev/null
+++ b/examples/extend-c-api.c
@@ -0,0 +1,67 @@
+/*
+ * This is an example of how to write C++ functions and make them usable with the qpdf C API. It
+ * consists of three files:
+ * - extend-c-api.h -- a plain C header file
+ * - extend-c-api.c -- a C program that calls the function
+ * - extend-c-api.cc -- a C++ file that implements the function
+ */
+
+#include "extend-c-api.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static char const* whoami = 0;
+
+static void
+usage()
+{
+    fprintf(stderr, "Usage: %s infile\n", whoami);
+    exit(2);
+}
+
+int
+main(int argc, char* argv[])
+{
+    char* infile = NULL;
+    qpdf_data qpdf = qpdf_init();
+    int warnings = 0;
+    int errors = 0;
+    char* p = NULL;
+
+    if ((p = strrchr(argv[0], '/')) != NULL) {
+        whoami = p + 1;
+    } else if ((p = strrchr(argv[0], '\\')) != NULL) {
+        whoami = p + 1;
+    } else {
+        whoami = argv[0];
+    }
+
+    if (argc != 2) {
+        usage();
+    }
+
+    infile = argv[1];
+
+    if ((qpdf_read(qpdf, infile, NULL) & QPDF_ERRORS) == 0) {
+        int npages;
+        if ((num_pages(qpdf, &npages) & QPDF_ERRORS) == 0) {
+            printf("num pages = %d\n", npages);
+        }
+    }
+    if (qpdf_more_warnings(qpdf)) {
+        warnings = 1;
+    }
+    if (qpdf_has_error(qpdf)) {
+        errors = 1;
+        printf("error: %s\n", qpdf_get_error_full_text(qpdf, qpdf_get_error(qpdf)));
+    }
+    qpdf_cleanup(&qpdf);
+    if (errors) {
+        return 2;
+    } else if (warnings) {
+        return 3;
+    }
+
+    return 0;
+}
diff --git a/examples/extend-c-api.h b/examples/extend-c-api.h
new file mode 100644
index 00000000..3b2d12d4
--- /dev/null
+++ b/examples/extend-c-api.h
@@ -0,0 +1,25 @@
+#ifndef EXAMPLE_C_EXTEND_H
+#define EXAMPLE_C_EXTEND_H
+
+/*
+ * This is an example of how to write C++ functions and make them usable with the qpdf C API. It
+ * consists of three files:
+ * - extend-c-api.h -- a plain C header file
+ * - extend-c-api.c -- a C program that calls the function
+ * - extend-c-api.cc -- a C++ file that implements the function
+ */
+#include <qpdf/qpdf-c.h>
+
+/* Declare your custom function to return QPDF_ERROR_CODE and take qpdf_data and anything else you
+ * need. Any errors are retrievable through the qpdf C APIs normal error-handling mechanism.
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+    QPDF_ERROR_CODE num_pages(qpdf_data qc, int* npages);
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* EXAMPLE_C_EXTEND_H */
diff --git a/examples/qtest/extend-c-api.test b/examples/qtest/extend-c-api.test
new file mode 100644
index 00000000..3dd82193
--- /dev/null
+++ b/examples/qtest/extend-c-api.test
@@ -0,0 +1,30 @@
+#!/usr/bin/env perl
+require 5.008;
+use warnings;
+use strict;
+
+chdir("extend-c-api") or die "chdir testdir failed: $!\n";
+
+require TestDriver;
+
+cleanup();
+
+my $td = new TestDriver('extend-c-api');
+
+$td->runtest("extend C API (good)",
+             {$td->COMMAND => "extend-c-api good.pdf"},
+             {$td->FILE => "good.out", $td->EXIT_STATUS => 0},
+             $td->NORMALIZE_NEWLINES);
+$td->runtest("extend C API (bad)",
+             {$td->COMMAND => "extend-c-api bad.pdf"},
+             {$td->FILE => "bad.out", $td->EXIT_STATUS => 2},
+             $td->NORMALIZE_NEWLINES);
+
+cleanup();
+
+$td->report(2);
+
+sub cleanup
+{
+    unlink "a.pdf";
+}
diff --git a/examples/qtest/extend-c-api/bad.out b/examples/qtest/extend-c-api/bad.out
new file mode 100644
index 00000000..51f1d56b
--- /dev/null
+++ b/examples/qtest/extend-c-api/bad.out
@@ -0,0 +1,5 @@
+WARNING: bad.pdf: can't find PDF header
+WARNING: bad.pdf: file is damaged
+WARNING: bad.pdf: can't find startxref
+WARNING: bad.pdf: Attempting to reconstruct cross-reference table
+error: bad.pdf: unable to find trailer dictionary while recovering damaged file
diff --git a/examples/qtest/extend-c-api/bad.pdf b/examples/qtest/extend-c-api/bad.pdf
new file mode 100644
index 00000000..a3d2d925
--- /dev/null
+++ b/examples/qtest/extend-c-api/bad.pdf
@@ -0,0 +1 @@
+not even a pdf file
diff --git a/examples/qtest/extend-c-api/good.out b/examples/qtest/extend-c-api/good.out
new file mode 100644
index 00000000..98205fae
--- /dev/null
+++ b/examples/qtest/extend-c-api/good.out
@@ -0,0 +1 @@
+num pages = 1
diff --git a/examples/qtest/extend-c-api/good.pdf b/examples/qtest/extend-c-api/good.pdf
new file mode 100644
index 00000000..42867b96
--- /dev/null
+++ b/examples/qtest/extend-c-api/good.pdf
@@ -0,0 +1,64 @@
+%PDF-2.0
+1 0 obj
+<<
+  /Pages 2 0 R
+  /Type /Catalog
+>>
+endobj
+2 0 obj
+<<
+  /Count 1
+  /Kids [
+    3 0 R
+  ]
+  /Type /Pages
+>>
+endobj
+3 0 obj
+<<
+  /Contents 4 0 R
+  /MediaBox [ 0 0 612 792 ]
+  /Parent 2 0 R
+  /Resources <<
+    /Font << /F1 5 0 R >>
+  >>
+  /Type /Page
+>>
+endobj
+4 0 obj
+<<
+  /Length 44
+>>
+stream
+BT
+  /F1 24 Tf
+  72 720 Td
+  (Potato) Tj
+ET
+endstream
+endobj
+5 0 obj
+<<
+  /BaseFont /Helvetica
+  /Encoding /WinAnsiEncoding
+  /Subtype /Type1
+  /Type /Font
+>>
+endobj
+
+xref
+0 6
+0000000000 65535 f 
+0000000009 00000 n 
+0000000062 00000 n 
+0000000133 00000 n 
+0000000277 00000 n 
+0000000372 00000 n 
+trailer <<
+  /Root 1 0 R
+  /Size 6
+  /ID [<42841c13bbf709d79a200fa1691836f8><b1d8b5838eeafe16125317aa78e666aa>]
+>>
+startxref
+478
+%%EOF