CFBase.h

/*
 * Copyright (c) 2008-2012 Brent Fulgham <bfulgham@gmail.org>. All rights reserved.
 * Copyright (c) 2009 Grant Erickson <gerickson@nuovations.com>. All rights reserved.
 *
 * This source code is a modified version of the CoreFoundation sources released by Apple Inc. under
 * the terms of the APSL version 2.0 (see below).
 *
 * For information about changes from the original Apple source release can be found by reviewing the
 * source control system for the project at https://sourceforge.net/svn/?group_id=246198.
 *
 * The original license information is as follows:
 * 
 * Copyright (c) 2012 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@
 */

/* CFBase.h
 Copyright (c) 1998-2011, Apple Inc. All rights reserved.
*/

#if !defined(__COREFOUNDATION_CFBASE__)
#define__COREFOUNDATION_CFBASE__ 1

#include<TargetConditionals.h>

#if (defined(__CYGWIN32__) || defined(_WIN32)) && !defined(__WIN32__)
#define__WIN32__ 1
#endif

#if defined(_MSC_VER) && defined(_M_IX86)
#define__i386__ 1
#endif

#if (defined(__i386__) || defined(__x86_64__)) && !defined(__LITTLE_ENDIAN__)
#define__LITTLE_ENDIAN__ 1
#endif

#if (defined(__arm__) && defined(__ARMEL__)) && !defined(__LITTLE_ENDIAN__)
#define__LITTLE_ENDIAN__ 1
#endif

#if !defined(__BIG_ENDIAN__) && !defined(__LITTLE_ENDIAN__)
#error Do not know the endianess of this architecture
#endif

#if !__BIG_ENDIAN__&& !__LITTLE_ENDIAN__
#error Both __BIG_ENDIAN__ and __LITTLE_ENDIAN__ cannot be false
#endif

#if__BIG_ENDIAN__&&__LITTLE_ENDIAN__
#error Both __BIG_ENDIAN__ and __LITTLE_ENDIAN__ cannot be true
#endif

// Some compilers provide the capability to test if certain features are available. This macro provides a compatibility path for other compilers.
#ifndef__has_feature
#define__has_feature(x) 0
#endif

#if defined(__GNUC__) ||TARGET_OS_WIN32
#include<stdint.h>
#include<stdbool.h>
#endif

#if__BLOCKS__
#include<Block.h>
#endif

// The arguments to these availability macros is a version number, e.g. 10_6, 3_0
#ifTARGET_OS_MAC&& !(TARGET_OS_EMBEDDED||TARGET_OS_IPHONE)
#include<AvailabilityMacros.h>
#include<Availability.h>

// Available on MacOS and iOS
#defineCF_AVAILABLE(_mac, _ios) AVAILABLE_MAC_OS_X_VERSION_##_mac##_AND_LATER

// Available on MacOS only
#defineCF_AVAILABLE_MAC(_mac) AVAILABLE_MAC_OS_X_VERSION_##_mac##_AND_LATER

// Available on iOS only
#defineCF_AVAILABLE_IOS(_ios) __OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_##_ios)

// Deprecated on either MacOS or iOS, or deprecated on both (check version numbers for details)
#defineCF_DEPRECATED(_macIntro, _macDep, _iosIntro, _iosDep) AVAILABLE_MAC_OS_X_VERSION_##_macIntro##_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_##_macDep

// Deprecated on MacOS, unavailable on iOS
#defineCF_DEPRECATED_MAC(_macIntro, _macDep) AVAILABLE_MAC_OS_X_VERSION_##_macIntro##_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_##_macDep

// Unavailable on MacOS, deprecated on iOS
#defineCF_DEPRECATED_IOS(_iosIntro, _iosDep) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_NA, __MAC_NA, __IPHONE_##_iosIntro, __IPHONE_##_iosDep)

#elif (TARGET_OS_EMBEDDED||TARGET_OS_IPHONE)
#include<AvailabilityMacros.h>
#include<Availability.h>

