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