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