Base.subproj/CFBase.h

   1 /*
   2  * Copyright (c) 2005 Apple Computer, 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-2005, 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(__WIN32__)
  39 #include <windows.h>
  40 #endif
  41
  42 #if defined(__GNUC__)
  43 #include <stdint.h>
  44 #include <stdbool.h>
  45 #elif defined(__WIN32__)
  46 // mostly for the benefit of MSVC
  47 #include <GNUCompatibility/stdint.h>
  48 #include <GNUCompatibility/stdbool.h>
  49 #endif
  50 #include <AvailabilityMacros.h>
  51
  52     #if defined(__MACH__)
  53         #include <CarbonCore/MacTypes.h>
  54     #endif
  55
  56 #if !defined(__MACTYPES__)
  57     typedef unsigned char           Boolean;
  58     typedef unsigned char           UInt8;
  59     typedef signed char             SInt8;
  60     typedef unsigned short          UInt16;
  61     typedef signed short            SInt16;
  62     typedef unsigned long           UInt32;
  63     typedef signed long             SInt32;
  64     typedef uint64_t                UInt64;
  65     typedef int64_t                 SInt64;
  66     typedef float                   Float32;
  67     typedef double                  Float64;
  68     typedef unsigned short          UniChar;
  69     typedef unsigned char *         StringPtr;
  70     typedef const unsigned char *   ConstStringPtr;
  71     typedef unsigned char           Str255[256];
  72     typedef const unsigned char *   ConstStr255Param;
  73     typedef SInt16                  OSErr;
  74     typedef SInt32                  OSStatus;
  75 #endif
  76 #if !defined(__MACTYPES__) || (defined(UNIVERSAL_INTERFACES_VERSION) && UNIVERSAL_INTERFACES_VERSION < 0x0340)
  77     typedef UInt32                  UTF32Char;
  78     typedef UInt16                  UTF16Char;
  79     typedef UInt8                   UTF8Char;
  80 #endif
  81
  82
  83 #if defined(__cplusplus)
  84 extern "C" {
  85 #endif
  86
  87 #ifndef NULL
  88 #ifdef __GNUG__
  89 #define NULL __null
  90 #else /* ! __GNUG__ */
  91 #ifndef __cplusplus
  92 #define NULL ((void *)0)
  93 #else /* __cplusplus */
  94 #define NULL 0
  95 #endif /* ! __cplusplus */
  96 #endif /* __GNUG__ */
  97 #endif /* ! NULL */
  98
  99 #if !defined(TRUE)
 100     #define TRUE        1
 101 #endif
 102
 103 #if !defined(FALSE)
 104     #define FALSE       0
 105 #endif
 106
 107 #if defined(__WIN32__)
 108     #undef CF_EXPORT
 109 /*
 110     We don't build as a library now, but this would be the starting point.
 111     #if defined(CF_BUILDING_CF_AS_LIB)
 112     // we're building CF as a library
 113     #define CF_EXPORT   extern
 114     #elif defined(CF_BUILDING_CF)
 115     // we're building CF as a DLL
 116 */
 117     #if defined(CF_BUILDING_CF)
 118         #define CF_EXPORT __declspec(dllexport) extern
 119     #else
 120         #define CF_EXPORT __declspec(dllimport) extern
 121     #endif
 122 #elif defined(macintosh)
 123     #if defined(__MWERKS__)
 124         #define CF_EXPORT __declspec(export) extern
 125     #endif
 126 #endif
 127
 128 #if !defined(CF_EXPORT)
 129     #define CF_EXPORT extern
 130 #endif
 131
 132 #if !defined(CF_INLINE)
 133     #if defined(__GNUC__)
 134         #define CF_INLINE static __inline__
 135     #elif defined(__MWERKS__) || defined(__cplusplus)
 136         #define CF_INLINE static inline
 137     #elif defined(_MSC_VER)
 138         #define CF_INLINE static __inline
 139     #elif defined(__WIN32__)
 140         #define CF_INLINE static __inline__
 141     #endif
 142 #endif
 143
 144
 145 CF_EXPORT double kCFCoreFoundationVersionNumber;
 146
 147 #define kCFCoreFoundationVersionNumber10_0 196.4
 148 #define kCFCoreFoundationVersionNumber10_0_3 196.5
 149 #define kCFCoreFoundationVersionNumber10_1 226.0
 150 /* Note the next two do not follow the usual numbering policy from the base release */
 151 #define kCFCoreFoundationVersionNumber10_1_2 227.2
 152 #define kCFCoreFoundationVersionNumber10_1_4 227.3
 153 #define kCFCoreFoundationVersionNumber10_2 263.0
 154 #define kCFCoreFoundationVersionNumber10_3 299.0
 155 #define kCFCoreFoundationVersionNumber10_3_3 299.3
 156 #define kCFCoreFoundationVersionNumber10_3_4 299.31
 157
 158 #if defined(__ppc64__)
 159 typedef UInt32 CFTypeID;
 160 typedef UInt64 CFOptionFlags;
 161 typedef UInt32 CFHashCode;
 162 typedef SInt64 CFIndex;
 163 #else
 164 typedef UInt32 CFTypeID;
 165 typedef UInt32 CFOptionFlags;
 166 typedef UInt32 CFHashCode;
 167 typedef SInt32 CFIndex;
 168 #endif
 169
 170 /* Base "type" of all "CF objects", and polymorphic functions on them */
 171 typedef const void * CFTypeRef;
 172
 173 typedef const struct __CFString * CFStringRef;
 174 typedef struct __CFString * CFMutableStringRef;
 175
 176 /*
 177         Type to mean any instance of a property list type;
 178         currently, CFString, CFData, CFNumber, CFBoolean, CFDate,
 179         CFArray, and CFDictionary.
 180 */
 181 typedef CFTypeRef CFPropertyListRef;
 182
 183 /* Values returned from comparison functions */
 184 typedef enum {
 185     kCFCompareLessThan = -1,
 186     kCFCompareEqualTo = 0,
 187     kCFCompareGreaterThan = 1
 188 } CFComparisonResult;
 189
 190 /* A standard comparison function */
 191 typedef CFComparisonResult (*CFComparatorFunction)(const void *val1, const void *val2, void *context);
 192
 193 /* Constant used by some functions to indicate failed searches. */
 194 /* This is of type CFIndex. */
 195 enum {
 196     kCFNotFound = -1
 197 };
 198
 199
 200 /* Range type */
 201 typedef struct {
 202     CFIndex location;
 203     CFIndex length;
 204 } CFRange;
 205
 206 #if defined(CF_INLINE)
 207 CF_INLINE CFRange CFRangeMake(CFIndex loc, CFIndex len) {
 208     CFRange range;
 209     range.location = loc;
 210     range.length = len;
 211     return range;
 212 }
 213 #else
 214 #define CFRangeMake(LOC, LEN) __CFRangeMake(LOC, LEN)
 215 #endif
 216
 217 /* Private; do not use */
 218 CF_EXPORT
 219 CFRange __CFRangeMake(CFIndex loc, CFIndex len);
 220
 221
 222 #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED
 223 /* Null representant */
 224
 225 typedef const struct __CFNull * CFNullRef;
 226
 227 CF_EXPORT
 228 CFTypeID CFNullGetTypeID(void);
 229
 230 CF_EXPORT
 231 const CFNullRef kCFNull;        // the singleton null instance
 232
 233 #endif
 234
 235
 236 /* Allocator API
 237
 238    Most of the time when specifying an allocator to Create functions, the NULL
 239    argument indicates "use the default"; this is the same as using kCFAllocatorDefault
 240    or the return value from CFAllocatorGetDefault().  This assures that you will use
 241    the allocator in effect at that time.
 242
 243    You should rarely use kCFAllocatorSystemDefault, the default default allocator.
 244 */
 245 typedef const struct __CFAllocator * CFAllocatorRef;
 246
 247 /* This is a synonym for NULL, if you'd rather use a named constant. */
 248 CF_EXPORT
 249 const CFAllocatorRef kCFAllocatorDefault;
 250
 251 /* Default system allocator; you rarely need to use this. */
 252 CF_EXPORT
 253 const CFAllocatorRef kCFAllocatorSystemDefault;
 254
 255 /* This allocator uses malloc(), realloc(), and free(). This should not be
 256    generally used; stick to kCFAllocatorDefault whenever possible. This
 257    allocator is useful as the "bytesDeallocator" in CFData or
 258    "contentsDeallocator" in CFString where the memory was obtained as a
 259    result of malloc() type functions.
 260 */
 261 CF_EXPORT
 262 const CFAllocatorRef kCFAllocatorMalloc;
 263
 264 /* This allocator explicitly uses the default malloc zone, returned by
 265    malloc_default_zone(). It should only be used when an object is
 266    safe to be allocated in non-scanned memory.
 267  */
 268 CF_EXPORT
 269 const CFAllocatorRef kCFAllocatorMallocZone AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 270
 271 /* Null allocator which does nothing and allocates no memory. This allocator
 272    is useful as the "bytesDeallocator" in CFData or "contentsDeallocator"
 273    in CFString where the memory should not be freed.
 274 */
 275 CF_EXPORT
 276 const CFAllocatorRef kCFAllocatorNull;
 277
 278 /* Special allocator argument to CFAllocatorCreate() which means
 279    "use the functions given in the context to allocate the allocator
 280    itself as well".
 281 */
 282 CF_EXPORT
 283 const CFAllocatorRef kCFAllocatorUseContext;
 284
 285 typedef const void *    (*CFAllocatorRetainCallBack)(const void *info);
 286 typedef void            (*CFAllocatorReleaseCallBack)(const void *info);
 287 typedef CFStringRef     (*CFAllocatorCopyDescriptionCallBack)(const void *info);
 288 typedef void *          (*CFAllocatorAllocateCallBack)(CFIndex allocSize, CFOptionFlags hint, void *info);
 289 typedef void *          (*CFAllocatorReallocateCallBack)(void *ptr, CFIndex newsize, CFOptionFlags hint, void *info);
 290 typedef void            (*CFAllocatorDeallocateCallBack)(void *ptr, void *info);
 291 typedef CFIndex         (*CFAllocatorPreferredSizeCallBack)(CFIndex size, CFOptionFlags hint, void *info);
 292 typedef struct {
 293     CFIndex                             version;
 294     void *                              info;
 295     CFAllocatorRetainCallBack           retain;
 296     CFAllocatorReleaseCallBack          release;
 297     CFAllocatorCopyDescriptionCallBack  copyDescription;
 298     CFAllocatorAllocateCallBack         allocate;
 299     CFAllocatorReallocateCallBack       reallocate;
 300     CFAllocatorDeallocateCallBack       deallocate;
 301     CFAllocatorPreferredSizeCallBack    preferredSize;
 302 } CFAllocatorContext;
 303
 304 CF_EXPORT
 305 CFTypeID        CFAllocatorGetTypeID(void);
 306
 307 /*
 308         CFAllocatorSetDefault() sets the allocator that is used in the current
 309         thread whenever NULL is specified as an allocator argument. This means
 310         that most, if not all allocations will go through this allocator. It
 311         also means that any allocator set as the default needs to be ready to
 312         deal with arbitrary memory allocation requests; in addition, the size
 313         and number of requests will change between releases.
 314
 315         An allocator set as the default will never be released, even if later
 316         another allocator replaces it as the default. Not only is it impractical
 317         for it to be released (as there might be caches created under the covers
 318         that refer to the allocator), in general it's also safer and more
 319         efficient to keep it around.
 320
 321         If you wish to use a custom allocator in a context, it's best to provide
 322         it as the argument to the various creation functions rather than setting
 323         it as the default. Setting the default allocator is not encouraged.
 324
 325         If you do set an allocator as the default, either do it for all time in
 326         your app, or do it in a nested fashion (by restoring the previous allocator
 327         when you exit your context). The latter might be appropriate for plug-ins
 328         or libraries that wish to set the default allocator.
 329 */
 330 CF_EXPORT
 331 void CFAllocatorSetDefault(CFAllocatorRef allocator);
 332
 333 CF_EXPORT
 334 CFAllocatorRef CFAllocatorGetDefault(void);
 335
 336 CF_EXPORT
 337 CFAllocatorRef CFAllocatorCreate(CFAllocatorRef allocator, CFAllocatorContext *context);
 338
 339 CF_EXPORT
 340 void *CFAllocatorAllocate(CFAllocatorRef allocator, CFIndex size, CFOptionFlags hint);
 341
 342 CF_EXPORT
 343 void *CFAllocatorReallocate(CFAllocatorRef allocator, void *ptr, CFIndex newsize, CFOptionFlags hint);
 344
 345 CF_EXPORT
 346 void CFAllocatorDeallocate(CFAllocatorRef allocator, void *ptr);
 347
 348 CF_EXPORT
 349 CFIndex CFAllocatorGetPreferredSizeForSize(CFAllocatorRef allocator, CFIndex size, CFOptionFlags hint);
 350
 351 CF_EXPORT
 352 void CFAllocatorGetContext(CFAllocatorRef allocator, CFAllocatorContext *context);
 353
 354
 355 /* Polymorphic CF functions */
 356
 357 CF_EXPORT
 358 CFTypeID CFGetTypeID(CFTypeRef cf);
 359
 360 CF_EXPORT
 361 CFStringRef CFCopyTypeIDDescription(CFTypeID type_id);
 362
 363 CF_EXPORT
 364 CFTypeRef CFRetain(CFTypeRef cf);
 365
 366 CF_EXPORT
 367 void CFRelease(CFTypeRef cf);
 368
 369 CF_EXPORT
 370 CFIndex CFGetRetainCount(CFTypeRef cf);
 371
 372 CF_EXPORT
 373 CFTypeRef CFMakeCollectable(CFTypeRef cf) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 374
 375 CF_EXPORT
 376 Boolean CFEqual(CFTypeRef cf1, CFTypeRef cf2);
 377
 378 CF_EXPORT
 379 CFHashCode CFHash(CFTypeRef cf);
 380
 381 CF_EXPORT
 382 CFStringRef CFCopyDescription(CFTypeRef cf);
 383
 384 CF_EXPORT
 385 CFAllocatorRef CFGetAllocator(CFTypeRef cf);
 386
 387 #if defined(__cplusplus)
 388 }
 389 #endif
 390
 391 #endif /* ! __COREFOUNDATION_CFBASE__ */
 392