Base.subproj/CFBase.h

   1 /*
   2  * Copyright (c) 2003 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25 /*      CFBase.h
  26         Copyright (c) 1998-2003, Apple, Inc. All rights reserved.
  27 */
  28
  29 #if !defined(__COREFOUNDATION_CFBASE__)
  30 #define __COREFOUNDATION_CFBASE__ 1
  31
  32 #if defined(__WIN32__)
  33 #include <windows.h>
  34 #endif
  35
  36 #include <stdint.h>
  37 #include <stdbool.h>
  38 #include <AvailabilityMacros.h>
  39
  40 #if defined(__MACH__)
  41     #include <CarbonCore/MacTypes.h>
  42 #else
  43     typedef unsigned char           Boolean;
  44     typedef unsigned char           UInt8;
  45     typedef signed char             SInt8;
  46     typedef unsigned short          UInt16;
  47     typedef signed short            SInt16;
  48     typedef unsigned long           UInt32;
  49     typedef signed long             SInt32;
  50     typedef uint64_t                UInt64;
  51     typedef int64_t                 SInt64;
  52     typedef float                   Float32;
  53     typedef double                  Float64;
  54     typedef unsigned short          UniChar;
  55     typedef unsigned char *         StringPtr;
  56     typedef const unsigned char *   ConstStringPtr;
  57     typedef unsigned char           Str255[256];
  58     typedef const unsigned char *   ConstStr255Param;
  59     typedef SInt16                  OSErr;
  60     typedef SInt32                  OSStatus;
  61     typedef UInt32                  UTF32Char;
  62     typedef UInt16                  UTF16Char;
  63     typedef UInt8                   UTF8Char;
  64 #endif
  65
  66 #if defined(__cplusplus)
  67 extern "C" {
  68 #endif
  69
  70 #if !defined(NULL)
  71     #define NULL        0
  72 #endif
  73
  74 #if !defined(TRUE)
  75     #define TRUE        1
  76 #endif
  77
  78 #if !defined(FALSE)
  79     #define FALSE       0
  80 #endif
  81
  82 #if defined(__WIN32__)
  83     #undef CF_EXPORT
  84     #if defined(CF_BUILDING_CF)
  85         #define CF_EXPORT __declspec(dllexport) extern
  86     #else
  87         #define CF_EXPORT __declspec(dllimport) extern
  88     #endif
  89 #elif defined(macintosh)
  90     #if defined(__MWERKS__)
  91         #define CF_EXPORT __declspec(export) extern
  92     #endif
  93 #endif
  94
  95 #if !defined(CF_EXPORT)
  96     #define CF_EXPORT extern
  97 #endif
  98
  99 #if !defined(CF_INLINE)
 100     #if defined(__GNUC__)
 101         #define CF_INLINE static __inline__
 102     #elif defined(__MWERKS__) || defined(__cplusplus)
 103         #define CF_INLINE static inline
 104     #elif defined(__WIN32__)
 105         #define CF_INLINE static __inline__
 106     #endif
 107 #endif
 108
 109
 110 CF_EXPORT double kCFCoreFoundationVersionNumber;
 111
 112 #define kCFCoreFoundationVersionNumber10_0 196.4
 113 #define kCFCoreFoundationVersionNumber10_0_3 196.5
 114 #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED
 115 #define kCFCoreFoundationVersionNumber10_1 226.0
 116 /* Note these do not follow the usual numbering policy from the base release */
 117 #define kCFCoreFoundationVersionNumber10_1_2 227.2
 118 #define kCFCoreFoundationVersionNumber10_1_4 227.3
 119 #endif
 120 #if MAC_OS_X_VERSION_10_3 <= MAC_OS_X_VERSION_MAX_ALLOWED
 121 #define kCFCoreFoundationVersionNumber10_2 263.0
 122 #endif
 123
 124 typedef UInt32 CFTypeID;
 125 typedef UInt32 CFOptionFlags;
 126 typedef UInt32 CFHashCode;
 127 typedef SInt32 CFIndex;
 128
 129 /* Base "type" of all "CF objects", and polymorphic functions on them */
 130 typedef const void * CFTypeRef;
 131
 132 typedef const struct __CFString * CFStringRef;
 133 typedef struct __CFString * CFMutableStringRef;
 134
 135 /*
 136         Type to mean any instance of a property list type;
 137         currently, CFString, CFData, CFNumber, CFBoolean, CFDate,
 138         CFArray, and CFDictionary.
 139 */
 140 typedef CFTypeRef CFPropertyListRef;
 141
 142 /* Values returned from comparison functions */
 143 typedef enum {
 144     kCFCompareLessThan = -1,
 145     kCFCompareEqualTo = 0,
 146     kCFCompareGreaterThan = 1
 147 } CFComparisonResult;
 148
 149 /* A standard comparison function */
 150 typedef CFComparisonResult (*CFComparatorFunction)(const void *val1, const void *val2, void *context);
 151
 152 /* Constant used by some functions to indicate failed searches. */
 153 /* This is of type CFIndex. */
 154 enum {
 155     kCFNotFound = -1
 156 };
 157
 158
 159 /* Range type */
 160 typedef struct {
 161     CFIndex location;
 162     CFIndex length;
 163 } CFRange;
 164
 165 #if defined(CF_INLINE)
 166 CF_INLINE CFRange CFRangeMake(CFIndex loc, CFIndex len) {
 167     CFRange range;
 168     range.location = loc;
 169     range.length = len;
 170     return range;
 171 }
 172 #else
 173 #define CFRangeMake(LOC, LEN) __CFRangeMake(LOC, LEN)
 174 #endif
 175
 176 /* Private; do not use */
 177 CF_EXPORT
 178 CFRange __CFRangeMake(CFIndex loc, CFIndex len);
 179
 180
 181 #if MAC_OS_X_VERSION_10_2 <= MAC_OS_X_VERSION_MAX_ALLOWED
 182 /* Null representant */
 183
 184 typedef const struct __CFNull * CFNullRef;
 185
 186 CF_EXPORT
 187 CFTypeID CFNullGetTypeID(void);
 188
 189 CF_EXPORT
 190 const CFNullRef kCFNull;        // the singleton null instance
 191
 192 #endif
 193
 194
 195 /* Allocator API
 196
 197    Most of the time when specifying an allocator to Create functions, the NULL
 198    argument indicates "use the default"; this is the same as using kCFAllocatorDefault
 199    or the return value from CFAllocatorGetDefault().  This assures that you will use
 200    the allocator in effect at that time.
 201
 202    You should rarely use kCFAllocatorSystemDefault, the default default allocator.
 203 */
 204 typedef const struct __CFAllocator * CFAllocatorRef;
 205
 206 /* This is a synonym for NULL, if you'd rather use a named constant. */
 207 CF_EXPORT
 208 const CFAllocatorRef kCFAllocatorDefault;
 209
 210 /* Default system allocator; you rarely need to use this. */
 211 CF_EXPORT
 212 const CFAllocatorRef kCFAllocatorSystemDefault;
 213
 214 /* This allocator uses malloc(), realloc(), and free(). This should not be
 215    generally used; stick to kCFAllocatorDefault whenever possible. This
 216    allocator is useful as the "bytesDeallocator" in CFData or
 217    "contentsDeallocator" in CFString where the memory was obtained as a
 218    result of malloc() type functions.
 219 */
 220 CF_EXPORT
 221 const CFAllocatorRef kCFAllocatorMalloc;
 222
 223 /* Null allocator which does nothing and allocates no memory. This allocator
 224    is useful as the "bytesDeallocator" in CFData or "contentsDeallocator"
 225    in CFString where the memory should not be freed.
 226 */
 227 CF_EXPORT
 228 const CFAllocatorRef kCFAllocatorNull;
 229
 230 /* Special allocator argument to CFAllocatorCreate() which means
 231    "use the functions given in the context to allocate the allocator
 232    itself as well".
 233 */
 234 CF_EXPORT
 235 const CFAllocatorRef kCFAllocatorUseContext;
 236
 237 typedef const void *    (*CFAllocatorRetainCallBack)(const void *info);
 238 typedef void            (*CFAllocatorReleaseCallBack)(const void *info);
 239 typedef CFStringRef     (*CFAllocatorCopyDescriptionCallBack)(const void *info);
 240 typedef void *          (*CFAllocatorAllocateCallBack)(CFIndex allocSize, CFOptionFlags hint, void *info);
 241 typedef void *          (*CFAllocatorReallocateCallBack)(void *ptr, CFIndex newsize, CFOptionFlags hint, void *info);
 242 typedef void            (*CFAllocatorDeallocateCallBack)(void *ptr, void *info);
 243 typedef CFIndex         (*CFAllocatorPreferredSizeCallBack)(CFIndex size, CFOptionFlags hint, void *info);
 244 typedef struct {
 245     CFIndex                             version;
 246     void *                              info;
 247     CFAllocatorRetainCallBack           retain;
 248     CFAllocatorReleaseCallBack          release;
 249     CFAllocatorCopyDescriptionCallBack  copyDescription;
 250     CFAllocatorAllocateCallBack         allocate;
 251     CFAllocatorReallocateCallBack       reallocate;
 252     CFAllocatorDeallocateCallBack       deallocate;
 253     CFAllocatorPreferredSizeCallBack    preferredSize;
 254 } CFAllocatorContext;
 255
 256 CF_EXPORT
 257 CFTypeID        CFAllocatorGetTypeID(void);
 258
 259 /*
 260         CFAllocatorSetDefault() sets the allocator that is used in the current
 261         thread whenever NULL is specified as an allocator argument. This means
 262         that most, if not all allocations will go through this allocator. It
 263         also means that any allocator set as the default needs to be ready to
 264         deal with arbitrary memory allocation requests; in addition, the size
 265         and number of requests will change between releases.
 266
 267         An allocator set as the default will never be released, even if later
 268         another allocator replaces it as the default. Not only is it impractical
 269         for it to be released (as there might be caches created under the covers
 270         that refer to the allocator), in general it's also safer and more
 271         efficient to keep it around.
 272
 273         If you wish to use a custom allocator in a context, it's best to provide
 274         it as the argument to the various creation functions rather than setting
 275         it as the default. Setting the default allocator is not encouraged.
 276
 277         If you do set an allocator as the default, either do it for all time in
 278         your app, or do it in a nested fashion (by restoring the previous allocator
 279         when you exit your context). The latter might be appropriate for plug-ins
 280         or libraries that wish to set the default allocator.
 281 */
 282 CF_EXPORT
 283 void CFAllocatorSetDefault(CFAllocatorRef allocator);
 284
 285 CF_EXPORT
 286 CFAllocatorRef CFAllocatorGetDefault(void);
 287
 288 CF_EXPORT
 289 CFAllocatorRef CFAllocatorCreate(CFAllocatorRef allocator, CFAllocatorContext *context);
 290
 291 CF_EXPORT
 292 void *CFAllocatorAllocate(CFAllocatorRef allocator, CFIndex size, CFOptionFlags hint);
 293
 294 CF_EXPORT
 295 void *CFAllocatorReallocate(CFAllocatorRef allocator, void *ptr, CFIndex newsize, CFOptionFlags hint);
 296
 297 CF_EXPORT
 298 void CFAllocatorDeallocate(CFAllocatorRef allocator, void *ptr);
 299
 300 CF_EXPORT
 301 CFIndex CFAllocatorGetPreferredSizeForSize(CFAllocatorRef allocator, CFIndex size, CFOptionFlags hint);
 302
 303 CF_EXPORT
 304 void CFAllocatorGetContext(CFAllocatorRef allocator, CFAllocatorContext *context);
 305
 306
 307 /* Polymorphic CF functions */
 308
 309 CF_EXPORT
 310 CFTypeID CFGetTypeID(CFTypeRef cf);
 311
 312 CF_EXPORT
 313 CFStringRef CFCopyTypeIDDescription(CFTypeID type_id);
 314
 315 CF_EXPORT
 316 CFTypeRef CFRetain(CFTypeRef cf);
 317
 318 CF_EXPORT
 319 void CFRelease(CFTypeRef cf);
 320
 321 CF_EXPORT
 322 CFIndex CFGetRetainCount(CFTypeRef cf);
 323
 324 CF_EXPORT
 325 Boolean CFEqual(CFTypeRef cf1, CFTypeRef cf2);
 326
 327 CF_EXPORT
 328 CFHashCode CFHash(CFTypeRef cf);
 329
 330 CF_EXPORT
 331 CFStringRef CFCopyDescription(CFTypeRef cf);
 332
 333 CF_EXPORT
 334 CFAllocatorRef CFGetAllocator(CFTypeRef cf);
 335
 336 #if defined(__cplusplus)
 337 }
 338 #endif
 339
 340 #endif /* ! __COREFOUNDATION_CFBASE__ */
 341