trunk/include/Availability.h

/* $MidnightBSD$ */
/*
 * Copyright (c) 2007-2011 by Apple Inc.. All rights reserved.
 *
 * @APPLE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */
 
#ifndef __AVAILABILITY__
#define __AVAILABILITY__
 /*     
    These macros are for use in OS header files. They enable function prototypes
    and Objective-C methods to be tagged with the OS version in which they
    were first available; and, if applicable, the OS version in which they 
    became deprecated.  
     
    The desktop Mac OS X and iOS each have different version numbers.
    The __OSX_AVAILABLE_STARTING() macro allows you to specify both the desktop
    and iOS version numbers.  For instance:
        __OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0)
    means the function/method was first available on Mac OS X 10.2 on the desktop
    and first available in iOS 2.0 on the iPhone.
    
    If a function is available on one platform, but not the other a _NA (not
    applicable) parameter is used.  For instance:
            __OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_NA)
    means that the function/method was first available on Mac OS X 10.3, and it
    currently not implemented on the iPhone.

    At some point, a function/method may be deprecated.  That means Apple
    recommends applications stop using the function, either because there is a 
    better replacement or the functionality is being phased out.  Deprecated
    functions/methods can be tagged with a __OSX_AVAILABLE_BUT_DEPRECATED()
    macro which specifies the OS version where the function became available
    as well as the OS version in which it became deprecated.  For instance:
        __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_0,__MAC_10_5,__IPHONE_NA,__IPHONE_NA)
    means that the function/method was introduced in Mac OS X 10.0, then
    became deprecated beginning in Mac OS X 10.5.  On iOS the function 
    has never been available.  
    
    For these macros to function properly, a program must specify the OS version range 
    it is targeting.  The min OS version is specified as an option to the compiler:
    -mmacosx-version-min=10.x when building for Mac OS X, and -miphoneos-version-min=y.z
    when building for the iPhone.  The upper bound for the OS version is rarely needed,
    but it can be set on the command line via: -D__MAC_OS_X_VERSION_MAX_ALLOWED=10x0 for
    Mac OS X and __IPHONE_OS_VERSION_MAX_ALLOWED = y0z00 for iOS.  
    
    Examples:

        A function available in Mac OS X 10.5 and later, but not on the phone:
        
            extern void mymacfunc() __OSX_AVAILABLE_STARTING(__MAC_10_5,__IPHONE_NA);


        An Objective-C method in Mac OS X 10.5 and later, but not on the phone:
        
            @interface MyClass : NSObject
            -(void) mymacmethod __OSX_AVAILABLE_STARTING(__MAC_10_5,__IPHONE_NA);
            @end

        
        An enum available on the phone, but not available on Mac OS X:
        
            #if __IPHONE_OS_VERSION_MIN_REQUIRED
                enum { myEnum = 1 };
            #endif
           Note: this works when targeting the Mac OS X platform because 
           __IPHONE_OS_VERSION_MIN_REQUIRED is undefined which evaluates to zero. 
        

        An enum with values added in different iPhoneOS versions:
                
                        enum {
                            myX  = 1,   // Usable on iPhoneOS 2.1 and later
                            myY  = 2,   // Usable on iPhoneOS 3.0 and later
                            myZ  = 3,   // Usable on iPhoneOS 3.0 and later
                                ...
                      Note: you do not want to use #if with enumeration values
                          when a client needs to see all values at compile time
                          and use runtime logic to only use the viable values.
                          

    It is also possible to use the *_VERSION_MIN_REQUIRED in source code to make one
    source base that can be compiled to target a range of OS versions.  It is best
    to not use the _MAC_* and __IPHONE_* macros for comparisons, but rather their values.
    That is because you might get compiled on an old OS that does not define a later
    OS version macro, and in the C preprocessor undefined values evaluate to zero
    in expresssions, which could cause the #if expression to evaluate in an unexpected
    way.
    
        #ifdef __MAC_OS_X_VERSION_MIN_REQUIRED
            // code only compiled when targeting Mac OS X and not iPhone
            // note use of 1050 instead of __MAC_10_5
            #if __MAC_OS_X_VERSION_MIN_REQUIRED < 1050
                // code in here might run on pre-Leopard OS
            #else
                // code here can assume Leopard or later
            #endif
        #endif


*/

#define __MAC_10_0            1000
#define __MAC_10_1            1010
#define __MAC_10_2            1020
#define __MAC_10_3            1030
#define __MAC_10_4            1040
#define __MAC_10_5            1050
#define __MAC_10_6            1060
#define __MAC_10_7            1070
#define __MAC_10_8            1080
#define __MAC_10_9            1090
#define __MAC_10_10         101000
/* __MAC_NA is not defined to a value but is uses as a token by macros to indicate that the API is unavailable */

#define __IPHONE_2_0         20000
#define __IPHONE_2_1         20100
#define __IPHONE_2_2         20200
#define __IPHONE_3_0         30000
#define __IPHONE_3_1         30100
#define __IPHONE_3_2         30200
#define __IPHONE_4_0         40000
#define __IPHONE_4_1         40100
#define __IPHONE_4_2         40200
#define __IPHONE_4_3         40300
#define __IPHONE_5_0         50000
#define __IPHONE_5_1         50100
#define __IPHONE_6_0         60000
#define __IPHONE_6_1         60100
#define __IPHONE_7_0         70000
#define __IPHONE_7_1         70100
#define __IPHONE_8_0         80000
/* __IPHONE_NA is not defined to a value but is uses as a token by macros to indicate that the API is unavailable */

#include <AvailabilityInternal.h>


#ifdef __IPHONE_OS_VERSION_MIN_REQUIRED
    #define __OSX_AVAILABLE_STARTING(_osx, _ios) __AVAILABILITY_INTERNAL##_ios
    #define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep) \
                                                    __AVAILABILITY_INTERNAL##_iosIntro##_DEP##_iosDep
    #define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg) \
                                                    __AVAILABILITY_INTERNAL##_iosIntro##_DEP##_iosDep##_MSG(_msg)

#elif defined(__MAC_OS_X_VERSION_MIN_REQUIRED)
    #define __OSX_AVAILABLE_STARTING(_osx, _ios) __AVAILABILITY_INTERNAL##_osx
    #define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep) \
                                                    __AVAILABILITY_INTERNAL##_osxIntro##_DEP##_osxDep
    #define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg) \
                                                    __AVAILABILITY_INTERNAL##_osxIntro##_DEP##_osxDep##_MSG(_msg)

#else
    #define __OSX_AVAILABLE_STARTING(_osx, _ios)
    #define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep)
    #define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg)
#endif


