CFBase.h

   1 /*
   2  * Copyright (c) 2009 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 /*      CFBase.h
  24         Copyright (c) 1998-2009, Apple Inc. All rights reserved.
  25 */
  26
  27 #if !defined(__COREFOUNDATION_CFBASE__)
  28 #define __COREFOUNDATION_CFBASE__ 1
  29
  30 #include <TargetConditionals.h>
  31
  32 #if (defined(__CYGWIN32__) || defined(_WIN32)) && !defined(__WIN32__)
  33 #define __WIN32__ 1
  34 #endif
  35
  36 #if defined(_MSC_VER) && defined(_M_IX86)
  37 #define __i386__ 1
  38 #endif
  39
  40 #if (defined(__i386__) || defined(__x86_64__)) && !defined(__LITTLE_ENDIAN__)
  41 #define __LITTLE_ENDIAN__ 1
  42 #endif
  43
  44 #if !defined(__BIG_ENDIAN__) && !defined(__LITTLE_ENDIAN__)
  45 #error Do not know the endianess of this architecture
  46 #endif
  47
  48 #if !__BIG_ENDIAN__ && !__LITTLE_ENDIAN__
  49 #error Both __BIG_ENDIAN__ and __LITTLE_ENDIAN__ cannot be false
  50 #endif
  51
  52 #if __BIG_ENDIAN__ && __LITTLE_ENDIAN__
  53 #error Both __BIG_ENDIAN__ and __LITTLE_ENDIAN__ cannot be true
  54 #endif
  55
  56 #if TARGET_OS_WIN32
  57 #include <stdint.h>
  58 #include <stdbool.h>
  59 #elif defined(__GNUC__)
  60 #include <stdint.h>
  61 #include <stdbool.h>
  62 #endif
  63 #include <AvailabilityMacros.h>
  64
  65 #if (TARGET_OS_MAC && !(TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)) || (TARGET_OS_EMBEDDED || TARGET_OS_IPHONE)
  66 #include <libkern/OSTypes.h>
  67 #endif
  68
  69 #if !defined(__MACTYPES__)
  70 #if !defined(_OS_OSTYPES_H)
  71     typedef unsigned char           Boolean;
  72     typedef unsigned char           UInt8;
  73     typedef signed char             SInt8;
  74     typedef unsigned short          UInt16;
  75     typedef signed short            SInt16;
  76     typedef unsigned int            UInt32;
  77     typedef signed int              SInt32;
  78     typedef uint64_t                UInt64;
  79     typedef int64_t                 SInt64;
  80     typedef SInt32                  OSStatus;
  81 #endif
  82     typedef float                   Float32;
  83     typedef double                  Float64;
  84     typedef unsigned short          UniChar;
  85     typedef unsigned long           UniCharCount;
  86     typedef unsigned char *         StringPtr;
  87     typedef const unsigned char *   ConstStringPtr;
  88     typedef unsigned char           Str255[256];
  89     typedef const unsigned char *   ConstStr255Param;
  90     typedef SInt16                  OSErr;
  91     typedef SInt16                  RegionCode;
  92     typedef SInt16                  LangCode;
  93     typedef SInt16                  ScriptCode;
  94     typedef UInt32                  FourCharCode;
  95     typedef FourCharCode            OSType;
  96     typedef UInt8                   Byte;
  97     typedef SInt8                   SignedByte;
  98 #endif
  99 #if !defined(__MACTYPES__) || (defined(UNIVERSAL_INTERFACES_VERSION) && UNIVERSAL_INTERFACES_VERSION < 0x0340)
 100     typedef UInt32                  UTF32Char;
 101     typedef UInt16                  UTF16Char;
 102     typedef UInt8                   UTF8Char;
 103 #endif
 104
 105 #if !defined(CF_EXTERN_C_BEGIN)
 106 #if defined(__cplusplus)
 107 #define CF_EXTERN_C_BEGIN extern "C" {
 108 #define CF_EXTERN_C_END   }
 109 #else
 110 #define CF_EXTERN_C_BEGIN
 111 #define CF_EXTERN_C_END
 112 #endif
 113 #endif
 114
 115 #if TARGET_OS_WIN32 && defined(CF_BUILDING_CF) && defined(__cplusplus)
 116 #define CF_EXPORT extern "C" __declspec(dllexport)
 117 #elif TARGET_OS_WIN32 && defined(CF_BUILDING_CF) && !defined(__cplusplus)
 118 #define CF_EXPORT extern __declspec(dllexport)
 119 #elif TARGET_OS_WIN32 && defined(__cplusplus)
 120 #define CF_EXPORT extern "C" __declspec(dllimport)
 121 #elif TARGET_OS_WIN32
 122 #define CF_EXPORT extern __declspec(dllimport)
 123 #else
 124 #define CF_EXPORT extern
 125 #endif
 126
 127 CF_EXTERN_C_BEGIN
 128
 129 #if !defined(NULL)
 130 #if defined(__GNUG__)
 131     #define NULL __null
 132 #elif defined(__cplusplus)
 133     #define NULL 0
 134 #else
 135     #define NULL ((void *)0)
 136 #endif
 137 #endif
 138
 139 #if !defined(TRUE)
 140     #define TRUE        1
 141 #endif
 142
 143 #if !defined(FALSE)
 144     #define FALSE       0
 145 #endif
 146
 147 #if !defined(CF_INLINE)
 148     #if defined(__GNUC__) && (__GNUC__ == 4) && !defined(DEBUG)
 149         #define CF_INLINE static __inline__ __attribute__((always_inline))
 150     #elif defined(__GNUC__)
 151         #define CF_INLINE static __inline__
 152     #elif defined(__MWERKS__) || defined(__cplusplus)
 153         #define CF_INLINE static inline
 154     #elif defined(_MSC_VER)
 155         #define CF_INLINE static __inline
 156     #elif TARGET_OS_WIN32
 157         #define CF_INLINE static __inline__
 158     #endif
 159 #endif
 160
 161 // 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 the rename the functions, but this macro can be used to let the clang static analyzer know of any exceptions that cannot be fixed.
 162 #if defined(__clang__)
 163 #define CF_RETURNS_RETAINED __attribute__((cf_returns_retained))
 164 #else
 165 #define CF_RETURNS_RETAINED
 166 #endif
 167
 168
 169 CF_EXPORT double kCFCoreFoundationVersionNumber;
 170
 171 #if TARGET_OS_MAC
 172 #define kCFCoreFoundationVersionNumber10_0      196.40
 173 #define kCFCoreFoundationVersionNumber10_0_3    196.50
 174 #define kCFCoreFoundationVersionNumber10_1      226.00
 175 #define kCFCoreFoundationVersionNumber10_1_1    226.00
 176 /* Note the next three do not follow the usual numbering policy from the base release */
 177 #define kCFCoreFoundationVersionNumber10_1_2    227.20
 178 #define kCFCoreFoundationVersionNumber10_1_3    227.20
 179 #define kCFCoreFoundationVersionNumber10_1_4    227.30
 180 #define kCFCoreFoundationVersionNumber10_2      263.00
 181 #define kCFCoreFoundationVersionNumber10_2_1    263.10
 182 #define kCFCoreFoundationVersionNumber10_2_2    263.10
 183 #define kCFCoreFoundationVersionNumber10_2_3    263.30
 184 #define kCFCoreFoundationVersionNumber10_2_4    263.30
 185 #define kCFCoreFoundationVersionNumber10_2_5    263.50
 186 #define kCFCoreFoundationVersionNumber10_2_6    263.50
 187 #define kCFCoreFoundationVersionNumber10_2_7    263.50
 188 #define kCFCoreFoundationVersionNumber10_2_8    263.50
 189 #define kCFCoreFoundationVersionNumber10_3      299.00
 190 #define kCFCoreFoundationVersionNumber10_3_1    299.00
 191 #define kCFCoreFoundationVersionNumber10_3_2    299.00
 192 #define kCFCoreFoundationVersionNumber10_3_3    299.30
 193 #define kCFCoreFoundationVersionNumber10_3_4    299.31
 194 #define kCFCoreFoundationVersionNumber10_3_5    299.31
 195 #define kCFCoreFoundationVersionNumber10_3_6    299.32
 196 #define kCFCoreFoundationVersionNumber10_3_7    299.33
 197 #define kCFCoreFoundationVersionNumber10_3_8    299.33
 198 #define kCFCoreFoundationVersionNumber10_3_9    299.35
 199 #define kCFCoreFoundationVersionNumber10_4      368.00
 200 #define kCFCoreFoundationVersionNumber10_4_1    368.10
 201 #define kCFCoreFoundationVersionNumber10_4_2    368.11
 202 #define kCFCoreFoundationVersionNumber10_4_3    368.18
 203 #define kCFCoreFoundationVersionNumber10_4_4_Intel      368.26
 204 #define kCFCoreFoundationVersionNumber10_4_4_PowerPC    368.25
 205 #define kCFCoreFoundationVersionNumber10_4_5_Intel      368.26
 206 #define kCFCoreFoundationVersionNumber10_4_5_PowerPC    368.25
 207 #define kCFCoreFoundationVersionNumber10_4_6_Intel      368.26
 208 #define kCFCoreFoundationVersionNumber10_4_6_PowerPC    368.25
 209 #define kCFCoreFoundationVersionNumber10_4_7    368.27
 210 #define kCFCoreFoundationVersionNumber10_4_8    368.27
 211 #define kCFCoreFoundationVersionNumber10_4_9    368.28
 212 #define kCFCoreFoundationVersionNumber10_4_10   368.28
 213 #define kCFCoreFoundationVersionNumber10_4_11   368.31
 214 #define kCFCoreFoundationVersionNumber10_5      476.00
 215 #define kCFCoreFoundationVersionNumber10_5_1    476.00
 216 #define kCFCoreFoundationVersionNumber10_5_2    476.10
 217 #define kCFCoreFoundationVersionNumber10_5_3    476.13
 218 #define kCFCoreFoundationVersionNumber10_5_4    476.14
 219 #define kCFCoreFoundationVersionNumber10_5_5    476.15
 220 #define kCFCoreFoundationVersionNumber10_5_6    476.17
 221 #endif
 222
 223 #if TARGET_OS_IPHONE
 224 #define kCFCoreFoundationVersionNumber_iPhoneOS_2_0     478.23
 225 #define kCFCoreFoundationVersionNumber_iPhoneOS_2_1 478.26
 226 #define kCFCoreFoundationVersionNumber_iPhoneOS_2_2 478.29
 227 #endif
 228
 229 typedef unsigned long CFTypeID;
 230 typedef unsigned long CFOptionFlags;
 231 typedef unsigned long CFHashCode;
 232 typedef signed long CFIndex;
 233
 234 /* Base "type" of all "CF objects", and polymorphic functions on them */
 235 typedef const void * CFTypeRef;
 236
 237 typedef const struct __CFString * CFStringRef;
 238 typedef struct __CFString * CFMutableStringRef;
 239
 240 /*
 241         Type to mean any instance of a property list type;
 242         currently, CFString, CFData, CFNumber, CFBoolean, CFDate,
 243         CFArray, and CFDictionary.
 244 */
 245 typedef CFTypeRef CFPropertyListRef;
 246
 247 /* Values returned from comparison functions */
 248 enum {
 249     kCFCompareLessThan = -1,
 250     kCFCompareEqualTo = 0,
 251     kCFCompareGreaterThan = 1
 252 };
 253 typedef CFIndex CFComparisonResult;
 254
 255 /* A standard comparison function */
 256 typedef CFComparisonResult (*CFComparatorFunction)(const void *val1, const void *val2, void *context);
 257
 258 /* Constant used by some functions to indicate failed searches. */
 259 /* This is of type CFIndex. */
 260 enum {
 261     kCFNotFound = -1
 262 };
 263
 264
 265 /* Range type */
 266 typedef struct {
 267     CFIndex location;
 268     CFIndex length;
 269 } CFRange;
 270
 271 #if defined(CF_INLINE)
 272 CF_INLINE CFRange CFRangeMake(CFIndex loc, CFIndex len) {
 273     CFRange range;
 274     range.location = loc;
 275     range.length = len;
 276     return range;
 277 }
 278 #else
 279 #define CFRangeMake(LOC, LEN) __CFRangeMake(LOC, LEN)
 280 #endif
 281
 282 /* Private; do not use */
 283 CF_EXPORT
 284 CFRange __CFRangeMake(CFIndex loc, CFIndex len);
 285
 286
 287 #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED
 288 /* Null representant */
 289
 290 typedef const struct __CFNull * CFNullRef;
 291
 292 CF_EXPORT
 293 CFTypeID CFNullGetTypeID(void);
 294
 295 CF_EXPORT
 296 const CFNullRef kCFNull;        // the singleton null instance
 297
 298 #endif
 299
 300
 301 /* Allocator API
 302
 303    Most of the time when specifying an allocator to Create functions, the NULL
 304    argument indicates "use the default"; this is the same as using kCFAllocatorDefault
 305    or the return value from CFAllocatorGetDefault().  This assures that you will use
 306    the allocator in effect at that time.
 307
 308    You should rarely use kCFAllocatorSystemDefault, the default default allocator.
 309 */
 310 typedef const struct __CFAllocator * CFAllocatorRef;
 311
 312 /* This is a synonym for NULL, if you'd rather use a named constant. */
 313 CF_EXPORT
 314 const CFAllocatorRef kCFAllocatorDefault;
 315
 316 /* Default system allocator; you rarely need to use this. */
 317 CF_EXPORT
 318 const CFAllocatorRef kCFAllocatorSystemDefault;
 319
 320 /* This allocator uses malloc(), realloc(), and free(). This should not be
 321    generally used; stick to kCFAllocatorDefault whenever possible. This
 322    allocator is useful as the "bytesDeallocator" in CFData or
 323    "contentsDeallocator" in CFString where the memory was obtained as a
 324    result of malloc() type functions.
 325 */
 326 CF_EXPORT
 327 const CFAllocatorRef kCFAllocatorMalloc;
 328
 329 /* This allocator explicitly uses the default malloc zone, returned by
 330    malloc_default_zone(). It should only be used when an object is
 331    safe to be allocated in non-scanned memory.
 332  */
 333 CF_EXPORT
 334 const CFAllocatorRef kCFAllocatorMallocZone AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 335
 336 /* Null allocator which does nothing and allocates no memory. This allocator
 337    is useful as the "bytesDeallocator" in CFData or "contentsDeallocator"
 338    in CFString where the memory should not be freed.
 339 */
 340 CF_EXPORT
 341 const CFAllocatorRef kCFAllocatorNull;
 342
 343 /* Special allocator argument to CFAllocatorCreate() which means
 344    "use the functions given in the context to allocate the allocator
 345    itself as well".
 346 */
 347 CF_EXPORT
 348 const CFAllocatorRef kCFAllocatorUseContext;
 349
 350 typedef const void *    (*CFAllocatorRetainCallBack)(const void *info);
 351 typedef void            (*CFAllocatorReleaseCallBack)(const void *info);
 352 typedef CFStringRef     (*CFAllocatorCopyDescriptionCallBack)(const void *info);
 353 typedef void *          (*CFAllocatorAllocateCallBack)(CFIndex allocSize, CFOptionFlags hint, void *info);
 354 typedef void *          (*CFAllocatorReallocateCallBack)(void *ptr, CFIndex newsize, CFOptionFlags hint, void *info);
 355 typedef void            (*CFAllocatorDeallocateCallBack)(void *ptr, void *info);
 356 typedef CFIndex         (*CFAllocatorPreferredSizeCallBack)(CFIndex size, CFOptionFlags hint, void *info);
 357 typedef struct {
 358     CFIndex                             version;
 359     void *                              info;
 360     CFAllocatorRetainCallBack           retain;
 361     CFAllocatorReleaseCallBack          release;
 362     CFAllocatorCopyDescriptionCallBack  copyDescription;
 363     CFAllocatorAllocateCallBack         allocate;
 364     CFAllocatorReallocateCallBack       reallocate;
 365     CFAllocatorDeallocateCallBack       deallocate;
 366     CFAllocatorPreferredSizeCallBack    preferredSize;
 367 } CFAllocatorContext;
 368
 369 CF_EXPORT
 370 CFTypeID        CFAllocatorGetTypeID(void);
 371
 372 /*
 373         CFAllocatorSetDefault() sets the allocator that is used in the current
 374         thread whenever NULL is specified as an allocator argument. This means
 375         that most, if not all allocations will go through this allocator. It
 376         also means that any allocator set as the default needs to be ready to
 377         deal with arbitrary memory allocation requests; in addition, the size
 378         and number of requests will change between releases.
 379
 380         An allocator set as the default will never be released, even if later
 381         another allocator replaces it as the default. Not only is it impractical
 382         for it to be released (as there might be caches created under the covers
 383         that refer to the allocator), in general it's also safer and more
 384         efficient to keep it around.
 385
 386         If you wish to use a custom allocator in a context, it's best to provide
 387         it as the argument to the various creation functions rather than setting
 388         it as the default. Setting the default allocator is not encouraged.
 389
 390         If you do set an allocator as the default, either do it for all time in
 391         your app, or do it in a nested fashion (by restoring the previous allocator
 392         when you exit your context). The latter might be appropriate for plug-ins
 393         or libraries that wish to set the default allocator.
 394 */
 395 CF_EXPORT
 396 void CFAllocatorSetDefault(CFAllocatorRef allocator);
 397
 398 CF_EXPORT
 399 CFAllocatorRef CFAllocatorGetDefault(void);
 400
 401 CF_EXPORT
 402 CFAllocatorRef CFAllocatorCreate(CFAllocatorRef allocator, CFAllocatorContext *context);
 403
 404 CF_EXPORT
 405 void *CFAllocatorAllocate(CFAllocatorRef allocator, CFIndex size, CFOptionFlags hint);
 406
 407 CF_EXPORT
 408 void *CFAllocatorReallocate(CFAllocatorRef allocator, void *ptr, CFIndex newsize, CFOptionFlags hint);
 409
 410 CF_EXPORT
 411 void CFAllocatorDeallocate(CFAllocatorRef allocator, void *ptr);
 412
 413 CF_EXPORT
 414 CFIndex CFAllocatorGetPreferredSizeForSize(CFAllocatorRef allocator, CFIndex size, CFOptionFlags hint);
 415
 416 CF_EXPORT
 417 void CFAllocatorGetContext(CFAllocatorRef allocator, CFAllocatorContext *context);
 418
 419
 420 /* Polymorphic CF functions */
 421
 422 CF_EXPORT
 423 CFTypeID CFGetTypeID(CFTypeRef cf);
 424
 425 CF_EXPORT
 426 CFStringRef CFCopyTypeIDDescription(CFTypeID type_id);
 427
 428 CF_EXPORT
 429 CFTypeRef CFRetain(CFTypeRef cf);
 430
 431 CF_EXPORT
 432 void CFRelease(CFTypeRef cf);
 433
 434 CF_EXPORT
 435 CFIndex CFGetRetainCount(CFTypeRef cf);
 436
 437 CF_EXPORT
 438 CFTypeRef CFMakeCollectable(CFTypeRef cf) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 439
 440 CF_EXPORT
 441 Boolean CFEqual(CFTypeRef cf1, CFTypeRef cf2);
 442
 443 CF_EXPORT
 444 CFHashCode CFHash(CFTypeRef cf);
 445
 446 CF_EXPORT
 447 CFStringRef CFCopyDescription(CFTypeRef cf);
 448
 449 CF_EXPORT
 450 CFAllocatorRef CFGetAllocator(CFTypeRef cf);
 451
 452 CF_EXTERN_C_END
 453
 454 #endif /* ! __COREFOUNDATION_CFBASE__ */
 455