1 { CFDictionary.h
2 Copyright (c) 1998-2013, Apple Inc. All rights reserved.
3 }
4 {
5 Modified for use with Free Pascal
6 Version 308
7 Please report any bugs to <gpc@microbizz.nl>
8 }
9
10 {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
11 {$mode macpas}
12 {$modeswitch cblocks}
13 {$packenum 1}
14 {$macro on}
15 {$inline on}
16 {$calling mwpascal}
17
18 unit CFDictionary;
19 interface
20 {$setc UNIVERSAL_INTERFACES_VERSION := $0400}
21 {$setc GAP_INTERFACES_VERSION := $0308}
22
23 {$ifc not defined USE_CFSTR_CONSTANT_MACROS}
24 {$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
25 {$endc}
26
27 {$ifc defined CPUPOWERPC and defined CPUI386}
28 {$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
29 {$endc}
30 {$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
31 {$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
32 {$endc}
33
34 {$ifc not defined __ppc__ and defined CPUPOWERPC32}
35 {$setc __ppc__ := 1}
36 {$elsec}
37 {$setc __ppc__ := 0}
38 {$endc}
39 {$ifc not defined __ppc64__ and defined CPUPOWERPC64}
40 {$setc __ppc64__ := 1}
41 {$elsec}
42 {$setc __ppc64__ := 0}
43 {$endc}
44 {$ifc not defined __i386__ and defined CPUI386}
45 {$setc __i386__ := 1}
46 {$elsec}
47 {$setc __i386__ := 0}
48 {$endc}
49 {$ifc not defined __x86_64__ and defined CPUX86_64}
50 {$setc __x86_64__ := 1}
51 {$elsec}
52 {$setc __x86_64__ := 0}
53 {$endc}
54 {$ifc not defined __arm__ and defined CPUARM}
55 {$setc __arm__ := 1}
56 {$elsec}
57 {$setc __arm__ := 0}
58 {$endc}
59 {$ifc not defined __arm64__ and defined CPUAARCH64}
60 {$setc __arm64__ := 1}
61 {$elsec}
62 {$setc __arm64__ := 0}
63 {$endc}
64
65 {$ifc defined cpu64}
66 {$setc __LP64__ := 1}
67 {$elsec}
68 {$setc __LP64__ := 0}
69 {$endc}
70
71
72 {$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
73 {$error Conflicting definitions for __ppc__ and __i386__}
74 {$endc}
75
76 {$ifc defined __ppc__ and __ppc__}
77 {$setc TARGET_CPU_PPC := TRUE}
78 {$setc TARGET_CPU_PPC64 := FALSE}
79 {$setc TARGET_CPU_X86 := FALSE}
80 {$setc TARGET_CPU_X86_64 := FALSE}
81 {$setc TARGET_CPU_ARM := FALSE}
82 {$setc TARGET_CPU_ARM64 := FALSE}
83 {$setc TARGET_OS_MAC := TRUE}
84 {$setc TARGET_OS_IPHONE := FALSE}
85 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
86 {$setc TARGET_OS_EMBEDDED := FALSE}
87 {$elifc defined __ppc64__ and __ppc64__}
88 {$setc TARGET_CPU_PPC := FALSE}
89 {$setc TARGET_CPU_PPC64 := TRUE}
90 {$setc TARGET_CPU_X86 := FALSE}
91 {$setc TARGET_CPU_X86_64 := FALSE}
92 {$setc TARGET_CPU_ARM := FALSE}
93 {$setc TARGET_CPU_ARM64 := FALSE}
94 {$setc TARGET_OS_MAC := TRUE}
95 {$setc TARGET_OS_IPHONE := FALSE}
96 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
97 {$setc TARGET_OS_EMBEDDED := FALSE}
98 {$elifc defined __i386__ and __i386__}
99 {$setc TARGET_CPU_PPC := FALSE}
100 {$setc TARGET_CPU_PPC64 := FALSE}
101 {$setc TARGET_CPU_X86 := TRUE}
102 {$setc TARGET_CPU_X86_64 := FALSE}
103 {$setc TARGET_CPU_ARM := FALSE}
104 {$setc TARGET_CPU_ARM64 := FALSE}
105 {$ifc defined iphonesim}
106 {$setc TARGET_OS_MAC := FALSE}
107 {$setc TARGET_OS_IPHONE := TRUE}
108 {$setc TARGET_IPHONE_SIMULATOR := TRUE}
109 {$elsec}
110 {$setc TARGET_OS_MAC := TRUE}
111 {$setc TARGET_OS_IPHONE := FALSE}
112 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
113 {$endc}
114 {$setc TARGET_OS_EMBEDDED := FALSE}
115 {$elifc defined __x86_64__ and __x86_64__}
116 {$setc TARGET_CPU_PPC := FALSE}
117 {$setc TARGET_CPU_PPC64 := FALSE}
118 {$setc TARGET_CPU_X86 := FALSE}
119 {$setc TARGET_CPU_X86_64 := TRUE}
120 {$setc TARGET_CPU_ARM := FALSE}
121 {$setc TARGET_CPU_ARM64 := FALSE}
122 {$ifc defined iphonesim}
123 {$setc TARGET_OS_MAC := FALSE}
124 {$setc TARGET_OS_IPHONE := TRUE}
125 {$setc TARGET_IPHONE_SIMULATOR := TRUE}
126 {$elsec}
127 {$setc TARGET_OS_MAC := TRUE}
128 {$setc TARGET_OS_IPHONE := FALSE}
129 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
130 {$endc}
131 {$setc TARGET_OS_EMBEDDED := FALSE}
132 {$elifc defined __arm__ and __arm__}
133 {$setc TARGET_CPU_PPC := FALSE}
134 {$setc TARGET_CPU_PPC64 := FALSE}
135 {$setc TARGET_CPU_X86 := FALSE}
136 {$setc TARGET_CPU_X86_64 := FALSE}
137 {$setc TARGET_CPU_ARM := TRUE}
138 {$setc TARGET_CPU_ARM64 := FALSE}
139 {$setc TARGET_OS_MAC := FALSE}
140 {$setc TARGET_OS_IPHONE := TRUE}
141 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
142 {$setc TARGET_OS_EMBEDDED := TRUE}
143 {$elifc defined __arm64__ and __arm64__}
144 {$setc TARGET_CPU_PPC := FALSE}
145 {$setc TARGET_CPU_PPC64 := FALSE}
146 {$setc TARGET_CPU_X86 := FALSE}
147 {$setc TARGET_CPU_X86_64 := FALSE}
148 {$setc TARGET_CPU_ARM := FALSE}
149 {$setc TARGET_CPU_ARM64 := TRUE}
150 {$ifc defined ios}
151 {$setc TARGET_OS_MAC := FALSE}
152 {$setc TARGET_OS_IPHONE := TRUE}
153 {$setc TARGET_OS_EMBEDDED := TRUE}
154 {$elsec}
155 {$setc TARGET_OS_MAC := TRUE}
156 {$setc TARGET_OS_IPHONE := FALSE}
157 {$setc TARGET_OS_EMBEDDED := FALSE}
158 {$endc}
159 {$setc TARGET_IPHONE_SIMULATOR := FALSE}
160 {$elsec}
161 {$error __ppc__ nor __ppc64__ nor __i386__ nor __x86_64__ nor __arm__ nor __arm64__ is defined.}
162 {$endc}
163
164 {$ifc defined __LP64__ and __LP64__ }
165 {$setc TARGET_CPU_64 := TRUE}
166 {$elsec}
167 {$setc TARGET_CPU_64 := FALSE}
168 {$endc}
169
170 {$ifc defined FPC_BIG_ENDIAN}
171 {$setc TARGET_RT_BIG_ENDIAN := TRUE}
172 {$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
173 {$elifc defined FPC_LITTLE_ENDIAN}
174 {$setc TARGET_RT_BIG_ENDIAN := FALSE}
175 {$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
176 {$elsec}
177 {$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
178 {$endc}
179 {$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
180 {$setc CALL_NOT_IN_CARBON := FALSE}
181 {$setc OLDROUTINENAMES := FALSE}
182 {$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
183 {$setc OPAQUE_UPP_TYPES := TRUE}
184 {$setc OTCARBONAPPLICATION := TRUE}
185 {$setc OTKERNEL := FALSE}
186 {$setc PM_USE_SESSION_APIS := TRUE}
187 {$setc TARGET_API_MAC_CARBON := TRUE}
188 {$setc TARGET_API_MAC_OS8 := FALSE}
189 {$setc TARGET_API_MAC_OSX := TRUE}
190 {$setc TARGET_CARBON := TRUE}
191 {$setc TARGET_CPU_68K := FALSE}
192 {$setc TARGET_CPU_MIPS := FALSE}
193 {$setc TARGET_CPU_SPARC := FALSE}
194 {$setc TARGET_OS_UNIX := FALSE}
195 {$setc TARGET_OS_WIN32 := FALSE}
196 {$setc TARGET_RT_MAC_68881 := FALSE}
197 {$setc TARGET_RT_MAC_CFM := FALSE}
198 {$setc TARGET_RT_MAC_MACHO := TRUE}
199 {$setc TYPED_FUNCTION_POINTERS := TRUE}
200 {$setc TYPE_BOOL := FALSE}
201 {$setc TYPE_EXTENDED := FALSE}
202 {$setc TYPE_LONGLONG := TRUE}
203 uses MacTypes,CFBase;
204 {$endc} {not MACOSALLINCLUDE}
205
206 {$ALIGN POWER}
207
208
209 {!
210 @header CFDictionary
211 CFDictionary implements a container which pairs pointer-sized keys
212 with pointer-sized values. Values are accessed via arbitrary
213 user-defined keys. A CFDictionary differs from a CFArray in that
214 the key used to access a particular value in the dictionary remains
215 the same as values are added to or removed from the dictionary,
216 unless a value associated with its particular key is replaced or
217 removed. In a CFArray, the key (or index) used to retrieve a
218 particular value can change over time as values are added to or
219 deleted from the array. Also unlike an array, there is no ordering
220 among values in a dictionary. To enable later retrieval of a value,
221 the key of the key-value pair should be constant (or treated as
222 constant); if the key changes after being used to put a value in
223 the dictionary, the value may not be retrievable. The keys of a
224 dictionary form a set; that is, no two keys which are equal to
225 one another are present in the dictionary at any time.
226
227 #if MAC_OS_X_VERSION_MIN_REQUIRED <= MAC_OS_X_VERSION_10_4
228 Dictionaries come in two flavors, immutable, which cannot have
229 values added to them or removed from them after the dictionary is
230 created, and mutable, to which you can add values or from which
231 remove values. Mutable dictionaries have two subflavors,
232 fixed-capacity, for which there is a maximum number set at creation
233 time of values which can be put into the dictionary, and variable
234 capacity, which can have an unlimited number of values (or rather,
235 limited only by constraints external to CFDictionary, like the
236 amount of available memory). Fixed-capacity dictionaries can be
237 somewhat higher performing, if you can put a definate upper limit
238 on the number of values that might be put into the dictionary.
239 #else
240 Dictionaries come in two flavors, immutable, which cannot have
241 values added to them or removed from them after the dictionary is
242 created, and mutable, to which you can add values or from which
243 remove values. Mutable dictionaries can have an unlimited number
244 of values (or rather, limited only by constraints external to
245 CFDictionary, like the amount of available memory).
246 #endif
247
248 As with all CoreFoundation collection types, dictionaries maintain
249 hard references on the values you put in them, but the retaining and
250 releasing functions are user-defined callbacks that can actually do
251 whatever the user wants (for example, nothing).
252
253 Although a particular implementation of CFDictionary may not use
254 hashing and a hash table for storage of the values, the keys have
255 a hash-code generating function defined for them, and a function
256 to test for equality of two keys. These two functions together
257 must maintain the invariant that if equal(X, Y), then hash(X) ==
258 hash(Y). Note that the converse will not generally be true (but
259 the contrapositive, if hash(X) != hash(Y), then !equal(X, Y),
260 will be as required by Boolean logic). If the hash() and equal()
261 key callbacks are NULL, the key is used as a pointer-sized integer,
262 and pointer equality is used. Care should be taken to provide a
263 hash() callback which will compute sufficiently dispersed hash
264 codes for the key set for best performance.
265
266 Computational Complexity
267 The access time for a value in the dictionary is guaranteed to be at
268 worst O(N) for any implementation, current and future, but will
269 often be O(1) (constant time). Insertion or deletion operations
270 will typically be constant time as well, but are O(N*N) in the
271 worst case in some implementations. Access of values through a key
272 is faster than accessing values directly (if there are any such
273 operations). Dictionaries will tend to use significantly more memory
274 than a array with the same number of values.
275 }
276
277
278 {!
279 @typedef CFDictionaryKeyCallBacks
280 Structure containing the callbacks for keys of a CFDictionary.
281 @field version The version number of the structure type being passed
282 in as a parameter to the CFDictionary creation functions.
283 This structure is version 0.
284 @field retain The callback used to add a retain for the dictionary
285 on keys as they are used to put values into the dictionary.
286 This callback returns the value to use as the key in the
287 dictionary, which is usually the value parameter passed to
288 this callback, but may be a different value if a different
289 value should be used as the key. The dictionary's allocator
290 is passed as the first argument.
291 @field release The callback used to remove a retain previously added
292 for the dictionary from keys as their values are removed from
293 the dictionary. The dictionary's allocator is passed as the
294 first argument.
295 @field copyDescription The callback used to create a descriptive
296 string representation of each key in the dictionary. This
297 is used by the CFCopyDescription() function.
298 @field equal The callback used to compare keys in the dictionary for
299 equality.
300 @field hash The callback used to compute a hash code for keys as they
301 are used to access, add, or remove values in the dictionary.
302 }
303 type
allocatornull304 CFDictionaryRetainCallBack = function( allocator: CFAllocatorRef; value: {const} UnivPtr ): UnivPtr;
305 CFDictionaryReleaseCallBack = procedure( allocator: CFAllocatorRef; value: {const} UnivPtr );
valuenull306 CFDictionaryCopyDescriptionCallBack = function( value: {const} UnivPtr ): CFStringRef;
value1null307 CFDictionaryEqualCallBack = function( value1: {const} UnivPtr; value2: {const} UnivPtr ): Boolean;
valuenull308 CFDictionaryHashCallBack = function( value: {const} UnivPtr ): CFHashCode;
309 CFDictionaryKeyCallBacks = record
310 version: CFIndex;
311 retain: CFDictionaryRetainCallBack;
312 release: CFDictionaryReleaseCallBack;
313 copyDescription: CFDictionaryCopyDescriptionCallBack;
314 equal: CFDictionaryEqualCallBack;
315 hash: CFDictionaryHashCallBack;
316 end;
317 CFDictionaryKeyCallBacksPtr = ^CFDictionaryKeyCallBacks;
318
319 {!
320 @constant kCFTypeDictionaryKeyCallBacks
321 Predefined CFDictionaryKeyCallBacks structure containing a
322 set of callbacks appropriate for use when the keys of a
323 CFDictionary are all CFTypes.
324 }
325 var kCFTypeDictionaryKeyCallBacks: CFDictionaryKeyCallBacks; external name '_kCFTypeDictionaryKeyCallBacks'; (* attribute const *)
326
327 {!
328 @constant kCFCopyStringDictionaryKeyCallBacks
329 Predefined CFDictionaryKeyCallBacks structure containing a
330 set of callbacks appropriate for use when the keys of a
331 CFDictionary are all CFStrings, which may be mutable and
332 need to be copied in order to serve as constant keys for
333 the values in the dictionary.
334 }
335 var kCFCopyStringDictionaryKeyCallBacks: CFDictionaryKeyCallBacks; external name '_kCFCopyStringDictionaryKeyCallBacks'; (* attribute const *)
336
337 {!
338 @typedef CFDictionaryValueCallBacks
339 Structure containing the callbacks for values of a CFDictionary.
340 @field version The version number of the structure type being passed
341 in as a parameter to the CFDictionary creation functions.
342 This structure is version 0.
343 @field retain The callback used to add a retain for the dictionary
344 on values as they are put into the dictionary.
345 This callback returns the value to use as the value in the
346 dictionary, which is usually the value parameter passed to
347 this callback, but may be a different value if a different
348 value should be added to the dictionary. The dictionary's
349 allocator is passed as the first argument.
350 @field release The callback used to remove a retain previously added
351 for the dictionary from values as they are removed from
352 the dictionary. The dictionary's allocator is passed as the
353 first argument.
354 @field copyDescription The callback used to create a descriptive
355 string representation of each value in the dictionary. This
356 is used by the CFCopyDescription() function.
357 @field equal The callback used to compare values in the dictionary for
358 equality in some operations.
359 }
360 type
361 CFDictionaryValueCallBacks = record
362 version: CFIndex;
363 retain: CFDictionaryRetainCallBack;
364 release: CFDictionaryReleaseCallBack;
365 copyDescription: CFDictionaryCopyDescriptionCallBack;
366 equal: CFDictionaryEqualCallBack;
367 end;
368 CFDictionaryValueCallBacksPtr = ^CFDictionaryValueCallBacks;
369
370 {!
371 @constant kCFTypeDictionaryValueCallBacks
372 Predefined CFDictionaryValueCallBacks structure containing a set
373 of callbacks appropriate for use when the values in a CFDictionary
374 are all CFTypes.
375 }
376 var kCFTypeDictionaryValueCallBacks: CFDictionaryValueCallBacks; external name '_kCFTypeDictionaryValueCallBacks'; (* attribute const *)
377
378 {!
379 @typedef CFDictionaryApplierFunction
380 Type of the callback function used by the apply functions of
381 CFDictionarys.
382 @param key The current key for the value.
383 @param value The current value from the dictionary.
384 @param context The user-defined context parameter given to the apply
385 function.
386 }
387 type
388 CFDictionaryApplierFunction = procedure( key: {const} UnivPtr; value: {const} UnivPtr; context: UnivPtr );
389
390 {!
391 @typedef CFDictionaryRef
392 This is the type of a reference to immutable CFDictionarys.
393 }
394 type
395 CFDictionaryRef = ^__CFDictionary; { an opaque type }
396 __CFDictionary = record end;
397 CFDictionaryRefPtr = ^CFDictionaryRef;
398
399 {!
400 @typedef CFMutableDictionaryRef
401 This is the type of a reference to mutable CFDictionarys.
402 }
403 type
404 CFMutableDictionaryRef = CFDictionaryRef;
405 CFMutableDictionaryRefPtr = ^CFMutableDictionaryRef;
406
407 {!
408 @function CFDictionaryGetTypeID
409 Returns the type identifier of all CFDictionary instances.
410 }
CFDictionaryGetTypeIDnull411 function CFDictionaryGetTypeID: CFTypeID; external name '_CFDictionaryGetTypeID';
412
413 {!
414 @function CFDictionaryCreate
415 Creates a new immutable dictionary with the given values.
416 @param allocator The CFAllocator which should be used to allocate
417 memory for the dictionary and its storage for values. This
418 parameter may be NULL in which case the current default
419 CFAllocator is used. If this reference is not a valid
420 CFAllocator, the behavior is undefined.
421 @param keys A C array of the pointer-sized keys to be used for
422 the parallel C array of values to be put into the dictionary.
423 This parameter may be NULL if the numValues parameter is 0.
424 This C array is not changed or freed by this function. If
425 this parameter is not a valid pointer to a C array of at
426 least numValues pointers, the behavior is undefined.
427 @param values A C array of the pointer-sized values to be in the
428 dictionary. This parameter may be NULL if the numValues
429 parameter is 0. This C array is not changed or freed by
430 this function. If this parameter is not a valid pointer to
431 a C array of at least numValues pointers, the behavior is
432 undefined.
433 @param numValues The number of values to copy from the keys and
434 values C arrays into the CFDictionary. This number will be
435 the count of the dictionary. If this parameter is
436 negative, or greater than the number of values actually
437 in the keys or values C arrays, the behavior is undefined.
438 @param keyCallBacks A pointer to a CFDictionaryKeyCallBacks structure
439 initialized with the callbacks for the dictionary to use on
440 each key in the dictionary. The retain callback will be used
441 within this function, for example, to retain all of the new
442 keys from the keys C array. A copy of the contents of the
443 callbacks structure is made, so that a pointer to a structure
444 on the stack can be passed in, or can be reused for multiple
445 dictionary creations. If the version field of this
446 callbacks structure is not one of the defined ones for
447 CFDictionary, the behavior is undefined. The retain field may
448 be NULL, in which case the CFDictionary will do nothing to add
449 a retain to the keys of the contained values. The release field
450 may be NULL, in which case the CFDictionary will do nothing
451 to remove the dictionary's retain (if any) on the keys when the
452 dictionary is destroyed or a key-value pair is removed. If the
453 copyDescription field is NULL, the dictionary will create a
454 simple description for a key. If the equal field is NULL, the
455 dictionary will use pointer equality to test for equality of
456 keys. If the hash field is NULL, a key will be converted from
457 a pointer to an integer to compute the hash code. This callbacks
458 parameter itself may be NULL, which is treated as if a valid
459 structure of version 0 with all fields NULL had been passed in.
460 Otherwise, if any of the fields are not valid pointers to
461 functions of the correct type, or this parameter is not a
462 valid pointer to a CFDictionaryKeyCallBacks callbacks structure,
463 the behavior is undefined. If any of the keys put into the
464 dictionary is not one understood by one of the callback functions
465 the behavior when that callback function is used is undefined.
466 @param valueCallBacks A pointer to a CFDictionaryValueCallBacks structure
467 initialized with the callbacks for the dictionary to use on
468 each value in the dictionary. The retain callback will be used
469 within this function, for example, to retain all of the new
470 values from the values C array. A copy of the contents of the
471 callbacks structure is made, so that a pointer to a structure
472 on the stack can be passed in, or can be reused for multiple
473 dictionary creations. If the version field of this callbacks
474 structure is not one of the defined ones for CFDictionary, the
475 behavior is undefined. The retain field may be NULL, in which
476 case the CFDictionary will do nothing to add a retain to values
477 as they are put into the dictionary. The release field may be
478 NULL, in which case the CFDictionary will do nothing to remove
479 the dictionary's retain (if any) on the values when the
480 dictionary is destroyed or a key-value pair is removed. If the
481 copyDescription field is NULL, the dictionary will create a
482 simple description for a value. If the equal field is NULL, the
483 dictionary will use pointer equality to test for equality of
484 values. This callbacks parameter itself may be NULL, which is
485 treated as if a valid structure of version 0 with all fields
486 NULL had been passed in. Otherwise,
487 if any of the fields are not valid pointers to functions
488 of the correct type, or this parameter is not a valid
489 pointer to a CFDictionaryValueCallBacks callbacks structure,
490 the behavior is undefined. If any of the values put into the
491 dictionary is not one understood by one of the callback functions
492 the behavior when that callback function is used is undefined.
493 @result A reference to the new immutable CFDictionary.
494 }
CFDictionaryCreatenull495 function CFDictionaryCreate( allocator: CFAllocatorRef; {const} keys: UnivPtrPtr; {const} values: UnivPtrPtr; numValues: CFIndex; {const} keyCallBacks: CFDictionaryKeyCallBacksPtr { can be NULL }; {const} valueCallBacks: CFDictionaryValueCallBacksPtr { can be NULL } ): CFDictionaryRef; external name '_CFDictionaryCreate';
496
497 {!
498 @function CFDictionaryCreateCopy
499 Creates a new immutable dictionary with the key-value pairs from
500 the given dictionary.
501 @param allocator The CFAllocator which should be used to allocate
502 memory for the dictionary and its storage for values. This
503 parameter may be NULL in which case the current default
504 CFAllocator is used. If this reference is not a valid
505 CFAllocator, the behavior is undefined.
506 @param theDict The dictionary which is to be copied. The keys and values
507 from the dictionary are copied as pointers into the new
508 dictionary (that is, the values themselves are copied, not
509 that which the values point to, if anything). However, the
510 keys and values are also retained by the new dictionary using
511 the retain function of the original dictionary.
512 The count of the new dictionary will be the same as the
513 given dictionary. The new dictionary uses the same callbacks
514 as the dictionary to be copied. If this parameter is
515 not a valid CFDictionary, the behavior is undefined.
516 @result A reference to the new immutable CFDictionary.
517 }
CFDictionaryCreateCopynull518 function CFDictionaryCreateCopy( allocator: CFAllocatorRef; theDict: CFDictionaryRef ): CFDictionaryRef; external name '_CFDictionaryCreateCopy';
519
520 {!
521 @function CFDictionaryCreateMutable
522 Creates a new mutable dictionary.
523 @param allocator The CFAllocator which should be used to allocate
524 memory for the dictionary and its storage for values. This
525 parameter may be NULL in which case the current default
526 CFAllocator is used. If this reference is not a valid
527 CFAllocator, the behavior is undefined.
528 #if MAC_OS_X_VERSION_MIN_REQUIRED <= MAC_OS_X_VERSION_10_4
529 @param capacity The maximum number of values that can be contained by
530 the CFDictionary. The dictionary starts empty, and can grow
531 to this number of values (and it can have less). If this
532 parameter is 0, the dictionary's maximum capacity is unlimited
533 (or rather, only limited by address space and available memory
534 constraints). If this parameter is negative, the behavior is
535 undefined.
536 #else
537 @param capacity A hint about the number of values that will be held
538 by the CFDictionary. Pass 0 for no hint. The implementation may
539 ignore this hint, or may use it to optimize various
540 operations. A dictionary's actual capacity is only limited by
541 address space and available memory constraints). If this
542 parameter is negative, the behavior is undefined.
543 #endif
544 @param keyCallBacks A pointer to a CFDictionaryKeyCallBacks structure
545 initialized with the callbacks for the dictionary to use on
546 each key in the dictionary. A copy of the contents of the
547 callbacks structure is made, so that a pointer to a structure
548 on the stack can be passed in, or can be reused for multiple
549 dictionary creations. If the version field of this
550 callbacks structure is not one of the defined ones for
551 CFDictionary, the behavior is undefined. The retain field may
552 be NULL, in which case the CFDictionary will do nothing to add
553 a retain to the keys of the contained values. The release field
554 may be NULL, in which case the CFDictionary will do nothing
555 to remove the dictionary's retain (if any) on the keys when the
556 dictionary is destroyed or a key-value pair is removed. If the
557 copyDescription field is NULL, the dictionary will create a
558 simple description for a key. If the equal field is NULL, the
559 dictionary will use pointer equality to test for equality of
560 keys. If the hash field is NULL, a key will be converted from
561 a pointer to an integer to compute the hash code. This callbacks
562 parameter itself may be NULL, which is treated as if a valid
563 structure of version 0 with all fields NULL had been passed in.
564 Otherwise, if any of the fields are not valid pointers to
565 functions of the correct type, or this parameter is not a
566 valid pointer to a CFDictionaryKeyCallBacks callbacks structure,
567 the behavior is undefined. If any of the keys put into the
568 dictionary is not one understood by one of the callback functions
569 the behavior when that callback function is used is undefined.
570 @param valueCallBacks A pointer to a CFDictionaryValueCallBacks structure
571 initialized with the callbacks for the dictionary to use on
572 each value in the dictionary. The retain callback will be used
573 within this function, for example, to retain all of the new
574 values from the values C array. A copy of the contents of the
575 callbacks structure is made, so that a pointer to a structure
576 on the stack can be passed in, or can be reused for multiple
577 dictionary creations. If the version field of this callbacks
578 structure is not one of the defined ones for CFDictionary, the
579 behavior is undefined. The retain field may be NULL, in which
580 case the CFDictionary will do nothing to add a retain to values
581 as they are put into the dictionary. The release field may be
582 NULL, in which case the CFDictionary will do nothing to remove
583 the dictionary's retain (if any) on the values when the
584 dictionary is destroyed or a key-value pair is removed. If the
585 copyDescription field is NULL, the dictionary will create a
586 simple description for a value. If the equal field is NULL, the
587 dictionary will use pointer equality to test for equality of
588 values. This callbacks parameter itself may be NULL, which is
589 treated as if a valid structure of version 0 with all fields
590 NULL had been passed in. Otherwise,
591 if any of the fields are not valid pointers to functions
592 of the correct type, or this parameter is not a valid
593 pointer to a CFDictionaryValueCallBacks callbacks structure,
594 the behavior is undefined. If any of the values put into the
595 dictionary is not one understood by one of the callback functions
596 the behavior when that callback function is used is undefined.
597 @result A reference to the new mutable CFDictionary.
598 }
CFDictionaryCreateMutablenull599 function CFDictionaryCreateMutable( allocator: CFAllocatorRef; capacity: CFIndex; {const} keyCallBacks: CFDictionaryKeyCallBacksPtr { can be NULL }; {const} valueCallBacks: CFDictionaryValueCallBacksPtr { can be NULL } ): CFMutableDictionaryRef; external name '_CFDictionaryCreateMutable';
600
601 {!
602 @function CFDictionaryCreateMutableCopy
603 Creates a new mutable dictionary with the key-value pairs from
604 the given dictionary.
605 @param allocator The CFAllocator which should be used to allocate
606 memory for the dictionary and its storage for values. This
607 parameter may be NULL in which case the current default
608 CFAllocator is used. If this reference is not a valid
609 CFAllocator, the behavior is undefined.
610 #if MAC_OS_X_VERSION_MIN_REQUIRED <= MAC_OS_X_VERSION_10_4
611 @param capacity The maximum number of values that can be contained
612 by the CFDictionary. The dictionary starts empty, and can grow
613 to this number of values (and it can have less). If this
614 parameter is 0, the dictionary's maximum capacity is unlimited
615 (or rather, only limited by address space and available memory
616 constraints). This parameter must be greater than or equal
617 to the count of the dictionary which is to be copied, or the
618 behavior is undefined. If this parameter is negative, the
619 behavior is undefined.
620 #else
621 @param capacity A hint about the number of values that will be held
622 by the CFDictionary. Pass 0 for no hint. The implementation may
623 ignore this hint, or may use it to optimize various
624 operations. A dictionary's actual capacity is only limited by
625 address space and available memory constraints).
626 This parameter must be greater than or equal
627 to the count of the dictionary which is to be copied, or the
628 behavior is undefined. If this parameter is negative, the
629 behavior is undefined.
630 #endif
631 @param theDict The dictionary which is to be copied. The keys and values
632 from the dictionary are copied as pointers into the new
633 dictionary (that is, the values themselves are copied, not
634 that which the values point to, if anything). However, the
635 keys and values are also retained by the new dictionary using
636 the retain function of the original dictionary.
637 The count of the new dictionary will be the same as the
638 given dictionary. The new dictionary uses the same callbacks
639 as the dictionary to be copied. If this parameter is
640 not a valid CFDictionary, the behavior is undefined.
641 @result A reference to the new mutable CFDictionary.
642 }
CFDictionaryCreateMutableCopynull643 function CFDictionaryCreateMutableCopy( allocator: CFAllocatorRef; capacity: CFIndex; theDict: CFDictionaryRef ): CFMutableDictionaryRef; external name '_CFDictionaryCreateMutableCopy';
644
645 {!
646 @function CFDictionaryGetCount
647 Returns the number of values currently in the dictionary.
648 @param theDict The dictionary to be queried. If this parameter is
649 not a valid CFDictionary, the behavior is undefined.
650 @result The number of values in the dictionary.
651 }
CFDictionaryGetCountnull652 function CFDictionaryGetCount( theDict: CFDictionaryRef ): CFIndex; external name '_CFDictionaryGetCount';
653
654 {!
655 @function CFDictionaryGetCountOfKey
656 Counts the number of times the given key occurs in the dictionary.
657 @param theDict The dictionary to be searched. If this parameter is
658 not a valid CFDictionary, the behavior is undefined.
659 @param key The key for which to find matches in the dictionary. The
660 hash() and equal() key callbacks provided when the dictionary
661 was created are used to compare. If the hash() key callback
662 was NULL, the key is treated as a pointer and converted to
663 an integer. If the equal() key callback was NULL, pointer
664 equality (in C, ==) is used. If key, or any of the keys in
665 the dictionary, are not understood by the equal() callback,
666 the behavior is undefined.
667 @result Returns 1 if a matching key is used by the dictionary,
668 0 otherwise.
669 }
CFDictionaryGetCountOfKeynull670 function CFDictionaryGetCountOfKey( theDict: CFDictionaryRef; key: {const} UnivPtr ): CFIndex; external name '_CFDictionaryGetCountOfKey';
671
672 {!
673 @function CFDictionaryGetCountOfValue
674 Counts the number of times the given value occurs in the dictionary.
675 @param theDict The dictionary to be searched. If this parameter is
676 not a valid CFDictionary, the behavior is undefined.
677 @param value The value for which to find matches in the dictionary. The
678 equal() callback provided when the dictionary was created is
679 used to compare. If the equal() value callback was NULL, pointer
680 equality (in C, ==) is used. If value, or any of the values in
681 the dictionary, are not understood by the equal() callback,
682 the behavior is undefined.
683 @result The number of times the given value occurs in the dictionary.
684 }
CFDictionaryGetCountOfValuenull685 function CFDictionaryGetCountOfValue( theDict: CFDictionaryRef; value: {const} UnivPtr ): CFIndex; external name '_CFDictionaryGetCountOfValue';
686
687 {!
688 @function CFDictionaryContainsKey
689 Reports whether or not the key is in the dictionary.
690 @param theDict The dictionary to be searched. If this parameter is
691 not a valid CFDictionary, the behavior is undefined.
692 @param key The key for which to find matches in the dictionary. The
693 hash() and equal() key callbacks provided when the dictionary
694 was created are used to compare. If the hash() key callback
695 was NULL, the key is treated as a pointer and converted to
696 an integer. If the equal() key callback was NULL, pointer
697 equality (in C, ==) is used. If key, or any of the keys in
698 the dictionary, are not understood by the equal() callback,
699 the behavior is undefined.
700 @result true, if the key is in the dictionary, otherwise false.
701 }
CFDictionaryContainsKeynull702 function CFDictionaryContainsKey( theDict: CFDictionaryRef; key: {const} UnivPtr ): Boolean; external name '_CFDictionaryContainsKey';
703
704 {!
705 @function CFDictionaryContainsValue
706 Reports whether or not the value is in the dictionary.
707 @param theDict The dictionary to be searched. If this parameter is
708 not a valid CFDictionary, the behavior is undefined.
709 @param value The value for which to find matches in the dictionary. The
710 equal() callback provided when the dictionary was created is
711 used to compare. If the equal() callback was NULL, pointer
712 equality (in C, ==) is used. If value, or any of the values
713 in the dictionary, are not understood by the equal() callback,
714 the behavior is undefined.
715 @result true, if the value is in the dictionary, otherwise false.
716 }
CFDictionaryContainsValuenull717 function CFDictionaryContainsValue( theDict: CFDictionaryRef; value: {const} UnivPtr ): Boolean; external name '_CFDictionaryContainsValue';
718
719 {!
720 @function CFDictionaryGetValue
721 Retrieves the value associated with the given key.
722 @param theDict The dictionary to be queried. If this parameter is
723 not a valid CFDictionary, the behavior is undefined.
724 @param key The key for which to find a match in the dictionary. The
725 hash() and equal() key callbacks provided when the dictionary
726 was created are used to compare. If the hash() key callback
727 was NULL, the key is treated as a pointer and converted to
728 an integer. If the equal() key callback was NULL, pointer
729 equality (in C, ==) is used. If key, or any of the keys in
730 the dictionary, are not understood by the equal() callback,
731 the behavior is undefined.
732 @result The value with the given key in the dictionary, or NULL if
733 no key-value pair with a matching key exists. Since NULL
734 can be a valid value in some dictionaries, the function
735 CFDictionaryGetValueIfPresent() must be used to distinguish
736 NULL-no-found from NULL-is-the-value.
737 }
CFDictionaryGetValuenull738 function CFDictionaryGetValue( theDict: CFDictionaryRef; key: {const} UnivPtr ): UnivPtr; external name '_CFDictionaryGetValue';
739
740 {!
741 @function CFDictionaryGetValueIfPresent
742 Retrieves the value associated with the given key.
743 @param theDict The dictionary to be queried. If this parameter is
744 not a valid CFDictionary, the behavior is undefined.
745 @param key The key for which to find a match in the dictionary. The
746 hash() and equal() key callbacks provided when the dictionary
747 was created are used to compare. If the hash() key callback
748 was NULL, the key is treated as a pointer and converted to
749 an integer. If the equal() key callback was NULL, pointer
750 equality (in C, ==) is used. If key, or any of the keys in
751 the dictionary, are not understood by the equal() callback,
752 the behavior is undefined.
753 @param value A pointer to memory which should be filled with the
754 pointer-sized value if a matching key is found. If no key
755 match is found, the contents of the storage pointed to by
756 this parameter are undefined. This parameter may be NULL,
757 in which case the value from the dictionary is not returned
758 (but the return value of this function still indicates
759 whether or not the key-value pair was present).
760 @result true, if a matching key was found, false otherwise.
761 }
CFDictionaryGetValueIfPresentnull762 function CFDictionaryGetValueIfPresent( theDict: CFDictionaryRef; key: {const} UnivPtr; {const} value: UnivPtrPtr ): Boolean; external name '_CFDictionaryGetValueIfPresent';
763
764 {!
765 @function CFDictionaryGetKeysAndValues
766 Fills the two buffers with the keys and values from the dictionary.
767 @param theDict The dictionary to be queried. If this parameter is
768 not a valid CFDictionary, the behavior is undefined.
769 @param keys A C array of pointer-sized values to be filled with keys
770 from the dictionary. The keys and values C arrays are parallel
771 to each other (that is, the items at the same indices form a
772 key-value pair from the dictionary). This parameter may be NULL
773 if the keys are not desired. If this parameter is not a valid
774 pointer to a C array of at least CFDictionaryGetCount() pointers,
775 or NULL, the behavior is undefined.
776 @param values A C array of pointer-sized values to be filled with values
777 from the dictionary. The keys and values C arrays are parallel
778 to each other (that is, the items at the same indices form a
779 key-value pair from the dictionary). This parameter may be NULL
780 if the values are not desired. If this parameter is not a valid
781 pointer to a C array of at least CFDictionaryGetCount() pointers,
782 or NULL, the behavior is undefined.
783 }
784 procedure CFDictionaryGetKeysAndValues( theDict: CFDictionaryRef; {const} keys: UnivPtrPtr; {const} values: UnivPtrPtr ); external name '_CFDictionaryGetKeysAndValues';
785
786 {!
787 @function CFDictionaryApplyFunction
788 Calls a function once for each value in the dictionary.
789 @param theDict The dictionary to be queried. If this parameter is
790 not a valid CFDictionary, the behavior is undefined.
791 @param applier The callback function to call once for each value in
792 the dictionary. If this parameter is not a
793 pointer to a function of the correct prototype, the behavior
794 is undefined. If there are keys or values which the
795 applier function does not expect or cannot properly apply
796 to, the behavior is undefined.
797 @param context A pointer-sized user-defined value, which is passed
798 as the third parameter to the applier function, but is
799 otherwise unused by this function. If the context is not
800 what is expected by the applier function, the behavior is
801 undefined.
802 }
803 procedure CFDictionaryApplyFunction( theDict: CFDictionaryRef; applier: CFDictionaryApplierFunction; context: UnivPtr ); external name '_CFDictionaryApplyFunction';
804
805 {!
806 @function CFDictionaryAddValue
807 Adds the key-value pair to the dictionary if no such key already exists.
808 @param theDict The dictionary to which the value is to be added. If this
809 parameter is not a valid mutable CFDictionary, the behavior is
810 undefined.
811 #if MAC_OS_X_VERSION_MIN_REQUIRED <= MAC_OS_X_VERSION_10_4
812 If the dictionary is a fixed-capacity dictionary and
813 it is full before this operation, the behavior is undefined.
814 #endif
815 @param key The key of the value to add to the dictionary. The key is
816 retained by the dictionary using the retain callback provided
817 when the dictionary was created. If the key is not of the sort
818 expected by the retain callback, the behavior is undefined. If
819 a key which matches this key is already present in the dictionary,
820 this function does nothing ("add if absent").
821 @param value The value to add to the dictionary. The value is retained
822 by the dictionary using the retain callback provided when the
823 dictionary was created. If the value is not of the sort expected
824 by the retain callback, the behavior is undefined.
825 }
826 procedure CFDictionaryAddValue( theDict: CFMutableDictionaryRef; key: {const} UnivPtr; value: {const} UnivPtr ); external name '_CFDictionaryAddValue';
827
828 {!
829 @function CFDictionarySetValue
830 Sets the value of the key in the dictionary.
831 @param theDict The dictionary to which the value is to be set. If this
832 parameter is not a valid mutable CFDictionary, the behavior is
833 undefined.
834 #if MAC_OS_X_VERSION_MIN_REQUIRED <= MAC_OS_X_VERSION_10_4
835 If the dictionary is a fixed-capacity dictionary and
836 it is full before this operation, and the key does not exist in
837 the dictionary, the behavior is undefined.
838 #endif
839 @param key The key of the value to set into the dictionary. If a key
840 which matches this key is already present in the dictionary, only
841 the value is changed ("add if absent, replace if present"). If
842 no key matches the given key, the key-value pair is added to the
843 dictionary. If added, the key is retained by the dictionary,
844 using the retain callback provided
845 when the dictionary was created. If the key is not of the sort
846 expected by the key retain callback, the behavior is undefined.
847 @param value The value to add to or replace into the dictionary. The value
848 is retained by the dictionary using the retain callback provided
849 when the dictionary was created, and the previous value if any is
850 released. If the value is not of the sort expected by the
851 retain or release callbacks, the behavior is undefined.
852 }
853 procedure CFDictionarySetValue( theDict: CFMutableDictionaryRef; key: {const} UnivPtr; value: {const} UnivPtr ); external name '_CFDictionarySetValue';
854
855 {!
856 @function CFDictionaryReplaceValue
857 Replaces the value of the key in the dictionary.
858 @param theDict The dictionary to which the value is to be replaced. If this
859 parameter is not a valid mutable CFDictionary, the behavior is
860 undefined.
861 @param key The key of the value to replace in the dictionary. If a key
862 which matches this key is present in the dictionary, the value
863 is changed to the given value, otherwise this function does
864 nothing ("replace if present").
865 @param value The value to replace into the dictionary. The value
866 is retained by the dictionary using the retain callback provided
867 when the dictionary was created, and the previous value is
868 released. If the value is not of the sort expected by the
869 retain or release callbacks, the behavior is undefined.
870 }
871 procedure CFDictionaryReplaceValue( theDict: CFMutableDictionaryRef; key: {const} UnivPtr; value: {const} UnivPtr ); external name '_CFDictionaryReplaceValue';
872
873 {!
874 @function CFDictionaryRemoveValue
875 Removes the value of the key from the dictionary.
876 @param theDict The dictionary from which the value is to be removed. If this
877 parameter is not a valid mutable CFDictionary, the behavior is
878 undefined.
879 @param key The key of the value to remove from the dictionary. If a key
880 which matches this key is present in the dictionary, the key-value
881 pair is removed from the dictionary, otherwise this function does
882 nothing ("remove if present").
883 }
884 procedure CFDictionaryRemoveValue( theDict: CFMutableDictionaryRef; key: {const} UnivPtr ); external name '_CFDictionaryRemoveValue';
885
886 {!
887 @function CFDictionaryRemoveAllValues
888 Removes all the values from the dictionary, making it empty.
889 @param theDict The dictionary from which all of the values are to be
890 removed. If this parameter is not a valid mutable
891 CFDictionary, the behavior is undefined.
892 }
893 procedure CFDictionaryRemoveAllValues( theDict: CFMutableDictionaryRef ); external name '_CFDictionaryRemoveAllValues';
894
895 {$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
896
897 end.
898 {$endc} {not MACOSALLINCLUDE}
899