#defineCF_AVAILABLE(_mac, _ios) __OSX_AVAILABLE_STARTING(__MAC_##_mac, __IPHONE_##_ios)
#defineCF_AVAILABLE_MAC(_mac) __OSX_AVAILABLE_STARTING(__MAC_##_mac, __IPHONE_NA)
#defineCF_AVAILABLE_IOS(_ios) __OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_##_ios)
#defineCF_DEPRECATED(_macIntro, _macDep, _iosIntro, _iosDep) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_##_macIntro, __MAC_##_macDep, __IPHONE_##_iosIntro, __IPHONE_##_iosDep)
#defineCF_DEPRECATED_MAC(_macIntro, _macDep) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_##_macIntro, __MAC_##_macDep, __IPHONE_NA, __IPHONE_NA)
#defineCF_DEPRECATED_IOS(_iosIntro, _iosDep) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_NA, __MAC_NA, __IPHONE_##_iosIntro, __IPHONE_##_iosDep)

#else

#ifTARGET_OS_WIN32
#include<AvailabilityMacros.h>
#include<Availability.h>
#endif

#defineCF_AVAILABLE(_mac, _ios)
#defineCF_AVAILABLE_MAC(_mac)
#defineCF_AVAILABLE_IOS(_ios)
#defineCF_DEPRECATED(_macIntro, _macDep, _iosIntro, _iosDep)
#defineCF_DEPRECATED_MAC(_macIntro, _macDep)
#defineCF_DEPRECATED_IOS(_iosIntro, _iosDep)

#endif


// Older versions of these macro; use IOS versions instead
#defineCF_AVAILABLE_IPHONE(_ios) CF_AVAILABLE_IOS(_ios)
#defineCF_DEPRECATED_IPHONE(_iosIntro, _iosDep) CF_DEPRECATED_IOS(_iosIntro, _iosDep)

#if (TARGET_OS_MAC&& !(TARGET_OS_EMBEDDED||TARGET_OS_IPHONE)) || (TARGET_OS_EMBEDDED||TARGET_OS_IPHONE)
#include<libkern/OSTypes.h>
#endif

#if !defined(__MACTYPES__)
#if !defined(_OS_OSTYPES_H)
typedefunsigned charBoolean;
typedefunsigned charUInt8;
typedefsigned charSInt8;
typedefunsigned shortUInt16;
typedefsigned shortSInt16;
typedefunsigned intUInt32;
typedefsigned intSInt32;
typedefuint64_tUInt64;
typedefint64_tSInt64;
typedefSInt32OSStatus;
#endif
typedeffloatFloat32;
typedefdoubleFloat64;
typedefunsigned shortUniChar;
typedefunsigned longUniCharCount;
typedefunsigned char*StringPtr;
typedefconstunsigned char*ConstStringPtr;
typedefunsigned charStr255[256];
typedefconstunsigned char*ConstStr255Param;
typedefSInt16OSErr;
typedefSInt16RegionCode;
typedefSInt16LangCode;
typedefSInt16ScriptCode;
typedefUInt32FourCharCode;
typedefFourCharCodeOSType;
typedefUInt8Byte;
typedefSInt8SignedByte;
#endif
#if !defined(__MACTYPES__) || (defined(UNIVERSAL_INTERFACES_VERSION) &&UNIVERSAL_INTERFACES_VERSION<0x0340)
typedefUInt32UTF32Char;
typedefUInt16UTF16Char;
typedefUInt8UTF8Char;
#endif

#if !defined(CF_EXTERN_C_BEGIN)
#if defined(__cplusplus)
#defineCF_EXTERN_C_BEGIN extern "C" {
#defineCF_EXTERN_C_END }
#else
#defineCF_EXTERN_C_BEGIN
#defineCF_EXTERN_C_END
#endif
#endif

#ifTARGET_OS_WIN32

