EXTERNAL_HEADERS/Availability.h

   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__ */