EXTERNAL_HEADERS/Availability.h

   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 #define __MAC_NA        9999   /* not available */
 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 #define __IPHONE_NA      99999  /* not available */
 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__ */