#if !defined(CF_EXPORT)
#if defined(CF_BUILDING_CF) && defined(__cplusplus)
#defineCF_EXPORT extern "C" __declspec(dllexport) 
#elif defined(CF_BUILDING_CF) && !defined(__cplusplus)
#defineCF_EXPORT extern __declspec(dllexport) 
#elif defined(__cplusplus)
#defineCF_EXPORT extern "C" __declspec(dllimport) 
#else
#defineCF_EXPORT extern __declspec(dllimport) 
#endif
#endif

#else
#defineCF_EXPORT extern
#endif

CF_EXTERN_C_BEGIN

#if !defined(NULL)
#if defined(__GNUG__)
#defineNULL __null
#elif defined(__cplusplus)
#defineNULL 0
#else
#defineNULL ((void *)0)
#endif
#endif

#if !defined(TRUE)
#defineTRUE 1
#endif

#if !defined(FALSE)
#defineFALSE 0
#endif

#if !defined(CF_INLINE)
#if defined(__GNUC__) && (__GNUC__==4) && !defined(DEBUG)
#defineCF_INLINE static __inline__ __attribute__((always_inline))
#elif defined(__GNUC__)
#defineCF_INLINE static __inline__
#elif defined(__MWERKS__) || defined(__cplusplus)
#defineCF_INLINE static inline
#elif defined(_MSC_VER)
#defineCF_INLINE static __inline
#elifTARGET_OS_WIN32
#defineCF_INLINE static __inline__
#endif
#endif

// Marks functions which return a CF type that needs to be released by the caller but whose names are not consistent with CoreFoundation naming rules. The recommended fix to this is to rename the functions, but this macro can be used to let the clang static analyzer know of any exceptions that cannot be fixed.
// This macro is ONLY to be used in exceptional circumstances, not to annotate functions which conform to the CoreFoundation naming rules.
#if__has_feature(attribute_cf_returns_retained)
#defineCF_RETURNS_RETAINED __attribute__((cf_returns_retained))
#else
#defineCF_RETURNS_RETAINED
#endif

// Marks functions which return a CF type that may need to be retained by the caller but whose names are not consistent with CoreFoundation naming rules. The recommended fix to this is to rename the functions, but this macro can be used to let the clang static analyzer know of any exceptions that cannot be fixed. 
// This macro is ONLY to be used in exceptional circumstances, not to annotate functions which conform to the CoreFoundation naming rules.
#if__has_feature(attribute_cf_returns_not_retained)
#defineCF_RETURNS_NOT_RETAINED __attribute__((cf_returns_not_retained))
#else
#defineCF_RETURNS_NOT_RETAINED
#endif

// Marks functions which cannot be used when compiling in automatic reference counting mode.
#if__has_feature(objc_arc)
#defineCF_AUTOMATED_REFCOUNT_UNAVAILABLE __attribute__((unavailable("not available in automatic reference counting mode")))
#else
#defineCF_AUTOMATED_REFCOUNT_UNAVAILABLE
#endif

CF_EXPORTdoublekCFCoreFoundationVersionNumber;

#ifTARGET_OS_MAC
#definekCFCoreFoundationVersionNumber10_0 196.40
#definekCFCoreFoundationVersionNumber10_0_3 196.50
#definekCFCoreFoundationVersionNumber10_1 226.00
#definekCFCoreFoundationVersionNumber10_1_1 226.00
/* Note the next three do not follow the usual numbering policy from the base release */
#definekCFCoreFoundationVersionNumber10_1_2 227.20
#definekCFCoreFoundationVersionNumber10_1_3 227.20
#definekCFCoreFoundationVersionNumber10_1_4 227.30
#definekCFCoreFoundationVersionNumber10_2 263.00
#definekCFCoreFoundationVersionNumber10_2_1 263.10
#definekCFCoreFoundationVersionNumber10_2_2 263.10
#definekCFCoreFoundationVersionNumber10_2_3 263.30
#definekCFCoreFoundationVersionNumber10_2_4 263.30
#definekCFCoreFoundationVersionNumber10_2_5 263.50
#definekCFCoreFoundationVersionNumber10_2_6 263.50
#definekCFCoreFoundationVersionNumber10_2_7 263.50
#definekCFCoreFoundationVersionNumber10_2_8 263.50
#definekCFCoreFoundationVersionNumber10_3 299.00
#definekCFCoreFoundationVersionNumber10_3_1 299.00
#definekCFCoreFoundationVersionNumber10_3_2 299.00
#definekCFCoreFoundationVersionNumber10_3_3 299.30
#definekCFCoreFoundationVersionNumber10_3_4 299.31
#definekCFCoreFoundationVersionNumber10_3_5 299.31
#definekCFCoreFoundationVersionNumber10_3_6 299.32
#definekCFCoreFoundationVersionNumber10_3_7 299.33
#definekCFCoreFoundationVersionNumber10_3_8 299.33
#definekCFCoreFoundationVersionNumber10_3_9 299.35
#definekCFCoreFoundationVersionNumber10_4 368.00
#definekCFCoreFoundationVersionNumber10_4_1 368.10
#definekCFCoreFoundationVersionNumber10_4_2 368.11
#definekCFCoreFoundationVersionNumber10_4_3 368.18
#definekCFCoreFoundationVersionNumber10_4_4_Intel 368.26
#definekCFCoreFoundationVersionNumber10_4_4_PowerPC 368.25
#definekCFCoreFoundationVersionNumber10_4_5_Intel 368.26
#definekCFCoreFoundationVersionNumber10_4_5_PowerPC 368.25
#definekCFCoreFoundationVersionNumber10_4_6_Intel 368.26
#definekCFCoreFoundationVersionNumber10_4_6_PowerPC 368.25
#definekCFCoreFoundationVersionNumber10_4_7 368.27
#definekCFCoreFoundationVersionNumber10_4_8 368.27
#definekCFCoreFoundationVersionNumber10_4_9 368.28
#definekCFCoreFoundationVersionNumber10_4_10 368.28
#definekCFCoreFoundationVersionNumber10_4_11 368.31
#definekCFCoreFoundationVersionNumber10_5 476.00
#definekCFCoreFoundationVersionNumber10_5_1 476.00
#definekCFCoreFoundationVersionNumber10_5_2 476.10
#definekCFCoreFoundationVersionNumber10_5_3 476.13
#definekCFCoreFoundationVersionNumber10_5_4 476.14
#definekCFCoreFoundationVersionNumber10_5_5 476.15
#definekCFCoreFoundationVersionNumber10_5_6 476.17
#definekCFCoreFoundationVersionNumber10_5_7 476.18
#definekCFCoreFoundationVersionNumber10_5_8 476.19
#definekCFCoreFoundationVersionNumber10_6 550.00
#definekCFCoreFoundationVersionNumber10_6_1 550.00
#definekCFCoreFoundationVersionNumber10_6_2 550.13
#definekCFCoreFoundationVersionNumber10_6_3 550.19
#definekCFCoreFoundationVersionNumber10_6_4 550.29
#definekCFCoreFoundationVersionNumber10_6_5 550.42
#endif

#ifTARGET_OS_IPHONE
#definekCFCoreFoundationVersionNumber_iPhoneOS_2_0 478.23
#definekCFCoreFoundationVersionNumber_iPhoneOS_2_1 478.26
#definekCFCoreFoundationVersionNumber_iPhoneOS_2_2 478.29
#definekCFCoreFoundationVersionNumber_iPhoneOS_3_0 478.47
#definekCFCoreFoundationVersionNumber_iPhoneOS_3_1 478.52
#definekCFCoreFoundationVersionNumber_iPhoneOS_3_2 478.61
#definekCFCoreFoundationVersionNumber_iOS_4_0 550.32
#definekCFCoreFoundationVersionNumber_iOS_4_1 550.38
#definekCFCoreFoundationVersionNumber_iOS_4_2 550.52
#endif

typedefunsigned longCFTypeID;
typedefunsigned longCFOptionFlags;
typedefunsigned longCFHashCode;
typedefsigned longCFIndex;

