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