]>
Commit | Line | Data |
---|---|---|
e94d2f10 | 1 | /* |
503b54c9 | 2 | * API versioning definitions for CUPS. |
e94d2f10 | 3 | * |
f1b7e563 | 4 | * Copyright © 2007-2018 by Apple Inc. |
e94d2f10 | 5 | * |
f1b7e563 MS |
6 | * Licensed under Apache License v2.0. See the file "LICENSE" for more |
7 | * information. | |
e94d2f10 MS |
8 | */ |
9 | ||
10 | #ifndef _CUPS_VERSIONING_H_ | |
11 | # define _CUPS_VERSIONING_H_ | |
12 | ||
13 | /* | |
be3b49a3 MS |
14 | * This header defines several macros that add compiler-specific attributes for |
15 | * functions: | |
749b1e90 | 16 | * |
be3b49a3 MS |
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. | |
e3586875 MS |
25 | * - _CUPS_INTERNAL: Function is internal with no replacement API. |
26 | * - _CUPS_INTERNAL_MSG("msg"): Function is internal - use specified API | |
27 | * instead. | |
be3b49a3 MS |
28 | * - _CUPS_NONNULL((arg list)): Specifies the comma-separated argument indices |
29 | * are assumed non-NULL. Indices start at 1. | |
a32af27c | 30 | * - _CUPS_NORETURN: Specifies the function does not return. |
be3b49a3 MS |
31 | * - _CUPS_PRIVATE: Specifies the function is private to CUPS. |
32 | * - _CUPS_PUBLIC: Specifies the function is public API. | |
e94d2f10 MS |
33 | */ |
34 | ||
e94d2f10 | 35 | /* |
be3b49a3 MS |
36 | * Determine which compiler is being used and what annotation features are |
37 | * available... | |
e94d2f10 MS |
38 | */ |
39 | ||
be3b49a3 MS |
40 | # ifdef __APPLE__ |
41 | # include <os/availability.h> | |
42 | # endif /* __APPLE__ */ | |
43 | ||
0fa6c7fa MS |
44 | # ifdef __has_extension /* Clang */ |
45 | # define _CUPS_HAS_DEPRECATED | |
be3b49a3 | 46 | # define _CUPS_HAS_FORMAT |
a32af27c | 47 | # define _CUPS_HAS_NORETURN |
be3b49a3 | 48 | # define _CUPS_HAS_VISIBILITY |
0fa6c7fa MS |
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 | |
be3b49a3 | 58 | # define _CUPS_HAS_FORMAT |
a32af27c | 59 | # define _CUPS_HAS_NORETURN |
be3b49a3 | 60 | # define _CUPS_HAS_VISIBILITY |
0fa6c7fa MS |
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 */ | |
d3a97696 MS |
68 | # elif defined(_WIN32) |
69 | # define __attribute__(...) | |
0fa6c7fa MS |
70 | # endif /* __has_extension */ |
71 | ||
be3b49a3 MS |
72 | |
73 | /* | |
e3586875 MS |
74 | * Define _CUPS_INTERNAL, _CUPS_PRIVATE, and _CUPS_PUBLIC visibilty macros for |
75 | * internal/private/public functions... | |
be3b49a3 MS |
76 | */ |
77 | ||
78 | # ifdef _CUPS_HAS_VISIBILITY | |
e3586875 MS |
79 | # define _CUPS_INTERNAL __attribute__ ((visibility("hidden"))) |
80 | # define _CUPS_PRIVATE __attribute__ ((visibility("default"))) | |
be3b49a3 | 81 | # define _CUPS_PUBLIC __attribute__ ((visibility("default"))) |
d3a97696 | 82 | # elif defined(_WIN32) && defined(LIBCUPS2_EXPORTS) && 0 |
e3586875 MS |
83 | # define _CUPS_INTERNAL |
84 | # define _CUPS_PRIVATE __declspec(dllexport) | |
be3b49a3 MS |
85 | # define _CUPS_PUBLIC __declspec(dllexport) |
86 | # else | |
e3586875 | 87 | # define _CUPS_INTERNAL |
be3b49a3 MS |
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_IOS | |
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 | ||
0fa6c7fa MS |
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 | */ | |
be3b49a3 MS |
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 | |
387ff05c | 160 | # elif defined(__APPLE__) && defined(_CUPS_NO_DEPRECATED) |
be3b49a3 MS |
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)) API_UNAVAILABLE(ios) _CUPS_PUBLIC | |
168 | # define _CUPS_DEPRECATED_1_6_MSG(m) API_DEPRECATED(m, macos(10.2,10.8)) API_UNAVAILABLE(ios) _CUPS_PUBLIC | |
169 | # define _CUPS_DEPRECATED_1_7_MSG(m) API_DEPRECATED(m, macos(10.2,10.9)) API_UNAVAILABLE(ios) _CUPS_PUBLIC | |
170 | # define _CUPS_DEPRECATED_2_2_MSG(m) API_DEPRECATED(m, macos(10.2,10.12)) API_UNAVAILABLE(ios) _CUPS_PUBLIC | |
387ff05c MS |
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)) API_UNAVAILABLE(ios) _CUPS_PUBLIC | |
179 | # define _CUPS_DEPRECATED_1_6_MSG(m) API_DEPRECATED(m, macos(10.2,10.8)) API_UNAVAILABLE(ios) _CUPS_PUBLIC | |
180 | # define _CUPS_DEPRECATED_1_7_MSG(m) API_DEPRECATED(m, macos(10.2,10.9)) API_UNAVAILABLE(ios) _CUPS_PUBLIC | |
181 | # define _CUPS_DEPRECATED_2_2_MSG(m) API_DEPRECATED(m, macos(10.2,10.12)) API_UNAVAILABLE(ios) _CUPS_PUBLIC | |
182 | ||
0fa6c7fa MS |
183 | # elif defined(_CUPS_HAS_UNAVAILABLE_WITH_MESSAGE) && defined(_CUPS_NO_DEPRECATED) |
184 | /* | |
e666fe5e | 185 | * Compiler supports the unavailable attribute, so use it when the code |
0fa6c7fa MS |
186 | * wants to exclude the use of deprecated API. |
187 | */ | |
be3b49a3 MS |
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 | |
0fa6c7fa MS |
194 | # else |
195 | /* | |
196 | * Compiler supports the deprecated attribute, so use it. | |
197 | */ | |
be3b49a3 | 198 | # define _CUPS_DEPRECATED __attribute__ ((deprecated)) _CUPS_PUBLIC |
0fa6c7fa | 199 | # ifdef _CUPS_HAS_DEPRECATED_WITH_MESSAGE |
be3b49a3 MS |
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 | |
0fa6c7fa | 205 | # else |
be3b49a3 MS |
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 | |
0fa6c7fa | 211 | # endif /* _CUPS_HAS_DEPRECATED_WITH_MESSAGE */ |
0fa6c7fa | 212 | # endif /* !_CUPS_HAS_DEPRECATED || (_CUPS_SOURCE && !_CUPS_NO_DEPRECATED) */ |
e94d2f10 | 213 | |
be3b49a3 MS |
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 | ||
aaf19ab0 | 255 | |
a32af27c MS |
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 | ||
e94d2f10 | 267 | #endif /* !_CUPS_VERSIONING_H_ */ |