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