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-2011 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: /* __MAC_NA is not defined to a value but is uses as a token by macros to indicate that the API is unavailable */ 130: 131: #define __IPHONE_2_0 20000 132: #define __IPHONE_2_1 20100 133: #define __IPHONE_2_2 20200 134: #define __IPHONE_3_0 30000 135: #define __IPHONE_3_1 30100 136: #define __IPHONE_3_2 30200 137: #define __IPHONE_4_0 40000 138: #define __IPHONE_4_1 40100 139: #define __IPHONE_4_2 40200 140: #define __IPHONE_4_3 40300 141: #define __IPHONE_5_0 50000 142: #define __IPHONE_5_1 50100 143: #define __IPHONE_6_0 60000 144: #define __IPHONE_6_1 60100 145: #define __IPHONE_7_0 70000 146: /* __IPHONE_NA is not defined to a value but is uses as a token by macros to indicate that the API is unavailable */ 147: 148: #include <AvailabilityInternal.h> 149: 150: 151: #ifdef __IPHONE_OS_VERSION_MIN_REQUIRED 152: #define __OSX_AVAILABLE_STARTING(_osx, _ios) __AVAILABILITY_INTERNAL##_ios 153: #define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep) \ 154: __AVAILABILITY_INTERNAL##_iosIntro##_DEP##_iosDep 155: #define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg) \ 156: __AVAILABILITY_INTERNAL##_iosIntro##_DEP##_iosDep##_MSG(_msg) 157: 158: #elif defined(__MAC_OS_X_VERSION_MIN_REQUIRED) 159: #define __OSX_AVAILABLE_STARTING(_osx, _ios) __AVAILABILITY_INTERNAL##_osx 160: #define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep) \ 161: __AVAILABILITY_INTERNAL##_osxIntro##_DEP##_osxDep 162: #define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg) \ 163: __AVAILABILITY_INTERNAL##_osxIntro##_DEP##_osxDep##_MSG(_msg) 164: 165: #else 166: #define __OSX_AVAILABLE_STARTING(_osx, _ios) 167: #define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep) 168: #define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg) 169: #endif 170: 171: 172: #endif /* __AVAILABILITY__ */ 173: