[apple/xnu.git] / EXTERNAL_HEADERS / Availability.h

/*
 * Copyright (c) 2007-2010 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 the iPhone OS X each have different version numbers.
    The __OSX_AVAILABLE_STARTING() macro allows you to specify both the desktop
    and phone OS 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 OS X 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 the iPhone 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 -miphone-version-min=1.x.x
    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=10xx for
    Mac OS X and __IPHONE_OS_VERSION_MAX_ALLOWED = 1xxx for iPhone.  
    
    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_NA        9999   /* not available */

#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_NA      99999  /* not available */

#include <AvailabilityInternal.h>


#ifdef __IPHONE_OS_VERSION_MIN_REQUIRED
    #define __OSX_AVAILABLE_STARTING(_mac, _iphone) __AVAILABILITY_INTERNAL##_iphone
    #define __OSX_AVAILABLE_BUT_DEPRECATED(_macIntro, _macDep, _iphoneIntro, _iphoneDep) \
                                                    __AVAILABILITY_INTERNAL##_iphoneIntro##_DEP##_iphoneDep

#elif defined(__MAC_OS_X_VERSION_MIN_REQUIRED)
    #define __OSX_AVAILABLE_STARTING(_mac, _iphone) __AVAILABILITY_INTERNAL##_mac
    #define __OSX_AVAILABLE_BUT_DEPRECATED(_macIntro, _macDep, _iphoneIntro, _iphoneDep) \
                                                    __AVAILABILITY_INTERNAL##_macIntro##_DEP##_macDep

#else
    #define __OSX_AVAILABLE_STARTING(_mac, _iphone)
    #define __OSX_AVAILABLE_BUT_DEPRECATED(_macIntro, _macDep, _iphoneIntro, _iphoneDep) 
#endif


#endif /* __AVAILABILITY__ */
Commit	Line	Data
6d2010ae A	1	/*
	2	* Copyright (c) 2007-2010 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 the iPhone OS X each have different version numbers.
	33	The __OSX_AVAILABLE_STARTING() macro allows you to specify both the desktop
	34	and phone OS 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 OS X 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 the iPhone 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 -miphone-version-min=1.x.x
	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=10xx for
	61	Mac OS X and __IPHONE_OS_VERSION_MAX_ALLOWED = 1xxx for iPhone.
	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_NA 9999 /* not available */
128
129	#define __IPHONE_2_0 20000
130	#define __IPHONE_2_1 20100
131	#define __IPHONE_2_2 20200
132	#define __IPHONE_3_0 30000
133	#define __IPHONE_3_1 30100
134	#define __IPHONE_3_2 30200
135	#define __IPHONE_NA 99999 /* not available */
136
137	#include <AvailabilityInternal.h>
138
139
140	#ifdef __IPHONE_OS_VERSION_MIN_REQUIRED
141	#define __OSX_AVAILABLE_STARTING(_mac, _iphone) __AVAILABILITY_INTERNAL##_iphone
142	#define __OSX_AVAILABLE_BUT_DEPRECATED(_macIntro, _macDep, _iphoneIntro, _iphoneDep) \
143	__AVAILABILITY_INTERNAL##_iphoneIntro##_DEP##_iphoneDep
144
145	#elif defined(__MAC_OS_X_VERSION_MIN_REQUIRED)
146	#define __OSX_AVAILABLE_STARTING(_mac, _iphone) __AVAILABILITY_INTERNAL##_mac
147	#define __OSX_AVAILABLE_BUT_DEPRECATED(_macIntro, _macDep, _iphoneIntro, _iphoneDep) \
148	__AVAILABILITY_INTERNAL##_macIntro##_DEP##_macDep
149
150	#else
151	#define __OSX_AVAILABLE_STARTING(_mac, _iphone)
152	#define __OSX_AVAILABLE_BUT_DEPRECATED(_macIntro, _macDep, _iphoneIntro, _iphoneDep)
153	#endif
154
155
156	#endif /* __AVAILABILITY__ */