From 6d2db68f2ecd1f8b0945bc982af7a9807436d881 Mon Sep 17 00:00:00 2001 From: Jay Berkenbilt Date: Fri, 2 Sep 2022 14:43:29 -0400 Subject: Update comments in Constants.h --- include/qpdf/Constants.h | 42 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 41 insertions(+), 1 deletion(-) diff --git a/include/qpdf/Constants.h b/include/qpdf/Constants.h index 006ff20e..68214c62 100644 --- a/include/qpdf/Constants.h +++ b/include/qpdf/Constants.h @@ -23,10 +23,50 @@ #ifndef QPDFCONSTANTS_H #define QPDFCONSTANTS_H -/* Keep this file 'C' compatible so it can be used from the C and C++ +/* + * REMEMBER: + * + * Keep this file 'C' compatible so it can be used from the C and C++ * interfaces. */ +/* ****************************** NOTE ****************************** + +Tl;Dr: new values must be added to the end such that no constant's +numerical value changes, even across major releases. + +Details: + +As new values are added to existing enumerated types in this file, +it is important not to change the actual values of any constants. +This means that, in the absence of explicit assignment of values, +the order of entries can't change even across major releases. Why? +Here are the reasons: + +* Many of these constants are used by the C API. The C API is used + through foreign function call interfaces by users of other languages + who may not have access to or the ability to parse a C header file. + As such, users are likely to hard-code numerical values or create + their own constants whose values match. If we change values here, + their code would break, and there would be no way to detect it short + of noticing a bug. Furthermore, it would be difficult to write code + that properly handled more than one version of the qpdf shared + object (e.g. DLL) since the information about what version of qpdf + is involved is only available at runtime. + +- It has happened from time to time that a user builds an application + with an incorrectly installed qpdf, such as having mismatched header + files and library files. In the event that they are only using qpdf + interfaces that have been stable across the versions in question, + this turns out to be harmless. If they happen to use non-compatible + interfaces, this results usually in a failure to load or an obvious + runtime error. If we change values of constants, it is possible that + code that links and runs may have mismatched values for constants. + This would create a bug that would be extremely difficult to track + down and impossible for qpdf maintainers to reproduce. + +*/ + /* Exit Codes from QPDFJob and the qpdf CLI */ enum qpdf_exit_code_e { -- cgit v1.2.3-54-g00ecf