Green shading in the line number column means the source is part of the translation unit, red means it is conditionally excluded. Highlighted line numbers link to the translation unit page. Highlighted macros link to the macro page.
1: /* 2: * Copyright (c) 2007-2015 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: /* __MAC_NA is not defined to a value but is uses as a token by macros to indicate that the API is unavailable */ 137: 138: #define __IPHONE_2_0 20000 139: #define __IPHONE_2_1 20100 140: #define __IPHONE_2_2 20200 141: #define __IPHONE_3_0 30000 142: #define __IPHONE_3_1 30100 143: #define __IPHONE_3_2 30200 144: #define __IPHONE_4_0 40000 145: #define __IPHONE_4_1 40100 146: #define __IPHONE_4_2 40200 147: #define __IPHONE_4_3 40300 148: #define __IPHONE_5_0 50000 149: #define __IPHONE_5_1 50100 150: #define __IPHONE_6_0 60000 151: #define __IPHONE_6_1 60100 152: #define __IPHONE_7_0 70000 153: #define __IPHONE_7_1 70100 154: #define __IPHONE_8_0 80000 155: #define __IPHONE_8_1 80100 156: #define __IPHONE_8_2 80200 157: #define __IPHONE_8_3 80300 158: #define __IPHONE_8_4 80400 159: #define __IPHONE_9_0 90000 160: #define __IPHONE_9_1 90100 161: #define __IPHONE_9_2 90200 162: #define __IPHONE_9_3 90300 163: /* __IPHONE_NA is not defined to a value but is uses as a token by macros to indicate that the API is unavailable */ 164: 165: #define __TVOS_9_0 90000 166: #define __TVOS_9_1 90100 167: #define __TVOS_9_2 90200 168: 169: #define __WATCHOS_1_0 10000 170: #define __WATCHOS_2_0 20000 171: 172: #include <AvailabilityInternal.h> 173: 174: #ifdef __IPHONE_OS_VERSION_MIN_REQUIRED 175: #define __OSX_AVAILABLE_STARTING(_osx, _ios) __AVAILABILITY_INTERNAL##_ios 176: #define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep) \ 177: __AVAILABILITY_INTERNAL##_iosIntro##_DEP##_iosDep 178: #define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg) \ 179: __AVAILABILITY_INTERNAL##_iosIntro##_DEP##_iosDep##_MSG(_msg) 180: 181: #elif defined(__MAC_OS_X_VERSION_MIN_REQUIRED) 182: #define __OSX_AVAILABLE_STARTING(_osx, _ios) __AVAILABILITY_INTERNAL##_osx 183: #define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep) \ 184: __AVAILABILITY_INTERNAL##_osxIntro##_DEP##_osxDep 185: #define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg) \ 186: __AVAILABILITY_INTERNAL##_osxIntro##_DEP##_osxDep##_MSG(_msg) 187: 188: #else 189: #define __OSX_AVAILABLE_STARTING(_osx, _ios) 190: #define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep) 191: #define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg) 192: #endif 193: 194: 195: #if defined(__has_feature) 196: #if __has_feature(attribute_availability_with_message) 197: #define __OS_AVAILABILITY(_target, _availability) __attribute__((availability(_target,_availability))) 198: #define __OS_AVAILABILITY_MSG(_target, _availability, _msg) __attribute__((availability(_target,_availability,message=_msg))) 199: #else 200: #define __OS_AVAILABILITY(_target, _availability) 201: #define __OS_AVAILABILITY_MSG(_target, _availability, _msg) 202: #endif 203: #else 204: #define __OS_AVAILABILITY(_target, _availability) 205: #define __OS_AVAILABILITY_MSG(_target, _availability, _msg) 206: #endif 207: 208: 209: /* for use to document app extension usage */ 210: #if defined(__has_feature) 211: #if __has_feature(attribute_availability_app_extension) 212: #define __OSX_EXTENSION_UNAVAILABLE(_msg) __OS_AVAILABILITY_MSG(macosx_app_extension,unavailable,_msg) 213: #define __IOS_EXTENSION_UNAVAILABLE(_msg) __OS_AVAILABILITY_MSG(ios_app_extension,unavailable,_msg) 214: #else 215: #define __OSX_EXTENSION_UNAVAILABLE(_msg) 216: #define __IOS_EXTENSION_UNAVAILABLE(_msg) 217: #endif 218: #else 219: #define __OSX_EXTENSION_UNAVAILABLE(_msg) 220: #define __IOS_EXTENSION_UNAVAILABLE(_msg) 221: #endif 222: 223: #define __OS_EXTENSION_UNAVAILABLE(_msg) __OSX_EXTENSION_UNAVAILABLE(_msg) __IOS_EXTENSION_UNAVAILABLE(_msg) 224: 225: 226: 227: /* for use marking APIs available info for Mac OSX */ 228: #if defined(__has_attribute) 229: #if __has_attribute(availability) 230: #define __OSX_UNAVAILABLE __OS_AVAILABILITY(macosx,unavailable) 231: #define __OSX_AVAILABLE(_vers) __OS_AVAILABILITY(macosx,introduced=_vers) 232: #define __OSX_DEPRECATED(_start, _dep, _msg) __OSX_AVAILABLE(_start) __OS_AVAILABILITY_MSG(macosx,deprecated=_dep,_msg) 233: #endif 234: #endif 235: 236: #ifndef __OSX_UNAVAILABLE 237: #define __OSX_UNAVAILABLE 238: #endif 239: 240: #ifndef __OSX_AVAILABLE 241: #define __OSX_AVAILABLE(_vers) 242: #endif 243: 244: #ifndef __OSX_DEPRECATED 245: #define __OSX_DEPRECATED(_start, _dep, _msg) 246: #endif 247: 248: 249: /* for use marking APIs available info for iOS */ 250: #if defined(__has_attribute) 251: #if __has_attribute(availability) 252: #define __IOS_UNAVAILABLE __OS_AVAILABILITY(ios,unavailable) 253: #define __IOS_PROHIBITED __OS_AVAILABILITY(ios,unavailable) 254: #define __IOS_AVAILABLE(_vers) __OS_AVAILABILITY(ios,introduced=_vers) 255: #define __IOS_DEPRECATED(_start, _dep, _msg) __IOS_AVAILABLE(_start) __OS_AVAILABILITY_MSG(ios,deprecated=_dep,_msg) 256: #endif 257: #endif 258: 259: #ifndef __IOS_UNAVAILABLE 260: #define __IOS_UNAVAILABLE 261: #endif 262: 263: #ifndef __IOS_PROHIBITED 264: #define __IOS_PROHIBITED 265: #endif 266: 267: #ifndef __IOS_AVAILABLE 268: #define __IOS_AVAILABLE(_vers) 269: #endif 270: 271: #ifndef __IOS_DEPRECATED 272: #define __IOS_DEPRECATED(_start, _dep, _msg) 273: #endif 274: 275: 276: /* for use marking APIs available info for tvOS */ 277: #if defined(__has_feature) 278: #if __has_feature(attribute_availability_tvos) 279: #define __TVOS_UNAVAILABLE __OS_AVAILABILITY(tvos,unavailable) 280: #define __TVOS_PROHIBITED __OS_AVAILABILITY(tvos,unavailable) 281: #define __TVOS_AVAILABLE(_vers) __OS_AVAILABILITY(tvos,introduced=_vers) 282: #define __TVOS_DEPRECATED(_start, _dep, _msg) __TVOS_AVAILABLE(_start) __OS_AVAILABILITY_MSG(tvos,deprecated=_dep,_msg) 283: #endif 284: #endif 285: 286: #ifndef __TVOS_UNAVAILABLE 287: #define __TVOS_UNAVAILABLE 288: #endif 289: 290: #ifndef __TVOS_PROHIBITED 291: #define __TVOS_PROHIBITED 292: #endif 293: 294: #ifndef __TVOS_AVAILABLE 295: #define __TVOS_AVAILABLE(_vers) 296: #endif 297: 298: #ifndef __TVOS_DEPRECATED 299: #define __TVOS_DEPRECATED(_start, _dep, _msg) 300: #endif 301: 302: 303: /* for use marking APIs available info for Watch OS */ 304: #if defined(__has_feature) 305: #if __has_feature(attribute_availability_watchos) 306: #define __WATCHOS_UNAVAILABLE __OS_AVAILABILITY(watchos,unavailable) 307: #define __WATCHOS_PROHIBITED __OS_AVAILABILITY(watchos,unavailable) 308: #define __WATCHOS_AVAILABLE(_vers) __OS_AVAILABILITY(watchos,introduced=_vers) 309: #define __WATCHOS_DEPRECATED(_start, _dep, _msg) __WATCHOS_AVAILABLE(_start) __OS_AVAILABILITY_MSG(watchos,deprecated=_dep,_msg) 310: #endif 311: #endif 312: 313: #ifndef __WATCHOS_UNAVAILABLE 314: #define __WATCHOS_UNAVAILABLE 315: #endif 316: 317: #ifndef __WATCHOS_PROHIBITED 318: #define __WATCHOS_PROHIBITED 319: #endif 320: 321: #ifndef __WATCHOS_AVAILABLE 322: #define __WATCHOS_AVAILABLE(_vers) 323: #endif 324: 325: #ifndef __WATCHOS_DEPRECATED 326: #define __WATCHOS_DEPRECATED(_start, _dep, _msg) 327: #endif 328: 329: 330: #endif /* __AVAILABILITY__ */ 331: