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__) && (__GNUC__ == 4) && !defined(DEBUG)
 134         #define CF_INLINE static __inline__ __attribute__((always_inline))
 135     #elif defined(__GNUC__)
 136     #define CF_INLINE static __inline__
 137     #elif defined(__MWERKS__) || defined(__cplusplus)
 138         #define CF_INLINE static inline
 139     #elif defined(_MSC_VER)
 140         #define CF_INLINE static __inline
 141     #elif defined(__WIN32__)
 142         #define CF_INLINE static __inline__
 143     #endif
 144 #endif
 145
 146
 147 CF_EXPORT double kCFCoreFoundationVersionNumber;
 148
 149 #define kCFCoreFoundationVersionNumber10_0 196.4
 150 #define kCFCoreFoundationVersionNumber10_0_3 196.5
 151 #define kCFCoreFoundationVersionNumber10_1 226.0
 152 /* Note the next two do not follow the usual numbering policy from the base release */
 153 #define kCFCoreFoundationVersionNumber10_1_2 227.2
 154 #define kCFCoreFoundationVersionNumber10_1_4 227.3
 155 #define kCFCoreFoundationVersionNumber10_2 263.0
 156 #define kCFCoreFoundationVersionNumber10_3 299.0
 157 #define kCFCoreFoundationVersionNumber10_3_3 299.3
 158 #define kCFCoreFoundationVersionNumber10_3_4 299.31
 159
 160 #if defined(__ppc64__)
 161 typedef UInt32 CFTypeID;
 162 typedef UInt64 CFOptionFlags;
 163 typedef UInt32 CFHashCode;
 164 typedef SInt64 CFIndex;
 165 #else
 166 typedef UInt32 CFTypeID;
 167 typedef UInt32 CFOptionFlags;
 168 typedef UInt32 CFHashCode;
 169 typedef SInt32 CFIndex;
 170 #endif
 171
 172 /* Base "type" of all "CF objects", and polymorphic functions on them */
 173 typedef const void * CFTypeRef;
 174
 175 typedef const struct __CFString * CFStringRef;
 176 typedef struct __CFString * CFMutableStringRef;
 177
 178 /*
 179         Type to mean any instance of a property list type;
 180         currently, CFString, CFData, CFNumber, CFBoolean, CFDate,
 181         CFArray, and CFDictionary.
 182 */
 183 typedef CFTypeRef CFPropertyListRef;
 184
 185 /* Values returned from comparison functions */
 186 typedef enum {
 187     kCFCompareLessThan = -1,
 188     kCFCompareEqualTo = 0,
 189     kCFCompareGreaterThan = 1
 190 } CFComparisonResult;
 191
 192 /* A standard comparison function */
 193 typedef CFComparisonResult (*CFComparatorFunction)(const void *val1, const void *val2, void *context);
 194
 195 /* Constant used by some functions to indicate failed searches. */
 196 /* This is of type CFIndex. */
 197 enum {
 198     kCFNotFound = -1
 199 };
 200
 201
 202 /* Range type */
 203 typedef struct {
 204     CFIndex location;
 205     CFIndex length;
 206 } CFRange;
 207
 208 #if defined(CF_INLINE)
 209 CF_INLINE CFRange CFRangeMake(CFIndex loc, CFIndex len) {
 210     CFRange range;
 211     range.location = loc;
 212     range.length = len;
 213     return range;
 214 }
 215 #else
 216 #define CFRangeMake(LOC, LEN) __CFRangeMake(LOC, LEN)
 217 #endif
 218
 219 /* Private; do not use */
 220 CF_EXPORT
 221 CFRange __CFRangeMake(CFIndex loc, CFIndex len);
 222
 223
 224 #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED
 225 /* Null representant */
 226
 227 typedef const struct __CFNull * CFNullRef;
 228
 229 CF_EXPORT
 230 CFTypeID CFNullGetTypeID(void);
 231
 232 CF_EXPORT
 233 const CFNullRef kCFNull;        // the singleton null instance
 234
 235 #endif
 236
 237
 238 /* Allocator API
 239
 240    Most of the time when specifying an allocator to Create functions, the NULL
 241    argument indicates "use the default"; this is the same as using kCFAllocatorDefault
 242    or the return value from CFAllocatorGetDefault().  This assures that you will use
 243    the allocator in effect at that time.
 244
 245    You should rarely use kCFAllocatorSystemDefault, the default default allocator.
 246 */
 247 typedef const struct __CFAllocator * CFAllocatorRef;
 248
 249 /* This is a synonym for NULL, if you'd rather use a named constant. */
 250 CF_EXPORT
 251 const CFAllocatorRef kCFAllocatorDefault;
 252
 253 /* Default system allocator; you rarely need to use this. */
 254 CF_EXPORT
 255 const CFAllocatorRef kCFAllocatorSystemDefault;
 256
 257 /* This allocator uses malloc(), realloc(), and free(). This should not be
 258    generally used; stick to kCFAllocatorDefault whenever possible. This
 259    allocator is useful as the "bytesDeallocator" in CFData or
 260    "contentsDeallocator" in CFString where the memory was obtained as a
 261    result of malloc() type functions.
 262 */
 263 CF_EXPORT
 264 const CFAllocatorRef kCFAllocatorMalloc;
 265
 266 /* This allocator explicitly uses the default malloc zone, returned by
 267    malloc_default_zone(). It should only be used when an object is
 268    safe to be allocated in non-scanned memory.
 269  */
 270 CF_EXPORT
 271 const CFAllocatorRef kCFAllocatorMallocZone AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 272
 273 /* Null allocator which does nothing and allocates no memory. This allocator
 274    is useful as the "bytesDeallocator" in CFData or "contentsDeallocator"
 275    in CFString where the memory should not be freed.
 276 */
 277 CF_EXPORT
 278 const CFAllocatorRef kCFAllocatorNull;
 279
 280 /* Special allocator argument to CFAllocatorCreate() which means
 281    "use the functions given in the context to allocate the allocator
 282    itself as well".
 283 */
 284 CF_EXPORT
 285 const CFAllocatorRef kCFAllocatorUseContext;
 286
 287 typedef const void *    (*CFAllocatorRetainCallBack)(const void *info);
 288 typedef void            (*CFAllocatorReleaseCallBack)(const void *info);
 289 typedef CFStringRef     (*CFAllocatorCopyDescriptionCallBack)(const void *info);
 290 typedef void *          (*CFAllocatorAllocateCallBack)(CFIndex allocSize, CFOptionFlags hint, void *info);
 291 typedef void *          (*CFAllocatorReallocateCallBack)(void *ptr, CFIndex newsize, CFOptionFlags hint, void *info);
 292 typedef void            (*CFAllocatorDeallocateCallBack)(void *ptr, void *info);
 293 typedef CFIndex         (*CFAllocatorPreferredSizeCallBack)(CFIndex size, CFOptionFlags hint, void *info);
 294 typedef struct {
 295     CFIndex                             version;
 296     void *                              info;
 297     CFAllocatorRetainCallBack           retain;
 298     CFAllocatorReleaseCallBack          release;
 299     CFAllocatorCopyDescriptionCallBack  copyDescription;
 300     CFAllocatorAllocateCallBack         allocate;
 301     CFAllocatorReallocateCallBack       reallocate;
 302     CFAllocatorDeallocateCallBack       deallocate;
 303     CFAllocatorPreferredSizeCallBack    preferredSize;
 304 } CFAllocatorContext;
 305
 306 CF_EXPORT
 307 CFTypeID        CFAllocatorGetTypeID(void);
 308
 309 /*
 310         CFAllocatorSetDefault() sets the allocator that is used in the current
 311         thread whenever NULL is specified as an allocator argument. This means
 312         that most, if not all allocations will go through this allocator. It
 313         also means that any allocator set as the default needs to be ready to
 314         deal with arbitrary memory allocation requests; in addition, the size
 315         and number of requests will change between releases.
 316
 317         An allocator set as the default will never be released, even if later
 318         another allocator replaces it as the default. Not only is it impractical
 319         for it to be released (as there might be caches created under the covers
 320         that refer to the allocator), in general it's also safer and more
 321         efficient to keep it around.
 322
 323         If you wish to use a custom allocator in a context, it's best to provide
 324         it as the argument to the various creation functions rather than setting
 325         it as the default. Setting the default allocator is not encouraged.
 326
 327         If you do set an allocator as the default, either do it for all time in
 328         your app, or do it in a nested fashion (by restoring the previous allocator
 329         when you exit your context). The latter might be appropriate for plug-ins
 330         or libraries that wish to set the default allocator.
 331 */
 332 CF_EXPORT
 333 void CFAllocatorSetDefault(CFAllocatorRef allocator);
 334
 335 CF_EXPORT
 336 CFAllocatorRef CFAllocatorGetDefault(void);
 337
 338 CF_EXPORT
 339 CFAllocatorRef CFAllocatorCreate(CFAllocatorRef allocator, CFAllocatorContext *context);
 340
 341 CF_EXPORT
 342 void *CFAllocatorAllocate(CFAllocatorRef allocator, CFIndex size, CFOptionFlags hint);
 343
 344 CF_EXPORT
 345 void *CFAllocatorReallocate(CFAllocatorRef allocator, void *ptr, CFIndex newsize, CFOptionFlags hint);
 346
 347 CF_EXPORT
 348 void CFAllocatorDeallocate(CFAllocatorRef allocator, void *ptr);
 349
 350 CF_EXPORT
 351 CFIndex CFAllocatorGetPreferredSizeForSize(CFAllocatorRef allocator, CFIndex size, CFOptionFlags hint);
 352
 353 CF_EXPORT
 354 void CFAllocatorGetContext(CFAllocatorRef allocator, CFAllocatorContext *context);
 355
 356
 357 /* Polymorphic CF functions */
 358
 359 CF_EXPORT
 360 CFTypeID CFGetTypeID(CFTypeRef cf);
 361
 362 CF_EXPORT
 363 CFStringRef CFCopyTypeIDDescription(CFTypeID type_id);
 364
 365 CF_EXPORT
 366 CFTypeRef CFRetain(CFTypeRef cf);
 367
 368 CF_EXPORT
 369 void CFRelease(CFTypeRef cf);
 370
 371 CF_EXPORT
 372 CFIndex CFGetRetainCount(CFTypeRef cf);
 373
 374 CF_EXPORT
 375 CFTypeRef CFMakeCollectable(CFTypeRef cf) AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER;
 376
 377 CF_EXPORT
 378 Boolean CFEqual(CFTypeRef cf1, CFTypeRef cf2);
 379
 380 CF_EXPORT
 381 CFHashCode CFHash(CFTypeRef cf);
 382
 383 CF_EXPORT
 384 CFStringRef CFCopyDescription(CFTypeRef cf);
 385
 386 CF_EXPORT
 387 CFAllocatorRef CFGetAllocator(CFTypeRef cf);
 388
 389 #if defined(__cplusplus)
 390 }
 391 #endif
 392
 393 #endif /* ! __COREFOUNDATION_CFBASE__ */
 394