CFBase.h

   1 /*
   2  * Copyright (c) 2012 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 /*      CFBase.h
  25         Copyright (c) 1998-2012, Apple Inc. All rights reserved.
  26 */
  27
  28 #if !defined(__COREFOUNDATION_CFBASE__)
  29 #define __COREFOUNDATION_CFBASE__ 1
  30
  31 #include <TargetConditionals.h>
  32
  33 #if (defined(__CYGWIN32__) || defined(_WIN32)) && !defined(__WIN32__)
  34 #define __WIN32__ 1
  35 #endif
  36
  37 #if defined(_WIN64) && !defined(__WIN64__)
  38 #define __WIN64__ 1
  39 #endif
  40
  41 #if defined(__WIN64__) && !defined(__LLP64__)
  42 #define __LLP64__ 1
  43 #endif
  44
  45 #if defined(_MSC_VER) && defined(_M_IX86)
  46 #define __i386__ 1
  47 #endif
  48
  49 #if (defined(__i386__) || defined(__x86_64__)) && !defined(__LITTLE_ENDIAN__)
  50 #define __LITTLE_ENDIAN__ 1
  51 #endif
  52
  53 #if !defined(__BIG_ENDIAN__) && !defined(__LITTLE_ENDIAN__)
  54 #error Do not know the endianess of this architecture
  55 #endif
  56
  57 #if !__BIG_ENDIAN__ && !__LITTLE_ENDIAN__
  58 #error Both __BIG_ENDIAN__ and __LITTLE_ENDIAN__ cannot be false
  59 #endif
  60
  61 #if __BIG_ENDIAN__ && __LITTLE_ENDIAN__
  62 #error Both __BIG_ENDIAN__ and __LITTLE_ENDIAN__ cannot be true
  63 #endif
  64
  65 // Some compilers provide the capability to test if certain features are available. This macro provides a compatibility path for other compilers.
  66 #ifndef __has_feature
  67 #define __has_feature(x) 0
  68 #endif
  69
  70 // Some compilers provide the capability to test if certain attributes are available. This macro provides a compatibility path for other compilers.
  71 #ifndef __has_attribute
  72 #define __has_attribute(x) 0
  73 #endif
  74
  75 #ifndef __has_extension
  76 #define __has_extension(x) 0
  77 #endif
  78
  79 #if defined(__GNUC__) || TARGET_OS_WIN32
  80 #include <stdint.h>
  81 #include <stdbool.h>
  82 #endif
  83
  84 #if __BLOCKS__
  85 #include <Block.h>
  86 #endif
  87
  88 // The arguments to these availability macros is a version number, e.g. 10_6, 3_0
  89 #if (TARGET_OS_MAC || TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)
  90 #include <AvailabilityMacros.h>
  91 #include <Availability.h>
  92
  93 #ifndef __IPHONE_5_0
  94 #define __IPHONE_5_0 50000
  95 #endif
  96
  97 #ifndef __IPHONE_6_0
  98 #define __IPHONE_6_0 60000
  99 #endif
 100
 101 // Available on MacOS and iOS
 102 #define CF_AVAILABLE(_mac, _ios) __OSX_AVAILABLE_STARTING(__MAC_##_mac, __IPHONE_##_ios)
 103
 104 // Available on MacOS only
 105 #define CF_AVAILABLE_MAC(_mac) __OSX_AVAILABLE_STARTING(__MAC_##_mac, __IPHONE_NA)
 106
 107 // Available on iOS only
 108 #define CF_AVAILABLE_IOS(_ios) __OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_##_ios)
 109
 110 // Deprecated on either MacOS or iOS, or deprecated on both (check version numbers for details)
 111 #define CF_DEPRECATED(_macIntro, _macDep, _iosIntro, _iosDep) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_##_macIntro, __MAC_##_macDep, __IPHONE_##_iosIntro, __IPHONE_##_iosDep)
 112
 113 // Deprecated on MacOS, unavailable on iOS
 114 #define CF_DEPRECATED_MAC(_macIntro, _macDep) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_##_macIntro, __MAC_##_macDep, __IPHONE_NA, __IPHONE_NA)
 115
 116 // Unavailable on MacOS, deprecated on iOS
 117 #define CF_DEPRECATED_IOS(_iosIntro, _iosDep) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_NA, __MAC_NA, __IPHONE_##_iosIntro, __IPHONE_##_iosDep)
 118
 119 #else
 120
 121 #if TARGET_OS_WIN32
 122 #include <AvailabilityMacros.h>
 123 #include <Availability.h>
 124 #endif
 125
 126 #define CF_AVAILABLE(_mac, _ios)
 127 #define CF_AVAILABLE_MAC(_mac)
 128 #define CF_AVAILABLE_IOS(_ios)
 129 #define CF_DEPRECATED(_macIntro, _macDep, _iosIntro, _iosDep)
 130 #define CF_DEPRECATED_MAC(_macIntro, _macDep)
 131 #define CF_DEPRECATED_IOS(_iosIntro, _iosDep)
 132
 133 #endif
 134
 135 #if __has_feature(enumerator_attributes) && __has_attribute(availability)
 136 #define CF_ENUM_AVAILABLE(_mac, _ios) __OSX_AVAILABLE_STARTING(__MAC_##_mac, __IPHONE_##_ios)
 137 #define CF_ENUM_AVAILABLE_MAC(_mac) __OSX_AVAILABLE_STARTING(__MAC_##_mac, __IPHONE_NA)
 138 #define CF_ENUM_AVAILABLE_IOS(_ios) __OSX_AVAILABLE_STARTING(__MAC_NA, __IPHONE_##_ios)
 139 #define CF_ENUM_DEPRECATED(_macIntro, _macDep, _iosIntro, _iosDep) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_##_macIntro, __MAC_##_macDep, __IPHONE_##_iosIntro, __IPHONE_##_iosDep)
 140 #define CF_ENUM_DEPRECATED_MAC(_macIntro, _macDep) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_##_macIntro, __MAC_##_macDep, __IPHONE_NA, __IPHONE_NA)
 141 #define CF_ENUM_DEPRECATED_IOS(_iosIntro, _iosDep) __OSX_AVAILABLE_BUT_DEPRECATED(__MAC_NA, __MAC_NA, __IPHONE_##_iosIntro, __IPHONE_##_iosDep)
 142 #else
 143 #define CF_ENUM_AVAILABLE(_mac, _ios)
 144 #define CF_ENUM_AVAILABLE_MAC(_mac)
 145 #define CF_ENUM_AVAILABLE_IOS(_ios)
 146 #define CF_ENUM_DEPRECATED(_macIntro, _macDep, _iosIntro, _iosDep)
 147 #define CF_ENUM_DEPRECATED_MAC(_macIntro, _macDep)
 148 #define CF_ENUM_DEPRECATED_IOS(_iosIntro, _iosDep)
 149 #endif
 150
 151 #if (__cplusplus && __cplusplus >= 201103L && (__has_extension(cxx_strong_enums) || __has_feature(objc_fixed_enum))) || (!__cplusplus && __has_feature(objc_fixed_enum))
 152 #define CF_ENUM(_type, _name) enum _name : _type _name; enum _name : _type
 153 #if (__cplusplus)
 154 #define CF_OPTIONS(_type, _name) _type _name; enum : _type
 155 #else
 156 #define CF_OPTIONS(_type, _name) enum _name : _type _name; enum _name : _type
 157 #endif
 158 #else
 159 #define CF_ENUM(_type, _name) _type _name; enum
 160 #define CF_OPTIONS(_type, _name) _type _name; enum
 161 #endif
 162
 163 // Older versions of these macro; use IOS versions instead
 164 #define CF_AVAILABLE_IPHONE(_ios) CF_AVAILABLE_IOS(_ios)
 165 #define CF_DEPRECATED_IPHONE(_iosIntro, _iosDep) CF_DEPRECATED_IOS(_iosIntro, _iosDep)
 166
 167   #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) || (TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)
 168     #include <libkern/OSTypes.h>
 169   #endif
 170
 171 #if !defined(__MACTYPES__)
 172 #if !defined(_OS_OSTYPES_H)
 173     typedef unsigned char           Boolean;
 174     typedef unsigned char           UInt8;
 175     typedef signed char             SInt8;
 176     typedef unsigned short          UInt16;
 177     typedef signed short            SInt16;
 178     typedef unsigned int            UInt32;
 179     typedef signed int              SInt32;
 180     typedef uint64_t                UInt64;
 181     typedef int64_t                 SInt64;
 182     typedef SInt32                  OSStatus;
 183 #endif
 184     typedef float                   Float32;
 185     typedef double                  Float64;
 186     typedef unsigned short          UniChar;
 187     typedef unsigned long           UniCharCount;
 188     typedef unsigned char *         StringPtr;
 189     typedef const unsigned char *   ConstStringPtr;
 190     typedef unsigned char           Str255[256];
 191     typedef const unsigned char *   ConstStr255Param;
 192     typedef SInt16                  OSErr;
 193     typedef SInt16                  RegionCode;
 194     typedef SInt16                  LangCode;
 195     typedef SInt16                  ScriptCode;
 196     typedef UInt32                  FourCharCode;
 197     typedef FourCharCode            OSType;
 198     typedef UInt8                   Byte;
 199     typedef SInt8                   SignedByte;
 200 #endif
 201 #if !defined(__MACTYPES__) || (defined(UNIVERSAL_INTERFACES_VERSION) && UNIVERSAL_INTERFACES_VERSION < 0x0340)
 202     typedef UInt32                  UTF32Char;
 203     typedef UInt16                  UTF16Char;
 204     typedef UInt8                   UTF8Char;
 205 #endif
 206
 207 #if !defined(CF_EXTERN_C_BEGIN)
 208 #if defined(__cplusplus)
 209 #define CF_EXTERN_C_BEGIN extern "C" {
 210 #define CF_EXTERN_C_END   }
 211 #else
 212 #define CF_EXTERN_C_BEGIN
 213 #define CF_EXTERN_C_END
 214 #endif
 215 #endif
 216
 217 #if TARGET_OS_WIN32
 218
 219 #if !defined(CF_EXPORT)
 220 #if defined(CF_BUILDING_CF) && defined(__cplusplus)
 221 #define CF_EXPORT extern "C" __declspec(dllexport)
 222 #elif defined(CF_BUILDING_CF) && !defined(__cplusplus)
 223 #define CF_EXPORT extern __declspec(dllexport)
 224 #elif defined(__cplusplus)
 225 #define CF_EXPORT extern "C" __declspec(dllimport)
 226 #else
 227 #define CF_EXPORT extern __declspec(dllimport)
 228 #endif
 229 #endif
 230
 231 #else
 232 #define CF_EXPORT extern
 233 #endif
 234
 235 CF_EXTERN_C_BEGIN
 236
 237 #if !defined(NULL)
 238 #if defined(__GNUG__)
 239     #define NULL __null
 240 #elif defined(__cplusplus)
 241     #define NULL 0
 242 #else
 243     #define NULL ((void *)0)
 244 #endif
 245 #endif
 246
 247 #if !defined(TRUE)
 248     #define TRUE        1
 249 #endif
 250
 251 #if !defined(FALSE)
 252     #define FALSE       0
 253 #endif
 254
 255 #if !defined(CF_INLINE)
 256     #if defined(__GNUC__) && (__GNUC__ == 4) && !defined(DEBUG)
 257         #define CF_INLINE static __inline__ __attribute__((always_inline))
 258     #elif defined(__GNUC__)
 259         #define CF_INLINE static __inline__
 260     #elif defined(__cplusplus)
 261         #define CF_INLINE static inline
 262     #elif defined(_MSC_VER)
 263         #define CF_INLINE static __inline
 264     #elif TARGET_OS_WIN32
 265         #define CF_INLINE static __inline__
 266     #endif
 267 #endif
 268
 269 // 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.
 270 // This macro is ONLY to be used in exceptional circumstances, not to annotate functions which conform to the CoreFoundation naming rules.
 271 #ifndef CF_RETURNS_RETAINED
 272 #if __has_feature(attribute_cf_returns_retained)
 273 #define CF_RETURNS_RETAINED __attribute__((cf_returns_retained))
 274 #else
 275 #define CF_RETURNS_RETAINED
 276 #endif
 277 #endif
 278
 279 // 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.
 280 // This macro is ONLY to be used in exceptional circumstances, not to annotate functions which conform to the CoreFoundation naming rules.
 281 #ifndef CF_RETURNS_NOT_RETAINED
 282 #if __has_feature(attribute_cf_returns_not_retained)
 283 #define CF_RETURNS_NOT_RETAINED __attribute__((cf_returns_not_retained))
 284 #else
 285 #define CF_RETURNS_NOT_RETAINED
 286 #endif
 287 #endif
 288
 289 // Marks function arguments which are released by the callee.
 290 #ifndef CF_RELEASES_ARGUMENT
 291 #if __has_feature(attribute_cf_consumed)
 292 #define CF_RELEASES_ARGUMENT __attribute__((cf_consumed))
 293 #else
 294 #define CF_RELEASES_ARGUMENT
 295 #endif
 296 #endif
 297
 298 // Compatibility
 299 #ifndef CF_CONSUMED
 300 #if __has_feature(attribute_cf_consumed)
 301 #define CF_CONSUMED __attribute__((cf_consumed))
 302 #else
 303 #define CF_CONSUMED
 304 #endif
 305 #endif
 306
 307 // Marks functions which cannot be used when compiling in automatic reference counting mode.
 308 #if __has_feature(objc_arc)
 309 #define CF_AUTOMATED_REFCOUNT_UNAVAILABLE __attribute__((unavailable("not available in automatic reference counting mode")))
 310 #else
 311 #define CF_AUTOMATED_REFCOUNT_UNAVAILABLE
 312 #endif
 313
 314 #ifndef CF_IMPLICIT_BRIDGING_ENABLED
 315 #if __has_feature(arc_cf_code_audited)
 316 #define CF_IMPLICIT_BRIDGING_ENABLED _Pragma("clang arc_cf_code_audited begin")
 317 #else
 318 #define CF_IMPLICIT_BRIDGING_ENABLED
 319 #endif
 320 #endif
 321
 322 #ifndef CF_IMPLICIT_BRIDGING_DISABLED
 323 #if __has_feature(arc_cf_code_audited)
 324 #define CF_IMPLICIT_BRIDGING_DISABLED _Pragma("clang arc_cf_code_audited end")
 325 #else
 326 #define CF_IMPLICIT_BRIDGING_DISABLED
 327 #endif
 328 #endif
 329
 330
 331 CF_EXPORT double kCFCoreFoundationVersionNumber;
 332
 333 #if TARGET_OS_MAC
 334 #define kCFCoreFoundationVersionNumber10_0      196.40
 335 #define kCFCoreFoundationVersionNumber10_0_3    196.50
 336 #define kCFCoreFoundationVersionNumber10_1      226.00
 337 #define kCFCoreFoundationVersionNumber10_1_1    226.00
 338 /* Note the next three do not follow the usual numbering policy from the base release */
 339 #define kCFCoreFoundationVersionNumber10_1_2    227.20
 340 #define kCFCoreFoundationVersionNumber10_1_3    227.20
 341 #define kCFCoreFoundationVersionNumber10_1_4    227.30
 342 #define kCFCoreFoundationVersionNumber10_2      263.00
 343 #define kCFCoreFoundationVersionNumber10_2_1    263.10
 344 #define kCFCoreFoundationVersionNumber10_2_2    263.10
 345 #define kCFCoreFoundationVersionNumber10_2_3    263.30
 346 #define kCFCoreFoundationVersionNumber10_2_4    263.30
 347 #define kCFCoreFoundationVersionNumber10_2_5    263.50
 348 #define kCFCoreFoundationVersionNumber10_2_6    263.50
 349 #define kCFCoreFoundationVersionNumber10_2_7    263.50
 350 #define kCFCoreFoundationVersionNumber10_2_8    263.50
 351 #define kCFCoreFoundationVersionNumber10_3      299.00
 352 #define kCFCoreFoundationVersionNumber10_3_1    299.00
 353 #define kCFCoreFoundationVersionNumber10_3_2    299.00
 354 #define kCFCoreFoundationVersionNumber10_3_3    299.30
 355 #define kCFCoreFoundationVersionNumber10_3_4    299.31
 356 #define kCFCoreFoundationVersionNumber10_3_5    299.31
 357 #define kCFCoreFoundationVersionNumber10_3_6    299.32
 358 #define kCFCoreFoundationVersionNumber10_3_7    299.33
 359 #define kCFCoreFoundationVersionNumber10_3_8    299.33
 360 #define kCFCoreFoundationVersionNumber10_3_9    299.35
 361 #define kCFCoreFoundationVersionNumber10_4      368.00
 362 #define kCFCoreFoundationVersionNumber10_4_1    368.10
 363 #define kCFCoreFoundationVersionNumber10_4_2    368.11
 364 #define kCFCoreFoundationVersionNumber10_4_3    368.18
 365 #define kCFCoreFoundationVersionNumber10_4_4_Intel      368.26
 366 #define kCFCoreFoundationVersionNumber10_4_4_PowerPC    368.25
 367 #define kCFCoreFoundationVersionNumber10_4_5_Intel      368.26
 368 #define kCFCoreFoundationVersionNumber10_4_5_PowerPC    368.25
 369 #define kCFCoreFoundationVersionNumber10_4_6_Intel      368.26
 370 #define kCFCoreFoundationVersionNumber10_4_6_PowerPC    368.25
 371 #define kCFCoreFoundationVersionNumber10_4_7    368.27
 372 #define kCFCoreFoundationVersionNumber10_4_8    368.27
 373 #define kCFCoreFoundationVersionNumber10_4_9    368.28
 374 #define kCFCoreFoundationVersionNumber10_4_10   368.28
 375 #define kCFCoreFoundationVersionNumber10_4_11   368.31
 376 #define kCFCoreFoundationVersionNumber10_5      476.00
 377 #define kCFCoreFoundationVersionNumber10_5_1    476.00
 378 #define kCFCoreFoundationVersionNumber10_5_2    476.10
 379 #define kCFCoreFoundationVersionNumber10_5_3    476.13
 380 #define kCFCoreFoundationVersionNumber10_5_4    476.14
 381 #define kCFCoreFoundationVersionNumber10_5_5    476.15
 382 #define kCFCoreFoundationVersionNumber10_5_6    476.17
 383 #define kCFCoreFoundationVersionNumber10_5_7    476.18
 384 #define kCFCoreFoundationVersionNumber10_5_8    476.19
 385 #define kCFCoreFoundationVersionNumber10_6      550.00
 386 #define kCFCoreFoundationVersionNumber10_6_1    550.00
 387 #define kCFCoreFoundationVersionNumber10_6_2    550.13
 388 #define kCFCoreFoundationVersionNumber10_6_3    550.19
 389 #define kCFCoreFoundationVersionNumber10_6_4    550.29
 390 #define kCFCoreFoundationVersionNumber10_6_5    550.42
 391 #define kCFCoreFoundationVersionNumber10_6_6    550.42
 392 #define kCFCoreFoundationVersionNumber10_6_7    550.42
 393 #define kCFCoreFoundationVersionNumber10_6_8    550.43
 394 #define kCFCoreFoundationVersionNumber10_7      635.00
 395 #define kCFCoreFoundationVersionNumber10_7_1    635.00
 396 #define kCFCoreFoundationVersionNumber10_7_2    635.15
 397 #define kCFCoreFoundationVersionNumber10_7_3    635.19
 398 #define kCFCoreFoundationVersionNumber10_7_4    635.21
 399 #endif
 400
 401 #if TARGET_OS_IPHONE
 402 #define kCFCoreFoundationVersionNumber_iPhoneOS_2_0     478.23
 403 #define kCFCoreFoundationVersionNumber_iPhoneOS_2_1 478.26
 404 #define kCFCoreFoundationVersionNumber_iPhoneOS_2_2 478.29
 405 #define kCFCoreFoundationVersionNumber_iPhoneOS_3_0 478.47
 406 #define kCFCoreFoundationVersionNumber_iPhoneOS_3_1 478.52
 407 #define kCFCoreFoundationVersionNumber_iPhoneOS_3_2 478.61
 408 #define kCFCoreFoundationVersionNumber_iOS_4_0 550.32
 409 #define kCFCoreFoundationVersionNumber_iOS_4_1 550.38
 410 #define kCFCoreFoundationVersionNumber_iOS_4_2 550.52
 411 #define kCFCoreFoundationVersionNumber_iOS_4_3 550.52
 412 #define kCFCoreFoundationVersionNumber_iOS_5_0 675
 413 #define kCFCoreFoundationVersionNumber_iOS_5_1 690.1
 414 #endif
 415
 416 #if __LLP64__
 417 typedef unsigned long long CFTypeID;
 418 typedef unsigned long long CFOptionFlags;
 419 typedef unsigned long long CFHashCode;
 420 typedef signed long long CFIndex;
 421 #else
 422 typedef unsigned long CFTypeID;
 423 typedef unsigned long CFOptionFlags;
 424 typedef unsigned long CFHashCode;
 425 typedef signed long CFIndex;
 426 #endif
 427
 428 /* Base "type" of all "CF objects", and polymorphic functions on them */
 429 typedef const void * CFTypeRef;
 430
 431 typedef const struct __CFString * CFStringRef;
 432 typedef struct __CFString * CFMutableStringRef;
 433
 434 /*
 435         Type to mean any instance of a property list type;
 436         currently, CFString, CFData, CFNumber, CFBoolean, CFDate,
 437         CFArray, and CFDictionary.
 438 */
 439 typedef CFTypeRef CFPropertyListRef;
 440
 441 /* Values returned from comparison functions */
 442 typedef CF_ENUM(CFIndex, CFComparisonResult) {
 443     kCFCompareLessThan = -1L,
 444     kCFCompareEqualTo = 0,
 445     kCFCompareGreaterThan = 1
 446 };
 447
 448 /* A standard comparison function */
 449 typedef CFComparisonResult (*CFComparatorFunction)(const void *val1, const void *val2, void *context);
 450
 451 /* Constant used by some functions to indicate failed searches. */
 452 /* This is of type CFIndex. */
 453 enum {
 454     kCFNotFound = -1
 455 };
 456
 457
 458 /* Range type */
 459 typedef struct {
 460     CFIndex location;
 461     CFIndex length;
 462 } CFRange;
 463
 464 #if defined(CF_INLINE)
 465 CF_INLINE CFRange CFRangeMake(CFIndex loc, CFIndex len) {
 466     CFRange range;
 467     range.location = loc;
 468     range.length = len;
 469     return range;
 470 }
 471 #else
 472 #define CFRangeMake(LOC, LEN) __CFRangeMake(LOC, LEN)
 473 #endif
 474
 475 /* Private; do not use */
 476 CF_EXPORT
 477 CFRange __CFRangeMake(CFIndex loc, CFIndex len);
 478
 479
 480 /* Null representant */
 481
 482 typedef const struct __CFNull * CFNullRef;
 483
 484 CF_EXPORT
 485 CFTypeID CFNullGetTypeID(void);
 486
 487 CF_EXPORT
 488 const CFNullRef kCFNull;        // the singleton null instance
 489
 490
 491 /* Allocator API
 492
 493    Most of the time when specifying an allocator to Create functions, the NULL
 494    argument indicates "use the default"; this is the same as using kCFAllocatorDefault
 495    or the return value from CFAllocatorGetDefault().  This assures that you will use
 496    the allocator in effect at that time.
 497
 498    You should rarely use kCFAllocatorSystemDefault, the default default allocator.
 499 */
 500 typedef const struct __CFAllocator * CFAllocatorRef;
 501
 502 /* This is a synonym for NULL, if you'd rather use a named constant. */
 503 CF_EXPORT
 504 const CFAllocatorRef kCFAllocatorDefault;
 505
 506 /* Default system allocator; you rarely need to use this. */
 507 CF_EXPORT
 508 const CFAllocatorRef kCFAllocatorSystemDefault;
 509
 510 /* This allocator uses malloc(), realloc(), and free(). This should not be
 511    generally used; stick to kCFAllocatorDefault whenever possible. This
 512    allocator is useful as the "bytesDeallocator" in CFData or
 513    "contentsDeallocator" in CFString where the memory was obtained as a
 514    result of malloc() type functions.
 515 */
 516 CF_EXPORT
 517 const CFAllocatorRef kCFAllocatorMalloc;
 518
 519 /* This allocator explicitly uses the default malloc zone, returned by
 520    malloc_default_zone(). It should only be used when an object is
 521    safe to be allocated in non-scanned memory.
 522  */
 523 CF_EXPORT
 524 const CFAllocatorRef kCFAllocatorMallocZone;
 525
 526 /* Null allocator which does nothing and allocates no memory. This allocator
 527    is useful as the "bytesDeallocator" in CFData or "contentsDeallocator"
 528    in CFString where the memory should not be freed.
 529 */
 530 CF_EXPORT
 531 const CFAllocatorRef kCFAllocatorNull;
 532
 533 /* Special allocator argument to CFAllocatorCreate() which means
 534    "use the functions given in the context to allocate the allocator
 535    itself as well".
 536 */
 537 CF_EXPORT
 538 const CFAllocatorRef kCFAllocatorUseContext;
 539
 540 typedef const void *    (*CFAllocatorRetainCallBack)(const void *info);
 541 typedef void            (*CFAllocatorReleaseCallBack)(const void *info);
 542 typedef CFStringRef     (*CFAllocatorCopyDescriptionCallBack)(const void *info);
 543 typedef void *          (*CFAllocatorAllocateCallBack)(CFIndex allocSize, CFOptionFlags hint, void *info);
 544 typedef void *          (*CFAllocatorReallocateCallBack)(void *ptr, CFIndex newsize, CFOptionFlags hint, void *info);
 545 typedef void            (*CFAllocatorDeallocateCallBack)(void *ptr, void *info);
 546 typedef CFIndex         (*CFAllocatorPreferredSizeCallBack)(CFIndex size, CFOptionFlags hint, void *info);
 547 typedef struct {
 548     CFIndex                             version;
 549     void *                              info;
 550     CFAllocatorRetainCallBack           retain;
 551     CFAllocatorReleaseCallBack          release;
 552     CFAllocatorCopyDescriptionCallBack  copyDescription;
 553     CFAllocatorAllocateCallBack         allocate;
 554     CFAllocatorReallocateCallBack       reallocate;
 555     CFAllocatorDeallocateCallBack       deallocate;
 556     CFAllocatorPreferredSizeCallBack    preferredSize;
 557 } CFAllocatorContext;
 558
 559 CF_EXPORT
 560 CFTypeID        CFAllocatorGetTypeID(void);
 561
 562 /*
 563         CFAllocatorSetDefault() sets the allocator that is used in the current
 564         thread whenever NULL is specified as an allocator argument. This means
 565         that most, if not all allocations will go through this allocator. It
 566         also means that any allocator set as the default needs to be ready to
 567         deal with arbitrary memory allocation requests; in addition, the size
 568         and number of requests will change between releases.
 569
 570         An allocator set as the default will never be released, even if later
 571         another allocator replaces it as the default. Not only is it impractical
 572         for it to be released (as there might be caches created under the covers
 573         that refer to the allocator), in general it's also safer and more
 574         efficient to keep it around.
 575
 576         If you wish to use a custom allocator in a context, it's best to provide
 577         it as the argument to the various creation functions rather than setting
 578         it as the default. Setting the default allocator is not encouraged.
 579
 580         If you do set an allocator as the default, either do it for all time in
 581         your app, or do it in a nested fashion (by restoring the previous allocator
 582         when you exit your context). The latter might be appropriate for plug-ins
 583         or libraries that wish to set the default allocator.
 584 */
 585 CF_EXPORT
 586 void CFAllocatorSetDefault(CFAllocatorRef allocator);
 587
 588 CF_EXPORT
 589 CFAllocatorRef CFAllocatorGetDefault(void);
 590
 591 CF_EXPORT
 592 CFAllocatorRef CFAllocatorCreate(CFAllocatorRef allocator, CFAllocatorContext *context);
 593
 594 CF_EXPORT
 595 void *CFAllocatorAllocate(CFAllocatorRef allocator, CFIndex size, CFOptionFlags hint);
 596
 597 CF_EXPORT
 598 void *CFAllocatorReallocate(CFAllocatorRef allocator, void *ptr, CFIndex newsize, CFOptionFlags hint);
 599
 600 CF_EXPORT
 601 void CFAllocatorDeallocate(CFAllocatorRef allocator, void *ptr);
 602
 603 CF_EXPORT
 604 CFIndex CFAllocatorGetPreferredSizeForSize(CFAllocatorRef allocator, CFIndex size, CFOptionFlags hint);
 605
 606 CF_EXPORT
 607 void CFAllocatorGetContext(CFAllocatorRef allocator, CFAllocatorContext *context);
 608
 609
 610 /* Polymorphic CF functions */
 611
 612 CF_EXPORT
 613 CFTypeID CFGetTypeID(CFTypeRef cf);
 614
 615 CF_EXPORT
 616 CFStringRef CFCopyTypeIDDescription(CFTypeID type_id);
 617
 618 CF_EXPORT
 619 CFTypeRef CFRetain(CFTypeRef cf);
 620
 621 CF_EXPORT
 622 void CFRelease(CFTypeRef cf);
 623
 624 CF_EXPORT
 625 CFIndex CFGetRetainCount(CFTypeRef cf);
 626
 627 // This function is unavailable in ARC mode. Use CFBridgingRelease instead.
 628 CF_EXPORT
 629 CFTypeRef CFMakeCollectable(CFTypeRef cf) CF_AUTOMATED_REFCOUNT_UNAVAILABLE;
 630
 631 CF_EXPORT
 632 Boolean CFEqual(CFTypeRef cf1, CFTypeRef cf2);
 633
 634 CF_EXPORT
 635 CFHashCode CFHash(CFTypeRef cf);
 636
 637 CF_EXPORT
 638 CFStringRef CFCopyDescription(CFTypeRef cf);
 639
 640 CF_EXPORT
 641 CFAllocatorRef CFGetAllocator(CFTypeRef cf);
 642
 643 CF_EXTERN_C_END
 644
 645 #endif /* ! __COREFOUNDATION_CFBASE__ */
 646