Re-introduce QPDFObject.hh as deprecated

* Just removing a header file would cause build errors with no hint as
  to what happened. This way, people get a warning rather than error
  for the life of qpdf 11, and the warning tells them what to do.

* This avoids build surprises resulting from having two versions of
  QPDF headers installed at once. If you were building code out of a
  checkout of qpdf but had an older version installed on your system,
  if your code included <qpdf/QPDFObject.hh>, everything would work,
  but then your code would break without QPDFObject.hh later.

include/qpdf/QPDFObject.hh

@@ -0,0 +1,64 @@
+// Copyright (c) 2005-2022 Jay Berkenbilt
+//
+// This file is part of qpdf.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+//
+// Versions of qpdf prior to version 7 were released under the terms
+// of version 2.0 of the Artistic License. At your option, you may
+// continue to consider qpdf to be licensed under those terms. Please
+// see the manual for additional information.
+
+#ifndef QPDFOBJECT_HH
+#define QPDFOBJECT_HH
+
+#ifndef QPDF_OBJECT_NOWARN
+// ABI: remove this file in qpdf 12
+# warning "QPDFObject.hh is deprecated see comments in QPDFObject.hh"
+#endif
+
+#include <qpdf/Constants.h>
+class QPDFObject
+{
+  public:
+    // This file and these symbols will be removed in QPDF 12. Instead
+    // of including this header, include <qpdf/Constants.h>. Replace
+    // `QPDFObject::ot_` with `::ot_` in your code.
+
+    // Prior to qpdf 10.5, qpdf_object_type_e was
+    // QPDFObject::object_type_e but was moved to make it accessible
+    // to the C API. The code below is for backward compatibility
+    // until qpdf 12.
+    typedef enum qpdf_object_type_e object_type_e;
+    static constexpr object_type_e ot_uninitialized = ::ot_uninitialized;
+    static constexpr object_type_e ot_reserved = ::ot_reserved;
+    static constexpr object_type_e ot_null = ::ot_null;
+    static constexpr object_type_e ot_boolean = ::ot_boolean;
+    static constexpr object_type_e ot_integer = ::ot_integer;
+    static constexpr object_type_e ot_real = ::ot_real;
+    static constexpr object_type_e ot_string = ::ot_string;
+    static constexpr object_type_e ot_name = ::ot_name;
+    static constexpr object_type_e ot_array = ::ot_array;
+    static constexpr object_type_e ot_dictionary = ::ot_dictionary;
+    static constexpr object_type_e ot_stream = ::ot_stream;
+    static constexpr object_type_e ot_operator = ::ot_operator;
+    static constexpr object_type_e ot_inlineimage = ::ot_inlineimage;
+    static constexpr object_type_e ot_unresolved = ::ot_unresolved;
+
+  private:
+    QPDFObject() = delete;
+    QPDFObject(QPDFObject const&) = delete;
+    QPDFObject& operator=(QPDFObject const&) = delete;
+};
+
+#endif // QPDFOBJECT_HH

manual/release-notes.rst

@@ -95,17 +95,17 @@ For a detailed list of changes, please see the file
 
   - API: breaking changes
 
-    - Remove ``QPDFObject.hh`` from the public ``include/qpdf``
-      directory. The only use case for including
-      ``qpdf/QPDFObject.hh`` was to get ``QPDFObject::object_type_e``.
-      Since 10.5.0, this has been an alias to ``qpdf_object_type_e``,
-      defined in ``qpdf/Constants.h``. To fix your code, replace any
-      includes of ``qpdf/QPDFObject.hh`` with ``qpdf/Constants.h``,
-      and replace all occurrences of ``QPDFObject::ot_`` with
-      ``::ot_``. If you need your code to be backward compatible to
-      qpdf versions prior to 10.5.0, you can check that the
-      preprocessor symbol ``QPDF_MAJOR_VERSION`` is defined and ``>=
-      11``.
+    - Deprecate ``QPDFObject.hh`` for removal in qpdf 12. The only use
+      case for including ``qpdf/QPDFObject.hh`` was to get
+      ``QPDFObject::object_type_e``. Since 10.5.0, this has been an
+      alias to ``qpdf_object_type_e``, defined in
+      ``qpdf/Constants.h``. To fix your code, replace any includes of
+      ``qpdf/QPDFObject.hh`` with ``qpdf/Constants.h``, and replace
+      all occurrences of ``QPDFObject::ot_`` with ``::ot_``. If you
+      need your code to be backward compatible to qpdf versions prior
+      to 10.5.0, you can check that the preprocessor symbol
+      ``QPDF_MAJOR_VERSION`` is defined and ``>= 11``. As a stop-gap,
+      you can `#define QPDF_OBJECT_NOWARN` to suppress the warning.
 
     - Pipeline::write now takes ``unsigned char const*`` instead of
       ``unsigned char*``. Callers don't need to change anything, but

qpdf/test_driver.cc

@@ -35,6 +35,9 @@
 #include <stdlib.h>
 #include <string.h>
 
+#define QPDF_OBJECT_NOWARN
+#include <qpdf/QPDFObject.hh>
+
 static char const* whoami = 0;
 
 void
@@ -3298,6 +3301,10 @@ runtest(int n, char const* filename1, char const* arg2)
         QPDFObjectHandle uninitialized;
         assert(uninitialized.getTypeCode() == ::ot_uninitialized);
         assert(strcmp(uninitialized.getTypeName(), "uninitialized") == 0);
+
+        // ABI: until QPDF 12, spot check deprecated constants
+        assert(QPDFObject::ot_unresolved == ::ot_unresolved);
+        assert(QPDFObject::ot_uninitialized == ::ot_uninitialized);
     }
 
     QPDF pdf;