Expose exit code values to C API via Constants.h

ChangeLog

@@ -1,5 +1,8 @@
 2022-06-18  Jay Berkenbilt  <ejb@ql.org>
 
+        * Add qpdf_exit_code_e to Constants.h so that exit codes from
+        QPDFJob are accessible to the C API.
+
         * When --progress or --verbose is combined with writing to
         standard output, progress reporting and verbose messages go to
         standard error. Previously it was disabled in this case.

TODO

@@ -47,8 +47,6 @@ Output Capture + QPDFJob
 
 QPDFJob:
 
-* Expose the meanings of the return values of qpdfjob functions to the
-  C API.
 * Allow users to supply a custom progress reporter for QPDFJob
 
 Output Capture

include/qpdf/Constants.h

@@ -27,6 +27,18 @@
  * interfaces.
  */
 
+/* Exit Codes from QPDFJob and the qpdf CLI */
+
+enum qpdf_exit_code_e {
+    qpdf_exit_success = 0,
+    /* Normal exit codes */
+    qpdf_exit_error = 2,
+    qpdf_exit_warning = 3,
+    /* For --is-encrypted and --requires-password */
+    qpdf_exit_is_not_encrypted = 2,
+    qpdf_exit_correct_password = 3,
+};
+
 /* Error Codes */
 
 enum qpdf_error_code_e {

include/qpdf/QPDFJob.hh

@@ -47,11 +47,11 @@ class QPDFJob
 {
   public:
     // Exit codes -- returned by getExitCode() after calling run()
-    static int constexpr EXIT_ERROR = 2;
+    static int constexpr EXIT_ERROR = qpdf_exit_error;
-    static int constexpr EXIT_WARNING = 3;
+    static int constexpr EXIT_WARNING = qpdf_exit_warning;
     // For is-encrypted and requires-password
-    static int constexpr EXIT_IS_NOT_ENCRYPTED = 2;
+    static int constexpr EXIT_IS_NOT_ENCRYPTED = qpdf_exit_is_not_encrypted;
-    static int constexpr EXIT_CORRECT_PASSWORD = 3;
+    static int constexpr EXIT_CORRECT_PASSWORD = qpdf_exit_correct_password;
 
     // QPDFUsage is thrown if there are any usage-like errors when
     // calling Config methods.

include/qpdf/qpdfjob-c.h

@@ -49,7 +49,9 @@ extern "C" {
      * command-line with the given arguments and returns the exit code
      * that qpdf would use. argv must be a null-terminated array of
      * null-terminated UTF8-encoded strings. If calling this from
-     * wmain on Windows, use qpdfjob_run_from_wide_argv instead.
+     * wmain on Windows, use qpdfjob_run_from_wide_argv instead. Exit
+     * code values are defined in Constants.h in the qpdf_exit_code_e
+     * type.
      */
     QPDF_DLL
     int qpdfjob_run_from_argv(char const* const argv[]);
@@ -66,7 +68,8 @@ extern "C" {
     /* This function runs QPDFJob from a job JSON file. See the "QPDF
      * Job" section of the manual for details. The JSON string must be
      * UTF8-encoded. It returns the error code that qpdf would return
-     * with the equivalent command-line invocation.
+     * with the equivalent command-line invocation. Exit code values
+     * are defined in Constants.h in the qpdf_exit_code_e type.
      */
     QPDF_DLL
     int qpdfjob_run_from_json(char const* json);

manual/release-notes.rst

@@ -1717,6 +1717,12 @@ For a detailed list of changes, please see the file
       and may optionally compensate for rotation or scaling of the
       destination page.
 
+    - Exit codes returned by ``QPDFJob::run()`` and the C API wrappers
+      are now defined in :file:`qpdf/Constants.h` in the
+      ``qpdf_exit_code_e`` type so that they are accessible from the C
+      API. They were previously only defined as constants in
+      :file:`qpdf/QPDFJob.hh`.
+
   - Build Improvements
 
     - Add new configure option