#endif /* __AVAILABILITY__ */
Revision:	10989
Committed:	Fri Jun 15 20:38:07 2018 UTC (5 years, 10 months ago) by laffer1
Content type:	text/plain
File size:	7970 byte(s)
Log Message:	tag
#	Content
1	/* $MidnightBSD$ */
2	/*
3	* Copyright (c) 2007-2011 by Apple Inc.. All rights reserved.
4	*
5	* @APPLE_LICENSE_HEADER_START@
6	*
7	* This file contains Original Code and/or Modifications of Original Code
8	* as defined in and that are subject to the Apple Public Source License
9	* Version 2.0 (the 'License'). You may not use this file except in
10	* compliance with the License. Please obtain a copy of the License at
11	* http://www.opensource.apple.com/apsl/ and read it before using this
12	* file.
13	*
14	* The Original Code and all software distributed under the License are
15	* distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
16	* EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
17	* INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
18	* FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
19	* Please see the License for the specific language governing rights and
20	* limitations under the License.
21	*
22	* @APPLE_LICENSE_HEADER_END@
23	*/
24
25	#ifndef __AVAILABILITY__
26	#define __AVAILABILITY__
27	/*
28	These macros are for use in OS header files. They enable function prototypes
29	and Objective-C methods to be tagged with the OS version in which they
30	were first available; and, if applicable, the OS version in which they
31	became deprecated.
32
33	The desktop Mac OS X and iOS each have different version numbers.
34	The __OSX_AVAILABLE_STARTING() macro allows you to specify both the desktop
35	and iOS version numbers. For instance:
36	__OSX_AVAILABLE_STARTING(__MAC_10_2,__IPHONE_2_0)
37	means the function/method was first available on Mac OS X 10.2 on the desktop
38	and first available in iOS 2.0 on the iPhone.
39
40	If a function is available on one platform, but not the other a _NA (not
41	applicable) parameter is used. For instance:
42	__OSX_AVAILABLE_STARTING(__MAC_10_3,__IPHONE_NA)
43	means that the function/method was first available on Mac OS X 10.3, and it
44	currently not implemented on the iPhone.
45
46	At some point, a function/method may be deprecated. That means Apple
47	recommends applications stop using the function, either because there is a
48	better replacement or the functionality is being phased out. Deprecated
49	functions/methods can be tagged with a __OSX_AVAILABLE_BUT_DEPRECATED()
50	macro which specifies the OS version where the function became available
51	as well as the OS version in which it became deprecated. For instance:
52	__OSX_AVAILABLE_BUT_DEPRECATED(__MAC_10_0,__MAC_10_5,__IPHONE_NA,__IPHONE_NA)
53	means that the function/method was introduced in Mac OS X 10.0, then
54	became deprecated beginning in Mac OS X 10.5. On iOS the function
55	has never been available.
56
57	For these macros to function properly, a program must specify the OS version range
58	it is targeting. The min OS version is specified as an option to the compiler:
59	-mmacosx-version-min=10.x when building for Mac OS X, and -miphoneos-version-min=y.z
60	when building for the iPhone. The upper bound for the OS version is rarely needed,
61	but it can be set on the command line via: -D__MAC_OS_X_VERSION_MAX_ALLOWED=10x0 for
62	Mac OS X and __IPHONE_OS_VERSION_MAX_ALLOWED = y0z00 for iOS.
63
64	Examples:
65
66	A function available in Mac OS X 10.5 and later, but not on the phone:
67
68	extern void mymacfunc() __OSX_AVAILABLE_STARTING(__MAC_10_5,__IPHONE_NA);
69
70
71	An Objective-C method in Mac OS X 10.5 and later, but not on the phone:
72
73	@interface MyClass : NSObject
74	-(void) mymacmethod __OSX_AVAILABLE_STARTING(__MAC_10_5,__IPHONE_NA);
75	@end
76
77
78	An enum available on the phone, but not available on Mac OS X:
79
80	#if __IPHONE_OS_VERSION_MIN_REQUIRED
81	enum { myEnum = 1 };
82	#endif
83	Note: this works when targeting the Mac OS X platform because
84	__IPHONE_OS_VERSION_MIN_REQUIRED is undefined which evaluates to zero.
85
86
87	An enum with values added in different iPhoneOS versions:
88
89	enum {
90	myX = 1, // Usable on iPhoneOS 2.1 and later
91	myY = 2, // Usable on iPhoneOS 3.0 and later
92	myZ = 3, // Usable on iPhoneOS 3.0 and later
93	...
94	Note: you do not want to use #if with enumeration values
95	when a client needs to see all values at compile time
96	and use runtime logic to only use the viable values.
97
98
99	It is also possible to use the *_VERSION_MIN_REQUIRED in source code to make one
100	source base that can be compiled to target a range of OS versions. It is best
101	to not use the _MAC_* and __IPHONE_* macros for comparisons, but rather their values.
102	That is because you might get compiled on an old OS that does not define a later
103	OS version macro, and in the C preprocessor undefined values evaluate to zero
104	in expresssions, which could cause the #if expression to evaluate in an unexpected
105	way.
106
107	#ifdef __MAC_OS_X_VERSION_MIN_REQUIRED
108	// code only compiled when targeting Mac OS X and not iPhone
109	// note use of 1050 instead of __MAC_10_5
110	#if __MAC_OS_X_VERSION_MIN_REQUIRED < 1050
111	// code in here might run on pre-Leopard OS
112	#else
113	// code here can assume Leopard or later
114	#endif
115	#endif
116
117
118	*/
119
120	#define __MAC_10_0 1000
121	#define __MAC_10_1 1010
122	#define __MAC_10_2 1020
123	#define __MAC_10_3 1030
124	#define __MAC_10_4 1040
125	#define __MAC_10_5 1050
126	#define __MAC_10_6 1060
127	#define __MAC_10_7 1070
128	#define __MAC_10_8 1080
129	#define __MAC_10_9 1090
130	#define __MAC_10_10 101000
131	/* __MAC_NA is not defined to a value but is uses as a token by macros to indicate that the API is unavailable */
132
133	#define __IPHONE_2_0 20000
134	#define __IPHONE_2_1 20100
135	#define __IPHONE_2_2 20200
136	#define __IPHONE_3_0 30000
137	#define __IPHONE_3_1 30100
138	#define __IPHONE_3_2 30200
139	#define __IPHONE_4_0 40000
140	#define __IPHONE_4_1 40100
141	#define __IPHONE_4_2 40200
142	#define __IPHONE_4_3 40300
143	#define __IPHONE_5_0 50000
144	#define __IPHONE_5_1 50100
145	#define __IPHONE_6_0 60000
146	#define __IPHONE_6_1 60100
147	#define __IPHONE_7_0 70000
148	#define __IPHONE_7_1 70100
149	#define __IPHONE_8_0 80000
150	/* __IPHONE_NA is not defined to a value but is uses as a token by macros to indicate that the API is unavailable */
151
152	#include <AvailabilityInternal.h>
153
154
155	#ifdef __IPHONE_OS_VERSION_MIN_REQUIRED
156	#define __OSX_AVAILABLE_STARTING(_osx, _ios) __AVAILABILITY_INTERNAL##_ios
157	#define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep) \
158	__AVAILABILITY_INTERNAL##_iosIntro##_DEP##_iosDep
159	#define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg) \
160	__AVAILABILITY_INTERNAL##_iosIntro##_DEP##_iosDep##_MSG(_msg)
161
162	#elif defined(__MAC_OS_X_VERSION_MIN_REQUIRED)
163	#define __OSX_AVAILABLE_STARTING(_osx, _ios) __AVAILABILITY_INTERNAL##_osx
164	#define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep) \
165	__AVAILABILITY_INTERNAL##_osxIntro##_DEP##_osxDep
166	#define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg) \
167	__AVAILABILITY_INTERNAL##_osxIntro##_DEP##_osxDep##_MSG(_msg)
168
169	#else
170	#define __OSX_AVAILABLE_STARTING(_osx, _ios)
171	#define __OSX_AVAILABLE_BUT_DEPRECATED(_osxIntro, _osxDep, _iosIntro, _iosDep)
172	#define __OSX_AVAILABLE_BUT_DEPRECATED_MSG(_osxIntro, _osxDep, _iosIntro, _iosDep, _msg)
173	#endif
174
175
176	#endif /* __AVAILABILITY__ */
Name	Value
svn:eol-style	native
svn:keywords	MidnightBSD=%H
svn:mime-type	text/plain