/* Base "type" of all "CF objects", and polymorphic functions on them */
typedefconstvoid*CFTypeRef;

typedefconststruct__CFString*CFStringRef;
typedefstruct__CFString*CFMutableStringRef;

/*
 Type to mean any instance of a property list type;
 currently, CFString, CFData, CFNumber, CFBoolean, CFDate,
 CFArray, and CFDictionary.
*/
typedefCFTypeRefCFPropertyListRef;

/* Values returned from comparison functions */
enum {
kCFCompareLessThan=-1,
kCFCompareEqualTo=0,
kCFCompareGreaterThan=1
};
typedefCFIndexCFComparisonResult;

/* A standard comparison function */
typedefCFComparisonResult (*CFComparatorFunction)(constvoid*val1, constvoid*val2, void*context);

/* Constant used by some functions to indicate failed searches. */
/* This is of type CFIndex. */
enum {
kCFNotFound=-1
};


/* Range type */
typedefstruct {
CFIndexlocation;
CFIndexlength;
} CFRange;

#if defined(CF_INLINE)
CF_INLINECFRangeCFRangeMake(CFIndexloc, CFIndexlen) {
CFRangerange;
range.location=loc;
range.length=len;
returnrange;
}
#else
#defineCFRangeMake(LOC, LEN) __CFRangeMake(LOC, LEN)
#endif

/* Private; do not use */
CF_EXPORT
CFRange__CFRangeMake(CFIndexloc, CFIndexlen);


/* Null representant */

typedefconststruct__CFNull*CFNullRef;

CF_EXPORT
CFTypeIDCFNullGetTypeID(void);

CF_EXPORT
constCFNullRefkCFNull; // the singleton null instance


/* Allocator API

 Most of the time when specifying an allocator to Create functions, the NULL
 argument indicates "use the default"; this is the same as using kCFAllocatorDefault
 or the return value from CFAllocatorGetDefault(). This assures that you will use
 the allocator in effect at that time.

 You should rarely use kCFAllocatorSystemDefault, the default default allocator.
*/
typedefconststruct__CFAllocator*CFAllocatorRef;

/* This is a synonym for NULL, if you'd rather use a named constant. */
CF_EXPORT
constCFAllocatorRefkCFAllocatorDefault;

/* Default system allocator; you rarely need to use this. */
CF_EXPORT
constCFAllocatorRefkCFAllocatorSystemDefault;

/* This allocator uses malloc(), realloc(), and free(). This should not be
 generally used; stick to kCFAllocatorDefault whenever possible. This
 allocator is useful as the "bytesDeallocator" in CFData or
 "contentsDeallocator" in CFString where the memory was obtained as a
 result of malloc() type functions.
*/
CF_EXPORT
constCFAllocatorRefkCFAllocatorMalloc;

/* This allocator explicitly uses the default malloc zone, returned by
 malloc_default_zone(). It should only be used when an object is
 safe to be allocated in non-scanned memory.
 */
CF_EXPORT
constCFAllocatorRefkCFAllocatorMallocZone;

/* Null allocator which does nothing and allocates no memory. This allocator
 is useful as the "bytesDeallocator" in CFData or "contentsDeallocator"
 in CFString where the memory should not be freed. 
*/
CF_EXPORT
constCFAllocatorRefkCFAllocatorNull;

/* Special allocator argument to CFAllocatorCreate() which means
 "use the functions given in the context to allocate the allocator
 itself as well". 
*/
CF_EXPORT
constCFAllocatorRefkCFAllocatorUseContext;

