CFBase.h

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