cups/versioning.h

   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(11.0)) _CUPS_PUBLIC
 120 #    define _CUPS_API_2_2_7 API_AVAILABLE(macos(10.14), ios(11.0)) _CUPS_PUBLIC
 121 #    define _CUPS_API_2_3 _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_ */