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 | |