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