CFBase.h

   1 /*
   2  * Copyright (c) 2010 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 #define kCFCoreFoundationVersionNumber10_5_7    476.18
 223 #define kCFCoreFoundationVersionNumber10_5_8    476.19
 224 #define kCFCoreFoundationVersionNumber10_6      550.00
 225 #define kCFCoreFoundationVersionNumber10_6_1    550.00
 226 #define kCFCoreFoundationVersionNumber10_6_2    550.13
 227 #define kCFCoreFoundationVersionNumber10_6_3    550.19
 228 #endif
 229
 230 #if TARGET_OS_IPHONE
 231 #define kCFCoreFoundationVersionNumber_iPhoneOS_2_0     478.23
 232 #define kCFCoreFoundationVersionNumber_iPhoneOS_2_1 478.26
 233 #define kCFCoreFoundationVersionNumber_iPhoneOS_2_2 478.29
 234 #define kCFCoreFoundationVersionNumber_iPhoneOS_3_0 478.47
 235 #define kCFCoreFoundationVersionNumber_iPhoneOS_3_1 478.52
 236 #define kCFCoreFoundationVersionNumber_iPhoneOS_3_2 478.61
 237 #endif
 238
 239 typedef unsigned long CFTypeID;
 240 typedef unsigned long CFOptionFlags;
 241 typedef unsigned long CFHashCode;
 242 typedef signed long CFIndex;
 243
 244 /* Base "type" of all "CF objects", and polymorphic functions on them */
 245 typedef const void * CFTypeRef;
 246
 247 typedef const struct __CFString * CFStringRef;
 248 typedef struct __CFString * CFMutableStringRef;
 249
 250 /*
 251         Type to mean any instance of a property list type;
 252         currently, CFString, CFData, CFNumber, CFBoolean, CFDate,
 253         CFArray, and CFDictionary.
 254 */
 255 typedef CFTypeRef CFPropertyListRef;
 256
 257 /* Values returned from comparison functions */
 258 enum {
 259     kCFCompareLessThan = -1,
 260     kCFCompareEqualTo = 0,
 261     kCFCompareGreaterThan = 1
 262 };
 263 typedef CFIndex CFComparisonResult;
 264
 265 /* A standard comparison function */
 266 typedef CFComparisonResult (*CFComparatorFunction)(const void *val1, const void *val2, void *context);
 267
 268 /* Constant used by some functions to indicate failed searches. */
 269 /* This is of type CFIndex. */
 270 enum {
 271     kCFNotFound = -1
 272 };
 273
 274
 275 /* Range type */
 276 typedef struct {
 277     CFIndex location;
 278     CFIndex length;
 279 } CFRange;
 280
 281 #if defined(CF_INLINE)
 282 CF_INLINE CFRange CFRangeMake(CFIndex loc, CFIndex len) {
 283     CFRange range;
 284     range.location = loc;
 285     range.length = len;
 286     return range;
 287 }
 288 #else
 289 #define CFRangeMake(LOC, LEN) __CFRangeMake(LOC, LEN)
 290 #endif
 291
 292 /* Private; do not use */
 293 CF_EXPORT
 294 CFRange __CFRangeMake(CFIndex loc, CFIndex len);
 295
 296
 297 #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED
 298 /* Null representant */
 299
 300 typedef const struct __CFNull * CFNullRef;
 301
 302 CF_EXPORT
 303 CFTypeID CFNullGetTypeID(void);
 304
 305 CF_EXPORT
 306 const CFNullRef kCFNull;        // the singleton null instance
 307
 308 #endif
 309
 310
 311 /* Allocator API
 312
 313    Most of the time when specifying an allocator to Create functions, the NULL
 314    argument indicates "use the default"; this is the same as using kCFAllocatorDefault
 315    or the return value from CFAllocatorGetDefault().  This assures that you will use
 316    the allocator in effect at that time.
 317
 318    You should rarely use kCFAllocatorSystemDefault, the default default allocator.
 319 */
 320 typedef const struct __CFAllocator * CFAllocatorRef;
 321
 322 /* This is a synonym for NULL, if you'd rather use a named constant. */
 323 CF_EXPORT
 324 const CFAllocatorRef kCFAllocatorDefault;
 325
 326 /* Default system allocator; you rarely need to use this. */
 327 CF_EXPORT
 328 const CFAllocatorRef kCFAllocatorSystemDefault;
 329
 330 /* This allocator uses malloc(), realloc(), and free(). This should not be
 331    generally used; stick to kCFAllocatorDefault whenever possible. This
 332    allocator is useful as the "bytesDeallocator" in CFData or
 333    "contentsDeallocator" in CFString where the memory was obtained as a
 334    result of malloc() type functions.
 335 */
 336 CF_EXPORT
 337 const CFAllocatorRef kCFAllocatorMalloc;
 338
 339 /* This allocator explicitly uses the default malloc zone, returned by
 340    malloc_default_zone(). It should only be used when an object is
 341    safe to be allocated in non-scanned memory.
 342  */
 343 CF_EXPORT
 344 const CFAllocatorRef kCFAllocatorMallocZone AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 345
 346 /* Null allocator which does nothing and allocates no memory. This allocator
 347    is useful as the "bytesDeallocator" in CFData or "contentsDeallocator"
 348    in CFString where the memory should not be freed.
 349 */
 350 CF_EXPORT
 351 const CFAllocatorRef kCFAllocatorNull;
 352
 353 /* Special allocator argument to CFAllocatorCreate() which means
 354    "use the functions given in the context to allocate the allocator
 355    itself as well".
 356 */
 357 CF_EXPORT
 358 const CFAllocatorRef kCFAllocatorUseContext;
 359
 360 typedef const void *    (*CFAllocatorRetainCallBack)(const void *info);
 361 typedef void            (*CFAllocatorReleaseCallBack)(const void *info);
 362 typedef CFStringRef     (*CFAllocatorCopyDescriptionCallBack)(const void *info);
 363 typedef void *          (*CFAllocatorAllocateCallBack)(CFIndex allocSize, CFOptionFlags hint, void *info);
 364 typedef void *          (*CFAllocatorReallocateCallBack)(void *ptr, CFIndex newsize, CFOptionFlags hint, void *info);
 365 typedef void            (*CFAllocatorDeallocateCallBack)(void *ptr, void *info);
 366 typedef CFIndex         (*CFAllocatorPreferredSizeCallBack)(CFIndex size, CFOptionFlags hint, void *info);
 367 typedef struct {
 368     CFIndex                             version;
 369     void *                              info;
 370     CFAllocatorRetainCallBack           retain;
 371     CFAllocatorReleaseCallBack          release;
 372     CFAllocatorCopyDescriptionCallBack  copyDescription;
 373     CFAllocatorAllocateCallBack         allocate;
 374     CFAllocatorReallocateCallBack       reallocate;
 375     CFAllocatorDeallocateCallBack       deallocate;
 376     CFAllocatorPreferredSizeCallBack    preferredSize;
 377 } CFAllocatorContext;
 378
 379 CF_EXPORT
 380 CFTypeID        CFAllocatorGetTypeID(void);
 381
 382 /*
 383         CFAllocatorSetDefault() sets the allocator that is used in the current
 384         thread whenever NULL is specified as an allocator argument. This means
 385         that most, if not all allocations will go through this allocator. It
 386         also means that any allocator set as the default needs to be ready to
 387         deal with arbitrary memory allocation requests; in addition, the size
 388         and number of requests will change between releases.
 389
 390         An allocator set as the default will never be released, even if later
 391         another allocator replaces it as the default. Not only is it impractical
 392         for it to be released (as there might be caches created under the covers
 393         that refer to the allocator), in general it's also safer and more
 394         efficient to keep it around.
 395
 396         If you wish to use a custom allocator in a context, it's best to provide
 397         it as the argument to the various creation functions rather than setting
 398         it as the default. Setting the default allocator is not encouraged.
 399
 400         If you do set an allocator as the default, either do it for all time in
 401         your app, or do it in a nested fashion (by restoring the previous allocator
 402         when you exit your context). The latter might be appropriate for plug-ins
 403         or libraries that wish to set the default allocator.
 404 */
 405 CF_EXPORT
 406 void CFAllocatorSetDefault(CFAllocatorRef allocator);
 407
 408 CF_EXPORT
 409 CFAllocatorRef CFAllocatorGetDefault(void);
 410
 411 CF_EXPORT
 412 CFAllocatorRef CFAllocatorCreate(CFAllocatorRef allocator, CFAllocatorContext *context);
 413
 414 CF_EXPORT
 415 void *CFAllocatorAllocate(CFAllocatorRef allocator, CFIndex size, CFOptionFlags hint);
 416
 417 CF_EXPORT
 418 void *CFAllocatorReallocate(CFAllocatorRef allocator, void *ptr, CFIndex newsize, CFOptionFlags hint);
 419
 420 CF_EXPORT
 421 void CFAllocatorDeallocate(CFAllocatorRef allocator, void *ptr);
 422
 423 CF_EXPORT
 424 CFIndex CFAllocatorGetPreferredSizeForSize(CFAllocatorRef allocator, CFIndex size, CFOptionFlags hint);
 425
 426 CF_EXPORT
 427 void CFAllocatorGetContext(CFAllocatorRef allocator, CFAllocatorContext *context);
 428
 429
 430 /* Polymorphic CF functions */
 431
 432 CF_EXPORT
 433 CFTypeID CFGetTypeID(CFTypeRef cf);
 434
 435 CF_EXPORT
 436 CFStringRef CFCopyTypeIDDescription(CFTypeID type_id);
 437
 438 CF_EXPORT
 439 CFTypeRef CFRetain(CFTypeRef cf);
 440
 441 CF_EXPORT
 442 void CFRelease(CFTypeRef cf);
 443
 444 CF_EXPORT
 445 CFIndex CFGetRetainCount(CFTypeRef cf);
 446
 447 CF_EXPORT
 448 CFTypeRef CFMakeCollectable(CFTypeRef cf) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 449
 450 CF_EXPORT
 451 Boolean CFEqual(CFTypeRef cf1, CFTypeRef cf2);
 452
 453 CF_EXPORT
 454 CFHashCode CFHash(CFTypeRef cf);
 455
 456 CF_EXPORT
 457 CFStringRef CFCopyDescription(CFTypeRef cf);
 458
 459 CF_EXPORT
 460 CFAllocatorRef CFGetAllocator(CFTypeRef cf);
 461
 462 CF_EXTERN_C_END
 463
 464 #endif /* ! __COREFOUNDATION_CFBASE__ */
 465