1 /* 2 * API versioning definitions for CUPS. 3 * 4 * Copyright © 2021 by OpenPrinting. 5 * Copyright © 2007-2019 by Apple Inc. 6 * 7 * Licensed under Apache License v2.0. See the file "LICENSE" for more 8 * information. 9 */ 10 11 #ifndef _CUPS_VERSIONING_H_ 12 # define _CUPS_VERSIONING_H_ 13 14 /* 15 * This header defines several macros that add compiler-specific attributes for 16 * functions: 17 * 18 * - _CUPS_API_major_minor[_patch]: Specifies when an API became available by 19 * CUPS version. 20 * - _CUPS_DEPRECATED: Function is deprecated with no replacement. 21 * - _CUPS_DEPRECATED_MSG("message"): Function is deprecated and has a 22 * replacement. 23 * - _CUPS_FORMAT(format-index, additional-args-index): Function has a 24 * printf-style format argument followed by zero or more additional 25 * arguments. Indices start at 1. 26 * - _CUPS_INTERNAL: Function is internal with no replacement API. 27 * - _CUPS_INTERNAL_MSG("msg"): Function is internal - use specified API 28 * instead. 29 * - _CUPS_NONNULL((arg list)): Specifies the comma-separated argument indices 30 * are assumed non-NULL. Indices start at 1. 31 * - _CUPS_NORETURN: Specifies the function does not return. 32 * - _CUPS_PRIVATE: Specifies the function is private to CUPS. 33 * - _CUPS_PUBLIC: Specifies the function is public API. 34 */ 35 36 /* 37 * Determine which compiler is being used and what annotation features are 38 * available... 39 */ 40 41 # if defined(__APPLE__) && defined(__has_include) 42 # if __has_include(<os/availability.h>) 43 # include <os/availability.h> 44 # define _CUPS_API_AVAILABLE(...) API_AVAILABLE(__VA_ARGS__) 45 # define _CUPS_API_DEPRECATED(...) API_DEPRECATED(__VA_ARGS__) 46 # else 47 # define _CUPS_API_AVAILABLE(...) 48 # define _CUPS_API_DEPRECATED(...) 49 # endif /* __has_include(<os/availability.h>) */ 50 # else 51 # define _CUPS_API_AVAILABLE(...) 52 # define _CUPS_API_DEPRECATED(...) 53 # endif /* __APPLE__ && __has_include */ 54 55 # ifdef __has_extension /* Clang */ 56 # define _CUPS_HAS_DEPRECATED 57 # define _CUPS_HAS_FORMAT 58 # define _CUPS_HAS_NORETURN 59 # define _CUPS_HAS_VISIBILITY 60 # if __has_extension(attribute_deprecated_with_message) 61 # define _CUPS_HAS_DEPRECATED_WITH_MESSAGE 62 # endif 63 # if __has_extension(attribute_unavailable_with_message) 64 # define _CUPS_HAS_UNAVAILABLE_WITH_MESSAGE 65 # endif 66 # elif defined(__GNUC__) /* GCC and compatible */ 67 # if __GNUC__ >= 3 /* GCC 3.0 or higher */ 68 # define _CUPS_HAS_DEPRECATED 69 # define _CUPS_HAS_FORMAT 70 # define _CUPS_HAS_NORETURN 71 # define _CUPS_HAS_VISIBILITY 72 # endif /* __GNUC__ >= 3 */ 73 # if __GNUC__ >= 5 /* GCC 5.x */ 74 # define _CUPS_HAS_DEPRECATED_WITH_MESSAGE 75 # elif __GNUC__ == 4 && __GNUC_MINOR__ >= 5 76 /* GCC 4.5 or higher */ 77 # define _CUPS_HAS_DEPRECATED_WITH_MESSAGE 78 # endif /* __GNUC__ >= 5 */ 79 # elif defined(_WIN32) 80 # define __attribute__(...) 81 # endif /* __has_extension */ 82 83 84 /* 85 * Define _CUPS_INTERNAL, _CUPS_PRIVATE, and _CUPS_PUBLIC visibility macros for 86 * internal/private/public functions... 87 */ 88 89 # ifdef _CUPS_HAS_VISIBILITY 90 # define _CUPS_INTERNAL __attribute__ ((visibility("hidden"))) 91 # define _CUPS_PRIVATE __attribute__ ((visibility("default"))) 92 # define _CUPS_PUBLIC __attribute__ ((visibility("default"))) 93 # elif defined(_WIN32) && defined(LIBCUPS2_EXPORTS) && 0 94 # define _CUPS_INTERNAL 95 # define _CUPS_PRIVATE __declspec(dllexport) 96 # define _CUPS_PUBLIC __declspec(dllexport) 97 # else 98 # define _CUPS_INTERNAL 99 # define _CUPS_PRIVATE 100 # define _CUPS_PUBLIC 101 # endif /* _CUPS_HAS_VISIBILITY */ 102 103 104 /* 105 * Define _CUPS_API_major_minor[_patch] availability macros for CUPS. 106 * 107 * Note: Using any of the _CUPS_API macros automatically adds _CUPS_PUBLIC. 108 */ 109 110 # if defined(__APPLE__) && !defined(_CUPS_SOURCE) && TARGET_OS_OSX 111 /* 112 * On Apple operating systems, the _CUPS_API_* constants are defined using the 113 * API_ macros in <os/availability.h>. 114 * 115 * On iOS, we don't actually have libcups available directly, but the supplied 116 * libcups_static target in the Xcode project supports building on iOS 11.0 and 117 * later. 118 */ 119 # define _CUPS_API_1_1_19 _CUPS_API_AVAILABLE(macos(10.3), ios(11.0)) _CUPS_PUBLIC 120 # define _CUPS_API_1_1_20 _CUPS_API_AVAILABLE(macos(10.4), ios(11.0)) _CUPS_PUBLIC 121 # define _CUPS_API_1_1_21 _CUPS_API_AVAILABLE(macos(10.4), ios(11.0)) _CUPS_PUBLIC 122 # define _CUPS_API_1_2 _CUPS_API_AVAILABLE(macos(10.5), ios(11.0)) _CUPS_PUBLIC 123 # define _CUPS_API_1_3 _CUPS_API_AVAILABLE(macos(10.5), ios(11.0)) _CUPS_PUBLIC 124 # define _CUPS_API_1_4 _CUPS_API_AVAILABLE(macos(10.6), ios(11.0)) _CUPS_PUBLIC 125 # define _CUPS_API_1_5 _CUPS_API_AVAILABLE(macos(10.7), ios(11.0)) _CUPS_PUBLIC 126 # define _CUPS_API_1_6 _CUPS_API_AVAILABLE(macos(10.8), ios(11.0)) _CUPS_PUBLIC 127 # define _CUPS_API_1_7 _CUPS_API_AVAILABLE(macos(10.9), ios(11.0)) _CUPS_PUBLIC 128 # define _CUPS_API_2_0 _CUPS_API_AVAILABLE(macos(10.10), ios(11.0)) _CUPS_PUBLIC 129 # define _CUPS_API_2_2 _CUPS_API_AVAILABLE(macos(10.12), ios(11.0)) _CUPS_PUBLIC 130 # define _CUPS_API_2_2_4 _CUPS_API_AVAILABLE(macos(10.13), ios(12.0)) _CUPS_PUBLIC 131 # define _CUPS_API_2_2_7 _CUPS_API_AVAILABLE(macos(10.14), ios(13.0)) _CUPS_PUBLIC 132 # define _CUPS_API_2_3 _CUPS_API_AVAILABLE(macos(10.14), ios(13.0)) _CUPS_PUBLIC 133 # define _CUPS_API_2_4 _CUPS_PUBLIC 134 # else 135 # define _CUPS_API_1_1_19 _CUPS_PUBLIC 136 # define _CUPS_API_1_1_20 _CUPS_PUBLIC 137 # define _CUPS_API_1_1_21 _CUPS_PUBLIC 138 # define _CUPS_API_1_2 _CUPS_PUBLIC 139 # define _CUPS_API_1_3 _CUPS_PUBLIC 140 # define _CUPS_API_1_4 _CUPS_PUBLIC 141 # define _CUPS_API_1_5 _CUPS_PUBLIC 142 # define _CUPS_API_1_6 _CUPS_PUBLIC 143 # define _CUPS_API_1_7 _CUPS_PUBLIC 144 # define _CUPS_API_2_0 _CUPS_PUBLIC 145 # define _CUPS_API_2_2 _CUPS_PUBLIC 146 # define _CUPS_API_2_2_4 _CUPS_PUBLIC 147 # define _CUPS_API_2_2_7 _CUPS_PUBLIC 148 # define _CUPS_API_2_3 _CUPS_PUBLIC 149 # define _CUPS_API_2_4 _CUPS_PUBLIC 150 # endif /* __APPLE__ && !_CUPS_SOURCE */ 151 152 153 /* 154 * Define _CUPS_DEPRECATED and _CUPS_INTERNAL macros to mark old APIs as 155 * "deprecated" or "unavailable" with messages so you get warnings/errors are 156 * compile-time... 157 * 158 * Note: Using any of the _CUPS_DEPRECATED macros automatically adds 159 * _CUPS_PUBLIC. 160 */ 161 162 # if !defined(_CUPS_HAS_DEPRECATED) || (defined(_CUPS_SOURCE) && !defined(_CUPS_NO_DEPRECATED)) 163 /* 164 * Don't mark functions deprecated if the compiler doesn't support it 165 * or we are building CUPS source that doesn't care. 166 */ 167 # define _CUPS_DEPRECATED _CUPS_PUBLIC 168 # define _CUPS_DEPRECATED_MSG(m) _CUPS_PUBLIC 169 # define _CUPS_DEPRECATED_1_2_MSG(m) _CUPS_PUBLIC 170 # define _CUPS_DEPRECATED_1_6_MSG(m) _CUPS_PUBLIC 171 # define _CUPS_DEPRECATED_1_7_MSG(m) _CUPS_PUBLIC 172 # define _CUPS_DEPRECATED_2_2_MSG(m) _CUPS_PUBLIC 173 # elif defined(__APPLE__) && defined(_CUPS_NO_DEPRECATED) 174 /* 175 * Compiler supports the unavailable attribute, so use it when the code 176 * wants to exclude the use of deprecated API. 177 */ 178 # define _CUPS_DEPRECATED __attribute__ ((unavailable)) _CUPS_PUBLIC 179 # define _CUPS_DEPRECATED_MSG(m) __attribute__ ((unavailable(m))) _CUPS_PUBLIC 180 # define _CUPS_DEPRECATED_1_2_MSG(m) _CUPS_API_DEPRECATED(m, macos(10.2,10.5), ios(11.0,11.0)) _CUPS_PUBLIC 181 # define _CUPS_DEPRECATED_1_6_MSG(m) _CUPS_API_DEPRECATED(m, macos(10.2,10.8), ios(11.0,11.0)) _CUPS_PUBLIC 182 # define _CUPS_DEPRECATED_1_7_MSG(m) _CUPS_API_DEPRECATED(m, macos(10.2,10.9), ios(11.0,11.0)) _CUPS_PUBLIC 183 # define _CUPS_DEPRECATED_2_2_MSG(m) _CUPS_API_DEPRECATED(m, macos(10.2,10.12), ios(11.0,11.0)) _CUPS_PUBLIC 184 185 # elif defined(__APPLE__) 186 /* 187 * Just mark things as deprecated... 188 */ 189 # define _CUPS_DEPRECATED __attribute__ ((deprecated)) _CUPS_PUBLIC 190 # define _CUPS_DEPRECATED_MSG(m) __attribute__ ((deprecated(m))) _CUPS_PUBLIC 191 # define _CUPS_DEPRECATED_1_2_MSG(m) _CUPS_API_DEPRECATED(m, macos(10.2,10.5), ios(11.0,11.0)) _CUPS_PUBLIC 192 # define _CUPS_DEPRECATED_1_6_MSG(m) _CUPS_API_DEPRECATED(m, macos(10.2,10.8), ios(11.0,11.0)) _CUPS_PUBLIC 193 # define _CUPS_DEPRECATED_1_7_MSG(m) _CUPS_API_DEPRECATED(m, macos(10.2,10.9), ios(11.0,11.0)) _CUPS_PUBLIC 194 # define _CUPS_DEPRECATED_2_2_MSG(m) _CUPS_API_DEPRECATED(m, macos(10.2,10.12), ios(11.0,11.0)) _CUPS_PUBLIC 195 196 # elif defined(_CUPS_HAS_UNAVAILABLE_WITH_MESSAGE) && defined(_CUPS_NO_DEPRECATED) 197 /* 198 * Compiler supports the unavailable attribute, so use it when the code 199 * wants to exclude the use of deprecated API. 200 */ 201 # define _CUPS_DEPRECATED __attribute__ ((unavailable)) _CUPS_PUBLIC 202 # define _CUPS_DEPRECATED_MSG(m) __attribute__ ((unavailable(m))) _CUPS_PUBLIC 203 # define _CUPS_DEPRECATED_1_2_MSG(m) __attribute__ ((unavailable(m))) _CUPS_PUBLIC 204 # define _CUPS_DEPRECATED_1_6_MSG(m) __attribute__ ((unavailable(m))) _CUPS_PUBLIC 205 # define _CUPS_DEPRECATED_1_7_MSG(m) __attribute__ ((unavailable(m))) _CUPS_PUBLIC 206 # define _CUPS_DEPRECATED_2_2_MSG(m) __attribute__ ((unavailable(m))) _CUPS_PUBLIC 207 # else 208 /* 209 * Compiler supports the deprecated attribute, so use it. 210 */ 211 # define _CUPS_DEPRECATED __attribute__ ((deprecated)) _CUPS_PUBLIC 212 # ifdef _CUPS_HAS_DEPRECATED_WITH_MESSAGE 213 # define _CUPS_DEPRECATED_MSG(m) __attribute__ ((deprecated(m))) _CUPS_PUBLIC 214 # define _CUPS_DEPRECATED_1_2_MSG(m) __attribute__ ((deprecated(m))) _CUPS_PUBLIC 215 # define _CUPS_DEPRECATED_1_6_MSG(m) __attribute__ ((deprecated(m))) _CUPS_PUBLIC 216 # define _CUPS_DEPRECATED_1_7_MSG(m) __attribute__ ((deprecated(m))) _CUPS_PUBLIC 217 # define _CUPS_DEPRECATED_2_2_MSG(m) __attribute__ ((deprecated(m))) _CUPS_PUBLIC 218 # else 219 # define _CUPS_DEPRECATED_MSG(m) __attribute__ ((deprecated)) _CUPS_PUBLIC 220 # define _CUPS_DEPRECATED_1_2_MSG(m) __attribute__ ((deprecated)) _CUPS_PUBLIC 221 # define _CUPS_DEPRECATED_1_6_MSG(m) __attribute__ ((deprecated)) _CUPS_PUBLIC 222 # define _CUPS_DEPRECATED_1_7_MSG(m) __attribute__ ((deprecated)) _CUPS_PUBLIC 223 # define _CUPS_DEPRECATED_2_2_MSG(m) __attribute__ ((deprecated)) _CUPS_PUBLIC 224 # endif /* _CUPS_HAS_DEPRECATED_WITH_MESSAGE */ 225 # endif /* !_CUPS_HAS_DEPRECATED || (_CUPS_SOURCE && !_CUPS_NO_DEPRECATED) */ 226 227 228 /* 229 * Define _CUPS_FORMAT macro for printf-style functions... 230 */ 231 232 # ifdef _CUPS_HAS_FORMAT 233 # define _CUPS_FORMAT(a,b) __attribute__ ((__format__(__printf__, a,b))) 234 # else 235 # define _CUPS_FORMAT(a,b) 236 # endif /* _CUPS_HAS_FORMAT */ 237 238 239 /* 240 * Define _CUPS_INTERNAL_MSG macro for private APIs that have (historical) 241 * public visibility. 242 * 243 * Note: Using the _CUPS_INTERNAL_MSG macro automatically adds _CUPS_PUBLIC. 244 */ 245 246 # ifdef _CUPS_SOURCE 247 # define _CUPS_INTERNAL_MSG(m) _CUPS_PUBLIC 248 # elif defined(_CUPS_HAS_UNAVAILABLE_WITH_MESSAGE) 249 # define _CUPS_INTERNAL_MSG(m) __attribute__ ((unavailable(m))) _CUPS_PUBLIC 250 # elif defined(_CUPS_HAS_DEPRECATED_WITH_MESSAGE) 251 # define _CUPS_INTERNAL_MSG(m) __attribute__ ((deprecated(m))) _CUPS_PUBLIC 252 # else 253 # define _CUPS_INTERNAL_MSG(m) __attribute__ ((deprecated)) _CUPS_PUBLIC 254 # endif /* _CUPS_SOURCE */ 255 256 257 /* 258 * Define _CUPS_NONNULL macro for functions that don't expect non-null 259 * arguments... 260 */ 261 262 # ifdef _CUPS_HAS_NONNULL 263 # define _CUPS_NONNULL(...) __attribute__ ((nonnull(__VA_ARGS__))) 264 # else 265 # define _CUPS_NONNULL(...) 266 # endif /* _CUPS_HAS_FORMAT */ 267 268 269 /* 270 * Define _CUPS_NORETURN macro for functions that don't return. 271 */ 272 273 # ifdef _CUPS_HAS_NORETURN 274 # define _CUPS_NORETURN __attribute__ ((noreturn)) 275 # else 276 # define _CUPS_NORETURN 277 # endif /* _CUPS_HAS_NORETURN */ 278 279 280 #endif /* !_CUPS_VERSIONING_H_ */ 281