1/*
2 * Copyright (c) 2007-2016 by Apple Inc.. All rights reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23
24#ifndef __AVAILABILITY__
25#define __AVAILABILITY__
26 /*
27 These macros are for use in OS header files. They enable function prototypes
28 and Objective-C methods to be tagged with the OS version in which they
29 were first available; and, if applicable, the OS version in which they
30 became deprecated.
31
32 The desktop Mac OS X and iOS each have different version numbers.
33 The __OSX_AVAILABLE_STARTING() macro allows you to specify both the desktop
34 and iOS version numbers. For instance:
35 __OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0)
36 means the function/method was first available on Mac OS X 10.2 on the desktop
37 and first available in iOS 2.0 on the iPhone.
38
39 If a function is available on one platform, but not the other a _NA (not
40 applicable) parameter is used. For instance:
41 __OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_NA)
42 means that the function/method was first available on Mac OS X 10.3, and it
43 currently not implemented on the iPhone.
44
45 At some point, a function/method may be deprecated. That means Apple
46 recommends applications stop using the function, either because there is a
47 better replacement or the functionality is being phased out. Deprecated
48 functions/methods can be tagged with a __OSX_AVAILABLE_BUT_DEPRECATED()
49 macro which specifies the OS version where the function became available
50 as well as the OS version in which it became deprecated. For instance:
51 __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_0,__MAC_10_5,__IPHONE_NA,__IPHONE_NA)
52 means that the function/method was introduced in Mac OS X 10.0, then
53 became deprecated beginning in Mac OS X 10.5. On iOS the function
54 has never been available.
55
56 For these macros to function properly, a program must specify the OS version range
57 it is targeting. The min OS version is specified as an option to the compiler:
58 -mmacosx-version-min=10.x when building for Mac OS X, and -miphoneos-version-min=y.z
59 when building for the iPhone. The upper bound for the OS version is rarely needed,
60 but it can be set on the command line via: -D__MAC_OS_X_VERSION_MAX_ALLOWED=10x0 for
61 Mac OS X and __IPHONE_OS_VERSION_MAX_ALLOWED = y0z00 for iOS.
62
63 Examples:
64
65 A function available in Mac OS X 10.5 and later, but not on the phone:
66
67 extern void mymacfunc() __OSX_AVAILABLE_STARTING(__MAC_10_5,__IPHONE_NA);
68
69
70 An Objective-C method in Mac OS X 10.5 and later, but not on the phone:
71
72 @interface MyClass : NSObject
73 -(void) mymacmethod __OSX_AVAILABLE_STARTING(__MAC_10_5,__IPHONE_NA);
74 @end
75
76
77 An enum available on the phone, but not available on Mac OS X:
78
79 #if __IPHONE_OS_VERSION_MIN_REQUIRED
80 enum { myEnum = 1 };
81 #endif
82 Note: this works when targeting the Mac OS X platform because
83 __IPHONE_OS_VERSION_MIN_REQUIRED is undefined which evaluates to zero.
84
85
86 An enum with values added in different iPhoneOS versions:
87
88 enum {
89 myX = 1, // Usable on iPhoneOS 2.1 and later
90 myY = 2, // Usable on iPhoneOS 3.0 and later
91 myZ = 3, // Usable on iPhoneOS 3.0 and later
92 ...
93 Note: you do not want to use #if with enumeration values
94 when a client needs to see all values at compile time
95 and use runtime logic to only use the viable values.
96
97
98 It is also possible to use the *_VERSION_MIN_REQUIRED in source code to make one
99 source base that can be compiled to target a range of OS versions. It is best
100 to not use the _MAC_* and __IPHONE_* macros for comparisons, but rather their values.
101 That is because you might get compiled on an old OS that does not define a later
102 OS version macro, and in the C preprocessor undefined values evaluate to zero
103 in expresssions, which could cause the #if expression to evaluate in an unexpected
104 way.
105
106 #ifdef __MAC_OS_X_VERSION_MIN_REQUIRED
107 // code only compiled when targeting Mac OS X and not iPhone
108 // note use of 1050 instead of __MAC_10_5
109 #if __MAC_OS_X_VERSION_MIN_REQUIRED < 1050
110 // code in here might run on pre-Leopard OS
111 #else
112 // code here can assume Leopard or later
113 #endif
114 #endif
115
116
117*/
118
119#define __MAC_10_0 1000
120#define __MAC_10_1 1010
121#define __MAC_10_2 1020
122#define __MAC_10_3 1030
123#define __MAC_10_4 1040
124#define __MAC_10_5 1050
125#define __MAC_10_6 1060
126#define __MAC_10_7 1070
127#define __MAC_10_8 1080
128#define __MAC_10_9 1090
129#define __MAC_10_10 101000
130#define __MAC_10_10_2 101002
131#define __MAC_10_10_3 101003
132#define __MAC_10_11 101100
133#define __MAC_10_11_2 101102
134#define __MAC_10_11_3 101103
135#define __MAC_10_11_4 101104
136#define __MAC_10_12 101200
137#define __MAC_10_12_1 101201
138#define __MAC_10_12_2 101202
139#define __MAC_10_12_4 101204
140/* __MAC_NA is not defined to a value but is uses as a token by macros to indicate that the API is unavailable */
141
142#define __IPHONE_2_0 20000
143#define __IPHONE_2_1 20100
144#define __IPHONE_2_2 20200
145#define __IPHONE_3_0 30000
146#define __IPHONE_3_1 30100
147#define __IPHONE_3_2 30200
148#define __IPHONE_4_0 40000
149#define __IPHONE_4_1 40100
150#define __IPHONE_4_2 40200
151#define __IPHONE_4_3 40300
152#define __IPHONE_5_0 50000
153#define __IPHONE_5_1 50100
154#define __IPHONE_6_0 60000
155#define __IPHONE_6_1 60100
156#define __IPHONE_7_0 70000
157#define __IPHONE_7_1 70100
158#define __IPHONE_8_0 80000
159#define __IPHONE_8_1 80100
160#define __IPHONE_8_2 80200
161#define __IPHONE_8_3 80300
162#define __IPHONE_8_4 80400
163#define __IPHONE_9_0 90000
164#define __IPHONE_9_1 90100
165#define __IPHONE_9_2 90200
166#define __IPHONE_9_3 90300
167#define __IPHONE_10_0 100000
168#define __IPHONE_10_1 100100
169#define __IPHONE_10_2 100200
170#define __IPHONE_10_3 100300
171/* __IPHONE_NA is not defined to a value but is uses as a token by macros to indicate that the API is unavailable */
172
173#define __TVOS_9_0 90000
174#define __TVOS_9_1 90100
175#define __TVOS_9_2 90200
176#define __TVOS_10_0 100000
177#define __TVOS_10_0_1 100001
178#define __TVOS_10_1 100100
179#define __TVOS_10_2 100200
180
181#define __WATCHOS_1_0 10000
182#define __WATCHOS_2_0 20000
183#define __WATCHOS_3_0 30000
184#define __WATCHOS_3_1 30100
185#define __WATCHOS_3_1_1 30101
186#define __WATCHOS_3_2 30200
187
188#include <AvailabilityInternal.h>
189
190#ifdef __IPHONE_OS_VERSION_MIN_REQUIRED
191 #define __OSX_AVAILABLE_STARTING(_osx, _ios) __AVAILABILITY_INTERNAL##_ios
192 #define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep) \
193 __AVAILABILITY_INTERNAL##_iosIntro##_DEP##_iosDep
194 #define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg) \
195 __AVAILABILITY_INTERNAL##_iosIntro##_DEP##_iosDep##_MSG(_msg)
196
197#elif defined(__MAC_OS_X_VERSION_MIN_REQUIRED)
198 #define __OSX_AVAILABLE_STARTING(_osx, _ios) __AVAILABILITY_INTERNAL##_osx
199 #define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep) \
200 __AVAILABILITY_INTERNAL##_osxIntro##_DEP##_osxDep
201 #define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg) \
202 __AVAILABILITY_INTERNAL##_osxIntro##_DEP##_osxDep##_MSG(_msg)
203
204#else
205 #define __OSX_AVAILABLE_STARTING(_osx, _ios)
206 #define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep)
207 #define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg)
208#endif
209
210
211#if defined(__has_feature)
212 #if __has_feature(attribute_availability_with_message)
213 #define __OS_AVAILABILITY(_target, _availability) __attribute__((availability(_target,_availability)))
214 #define __OS_AVAILABILITY_MSG(_target, _availability, _msg) __attribute__((availability(_target,_availability,message=_msg)))
215 #elif __has_feature(attribute_availability)
216 #define __OS_AVAILABILITY(_target, _availability) __attribute__((availability(_target,_availability)))
217 #define __OS_AVAILABILITY_MSG(_target, _availability, _msg) __attribute__((availability(_target,_availability)))
218 #else
219 #define __OS_AVAILABILITY(_target, _availability)
220 #define __OS_AVAILABILITY_MSG(_target, _availability, _msg)
221 #endif
222#else
223 #define __OS_AVAILABILITY(_target, _availability)
224 #define __OS_AVAILABILITY_MSG(_target, _availability, _msg)
225#endif
226
227
228/* for use to document app extension usage */
229#if defined(__has_feature)
230 #if __has_feature(attribute_availability_app_extension)
231 #define __OSX_EXTENSION_UNAVAILABLE(_msg) __OS_AVAILABILITY_MSG(macosx_app_extension,unavailable,_msg)
232 #define __IOS_EXTENSION_UNAVAILABLE(_msg) __OS_AVAILABILITY_MSG(ios_app_extension,unavailable,_msg)
233 #else
234 #define __OSX_EXTENSION_UNAVAILABLE(_msg)
235 #define __IOS_EXTENSION_UNAVAILABLE(_msg)
236 #endif
237#else
238 #define __OSX_EXTENSION_UNAVAILABLE(_msg)
239 #define __IOS_EXTENSION_UNAVAILABLE(_msg)
240#endif
241
242#define __OS_EXTENSION_UNAVAILABLE(_msg) __OSX_EXTENSION_UNAVAILABLE(_msg) __IOS_EXTENSION_UNAVAILABLE(_msg)
243
244
245
246/* for use marking APIs available info for Mac OSX */
247#if defined(__has_attribute)
248 #if __has_attribute(availability)
249 #define __OSX_UNAVAILABLE __OS_AVAILABILITY(macosx,unavailable)
250 #define __OSX_AVAILABLE(_vers) __OS_AVAILABILITY(macosx,introduced=_vers)
251 #define __OSX_DEPRECATED(_start, _dep, _msg) __OSX_AVAILABLE(_start) __OS_AVAILABILITY_MSG(macosx,deprecated=_dep,_msg)
252 #endif
253#endif
254
255#ifndef __OSX_UNAVAILABLE
256 #define __OSX_UNAVAILABLE
257#endif
258
259#ifndef __OSX_AVAILABLE
260 #define __OSX_AVAILABLE(_vers)
261#endif
262
263#ifndef __OSX_DEPRECATED
264 #define __OSX_DEPRECATED(_start, _dep, _msg)
265#endif
266
267
268/* for use marking APIs available info for iOS */
269#if defined(__has_attribute)
270 #if __has_attribute(availability)
271 #define __IOS_UNAVAILABLE __OS_AVAILABILITY(ios,unavailable)
272 #define __IOS_PROHIBITED __OS_AVAILABILITY(ios,unavailable)
273 #define __IOS_AVAILABLE(_vers) __OS_AVAILABILITY(ios,introduced=_vers)
274 #define __IOS_DEPRECATED(_start, _dep, _msg) __IOS_AVAILABLE(_start) __OS_AVAILABILITY_MSG(ios,deprecated=_dep,_msg)
275 #endif
276#endif
277
278#ifndef __IOS_UNAVAILABLE
279 #define __IOS_UNAVAILABLE
280#endif
281
282#ifndef __IOS_PROHIBITED
283 #define __IOS_PROHIBITED
284#endif
285
286#ifndef __IOS_AVAILABLE
287 #define __IOS_AVAILABLE(_vers)
288#endif
289
290#ifndef __IOS_DEPRECATED
291 #define __IOS_DEPRECATED(_start, _dep, _msg)
292#endif
293
294
295/* for use marking APIs available info for tvOS */
296#if defined(__has_feature)
297 #if __has_feature(attribute_availability_tvos)
298 #define __TVOS_UNAVAILABLE __OS_AVAILABILITY(tvos,unavailable)
299 #define __TVOS_PROHIBITED __OS_AVAILABILITY(tvos,unavailable)
300 #define __TVOS_AVAILABLE(_vers) __OS_AVAILABILITY(tvos,introduced=_vers)
301 #define __TVOS_DEPRECATED(_start, _dep, _msg) __TVOS_AVAILABLE(_start) __OS_AVAILABILITY_MSG(tvos,deprecated=_dep,_msg)
302 #endif
303#endif
304
305#ifndef __TVOS_UNAVAILABLE
306 #define __TVOS_UNAVAILABLE
307#endif
308
309#ifndef __TVOS_PROHIBITED
310 #define __TVOS_PROHIBITED
311#endif
312
313#ifndef __TVOS_AVAILABLE
314 #define __TVOS_AVAILABLE(_vers)
315#endif
316
317#ifndef __TVOS_DEPRECATED
318 #define __TVOS_DEPRECATED(_start, _dep, _msg)
319#endif
320
321
322/* for use marking APIs available info for Watch OS */
323#if defined(__has_feature)
324 #if __has_feature(attribute_availability_watchos)
325 #define __WATCHOS_UNAVAILABLE __OS_AVAILABILITY(watchos,unavailable)
326 #define __WATCHOS_PROHIBITED __OS_AVAILABILITY(watchos,unavailable)
327 #define __WATCHOS_AVAILABLE(_vers) __OS_AVAILABILITY(watchos,introduced=_vers)
328 #define __WATCHOS_DEPRECATED(_start, _dep, _msg) __WATCHOS_AVAILABLE(_start) __OS_AVAILABILITY_MSG(watchos,deprecated=_dep,_msg)
329 #endif
330#endif
331
332#ifndef __WATCHOS_UNAVAILABLE
333 #define __WATCHOS_UNAVAILABLE
334#endif
335
336#ifndef __WATCHOS_PROHIBITED
337 #define __WATCHOS_PROHIBITED
338#endif
339
340#ifndef __WATCHOS_AVAILABLE
341 #define __WATCHOS_AVAILABLE(_vers)
342#endif
343
344#ifndef __WATCHOS_DEPRECATED
345 #define __WATCHOS_DEPRECATED(_start, _dep, _msg)
346#endif
347
348
349/* for use marking APIs unavailable for swift */
350#if defined(__has_feature)
351 #if __has_feature(attribute_availability_swift)
352 #define __SWIFT_UNAVAILABLE __OS_AVAILABILITY(swift,unavailable)
353 #define __SWIFT_UNAVAILABLE_MSG(_msg) __OS_AVAILABILITY_MSG(swift,unavailable,_msg)
354 #endif
355#endif
356
357#ifndef __SWIFT_UNAVAILABLE
358 #define __SWIFT_UNAVAILABLE
359#endif
360
361#ifndef __SWIFT_UNAVAILABLE_MSG
362 #define __SWIFT_UNAVAILABLE_MSG(_msg)
363#endif
364
365#if __has_include(<AvailabilityProhibitedInternal.h>)
366 #include <AvailabilityProhibitedInternal.h>
367#endif
368
369/*
370 Macros for defining which versions/platform a given symbol can be used.
371
372 @see http://clang.llvm.org/docs/AttributeReference.html#availability
373 */
374
375/*
376 * API Introductions
377 *
378 * Use to specify the release that a particular API became available.
379 *
380 * Platform names:
381 * macos, ios, tvos, watchos
382 *
383 * Examples:
384 * __API_AVAILABLE(macos(10.10))
385 * __API_AVAILABLE(macos(10.9), ios(10.0))
386 * __API_AVAILABLE(macos(10.4), ios(8.0), watchos(2.0), tvos(10.0))
387 */
388#define __API_AVAILABLE(...) __API_AVAILABLE_GET_MACRO(__VA_ARGS__,__API_AVAILABLE4, __API_AVAILABLE3, __API_AVAILABLE2, __API_AVAILABLE1)(__VA_ARGS__)
389
390
391/*
392 * API Deprecations
393 *
394 * Use to specify the release that a particular API became unavailable.
395 *
396 * Platform names:
397 * macos, ios, tvos, watchos
398 *
399 * Examples:
400 *
401 * __API_DEPRECATED("No longer supported", macos(10.4, 10.8))
402 * __API_DEPRECATED("No longer supported", macos(10.4, 10.8), ios(2.0, 3.0), watchos(2.0, 3.0), tvos(9.0, 10.0))
403 *
404 * __API_DEPRECATED_WITH_REPLACEMENT("-setName:", tvos(10.0, 10.4), ios(9.0, 10.0))
405 * __API_DEPRECATED_WITH_REPLACEMENT("SomeClassName", macos(10.4, 10.6), watchos(2.0, 3.0))
406 */
407#define __API_DEPRECATED(...) __API_DEPRECATED_MSG_GET_MACRO(__VA_ARGS__,__API_DEPRECATED_MSG5,__API_DEPRECATED_MSG4,__API_DEPRECATED_MSG3,__API_DEPRECATED_MSG2,__API_DEPRECATED_MSG1)(__VA_ARGS__)
408#define __API_DEPRECATED_WITH_REPLACEMENT(...) __API_DEPRECATED_REP_GET_MACRO(__VA_ARGS__,__API_DEPRECATED_REP5,__API_DEPRECATED_REP4,__API_DEPRECATED_REP3,__API_DEPRECATED_REP2,__API_DEPRECATED_REP1)(__VA_ARGS__)
409
410/*
411 * API Unavailability
412 * Use to specify that an API is unavailable for a particular platform.
413 *
414 * Example:
415 * __API_UNAVAILABLE(macos)
416 * __API_UNAVAILABLE(watchos, tvos)
417 */
418#define __API_UNAVAILABLE(...) __API_UNAVAILABLE_GET_MACRO(__VA_ARGS__,__API_UNAVAILABLE3,__API_UNAVAILABLE2,__API_UNAVAILABLE1)(__VA_ARGS__)
419
420#endif /* __AVAILABILITY__ */
421