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 visibilty 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

source code of include/cups/versioning.h