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