typedefconstvoid* (*CFAllocatorRetainCallBack)(constvoid*info);
typedefvoid (*CFAllocatorReleaseCallBack)(constvoid*info);
typedefCFStringRef (*CFAllocatorCopyDescriptionCallBack)(constvoid*info);
typedefvoid* (*CFAllocatorAllocateCallBack)(CFIndexallocSize, CFOptionFlagshint, void*info);
typedefvoid* (*CFAllocatorReallocateCallBack)(void*ptr, CFIndexnewsize, CFOptionFlagshint, void*info);
typedefvoid (*CFAllocatorDeallocateCallBack)(void*ptr, void*info);
typedefCFIndex (*CFAllocatorPreferredSizeCallBack)(CFIndexsize, CFOptionFlagshint, void*info);
typedefstruct {
CFIndexversion;
void*info;
CFAllocatorRetainCallBackretain;
CFAllocatorReleaseCallBackrelease; 
CFAllocatorCopyDescriptionCallBackcopyDescription;
CFAllocatorAllocateCallBackallocate;
CFAllocatorReallocateCallBackreallocate;
CFAllocatorDeallocateCallBackdeallocate;
CFAllocatorPreferredSizeCallBackpreferredSize;
} CFAllocatorContext;

CF_EXPORT
CFTypeIDCFAllocatorGetTypeID(void);

/*
 CFAllocatorSetDefault() sets the allocator that is used in the current
 thread whenever NULL is specified as an allocator argument. This means
 that most, if not all allocations will go through this allocator. It
 also means that any allocator set as the default needs to be ready to
 deal with arbitrary memory allocation requests; in addition, the size
 and number of requests will change between releases.

 An allocator set as the default will never be released, even if later
 another allocator replaces it as the default. Not only is it impractical
 for it to be released (as there might be caches created under the covers
 that refer to the allocator), in general it's also safer and more
 efficient to keep it around.

 If you wish to use a custom allocator in a context, it's best to provide
 it as the argument to the various creation functions rather than setting
 it as the default. Setting the default allocator is not encouraged.

 If you do set an allocator as the default, either do it for all time in
 your app, or do it in a nested fashion (by restoring the previous allocator
 when you exit your context). The latter might be appropriate for plug-ins
 or libraries that wish to set the default allocator.
*/
CF_EXPORT
voidCFAllocatorSetDefault(CFAllocatorRefallocator);

CF_EXPORT
CFAllocatorRefCFAllocatorGetDefault(void);

CF_EXPORT
CFAllocatorRefCFAllocatorCreate(CFAllocatorRefallocator, CFAllocatorContext*context);

CF_EXPORT
void*CFAllocatorAllocate(CFAllocatorRefallocator, CFIndexsize, CFOptionFlagshint);

CF_EXPORT
void*CFAllocatorReallocate(CFAllocatorRefallocator, void*ptr, CFIndexnewsize, CFOptionFlagshint);

CF_EXPORT
voidCFAllocatorDeallocate(CFAllocatorRefallocator, void*ptr);

CF_EXPORT
CFIndexCFAllocatorGetPreferredSizeForSize(CFAllocatorRefallocator, CFIndexsize, CFOptionFlagshint);

CF_EXPORT
voidCFAllocatorGetContext(CFAllocatorRefallocator, CFAllocatorContext*context);


/* Polymorphic CF functions */

CF_EXPORT
CFTypeIDCFGetTypeID(CFTypeRefcf);

CF_EXPORT
CFStringRefCFCopyTypeIDDescription(CFTypeIDtype_id);

CF_EXPORT
CFTypeRefCFRetain(CFTypeRefcf);

CF_EXPORT
voidCFRelease(CFTypeRefcf);

CF_EXPORT
CFIndexCFGetRetainCount(CFTypeRefcf);

// This function is unavailable in ARC mode. Use CFBridgingRelease instead.
CF_EXPORT
CFTypeRefCFMakeCollectable(CFTypeRefcf) CF_AUTOMATED_REFCOUNT_UNAVAILABLE;

CF_EXPORT
BooleanCFEqual(CFTypeRefcf1, CFTypeRefcf2);

CF_EXPORT
CFHashCodeCFHash(CFTypeRefcf);

CF_EXPORT
CFStringRefCFCopyDescription(CFTypeRefcf);

CF_EXPORT
CFAllocatorRefCFGetAllocator(CFTypeRefcf);

CF_EXTERN_C_END

#endif/* ! __COREFOUNDATION_CFBASE__ */