1/*
2 * Copyright (c) 2019 Apple Inc. All rights reserved.
3 *
4 * @APPLE_OSREFERENCE_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. The rights granted to you under the License
10 * may not be used to create, or enable the creation or redistribution of,
11 * unlawful or unlicensed copies of an Apple operating system, or to
12 * circumvent, violate, or enable the circumvention or violation of, any
13 * terms of an Apple operating system software license agreement.
14 *
15 * Please obtain a copy of the License at
16 * http://www.opensource.apple.com/apsl/ and read it before using this file.
17 *
18 * The Original Code and all software distributed under the License are
19 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
20 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
21 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
22 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
23 * Please see the License for the specific language governing rights and
24 * limitations under the License.
25 *
26 * @APPLE_OSREFERENCE_LICENSE_HEADER_END@
27 */
28/*
29 * Copyright (c) 1998-1999 Apple Computer, Inc. All rights reserved.
30 *
31 * HISTORY
32 *
33 * OSDictionary.h created by rsulack on Wed 17-Sep-1997
34 * OSDictionary.h converted to C++ by gvdl on Fri 1998-10-30
35 */
36
37#ifndef _IOKIT_IODICTIONARY_H
38#define _IOKIT_IODICTIONARY_H
39
40#include <libkern/c++/OSCollection.h>
41#include <libkern/c++/OSArray.h>
42#include <libkern/c++/OSPtr.h>
43#include <os/base.h>
44
45class OSArray;
46class OSSymbol;
47class OSString;
48class OSDictionary;
49
50typedef OSDictionary* OSDictionaryPtr;
51
52/*!
53 * @header
54 *
55 * @abstract
56 * This header declares the OSDictionary collection class.
57 */
58
59
60/*!
61 * @class OSDictionary
62 *
63 * @abstract
64 * OSDictionary provides an associative store using strings for keys.
65 *
66 * @discussion
67 * OSDictionary is a container for Libkern C++ objects
68 * (those derived from
69 * @link //apple_ref/doc/class/OSMetaClassBase OSMetaClassBase@/link,
70 * in particular @link //apple_ref/doc/class/OSObject OSObject@/link).
71 * Storage and access are associative, based on string-valued keys
72 * (C string, @link //apple_ref/cpp/cl/OSString OSString@/link,
73 * or @link //apple_ref/cpp/cl/OSSymbol OSSymbol@/link).
74 * When adding an object to an OSDictionary, you provide a string identifier,
75 * which can then used to retrieve that object or remove it from the dictionary.
76 * Setting an object with a key that already has an associated object
77 * replaces the original object.
78 *
79 * You must generally cast retrieved objects from
80 * @link //apple_ref/cpp/cl/OSObject OSObject@/link
81 * to the desired class using
82 * <code>@link //apple_ref/cpp/macro/OSDynamicCast OSDynamicCast@/link</code>.
83 * This macro returns the object cast to the desired class,
84 * or <code>NULL</code> if the object isn't derived from that class.
85 *
86 * When iterating an OSDictionary using
87 * @link //apple_ref/doc/class/OSCollectionIterator OSCollectionIterator@/link,
88 * the objects returned from
89 * <code>@link //apple_ref/doc/function/OSCollectionIterator::getNextObject
90 * getNextObject@/link</code>
91 * are dictionary keys (not the object values for those keys).
92 * You can use the keys to retrieve their associated object values.
93 *
94 * As with all Libkern collection classes,
95 * OSDictionary retains keys and objects added to it,
96 * and releases keys and objects removed from it (or replaced).
97 * An OSDictionary also grows as necessary to accommodate new key/value pairs,
98 * <i>unlike</i> Core Foundation collections (it does not, however, shrink).
99 *
100 * <b>Note:</b> OSDictionary currently uses a linear search algorithm,
101 * and is not designed for high-performance access of many values.
102 * It is intended as a simple associative-storage mechanism only.
103 *
104 * <b>Use Restrictions</b>
105 *
106 * With very few exceptions in the I/O Kit, all Libkern-based C++
107 * classes, functions, and macros are <b>unsafe</b>
108 * to use in a primary interrupt context.
109 * Consult the I/O Kit documentation related to primary interrupts
110 * for more information.
111 *
112 * OSDictionary provides no concurrency protection;
113 * it's up to the usage context to provide any protection necessary.
114 * Some portions of the I/O Kit, such as
115 * @link //apple_ref/doc/class/IORegistryEntry IORegistryEntry@/link,
116 * handle synchronization via defined member functions for setting
117 * properties.
118 */
119class OSDictionary : public OSCollection
120{
121 friend class OSSerialize;
122
123 OSDeclareDefaultStructors(OSDictionary);
124
125#if APPLE_KEXT_ALIGN_CONTAINERS
126
127protected:
128 unsigned int count;
129 unsigned int capacity;
130 unsigned int capacityIncrement;
131 struct dictEntry {
132 OSTaggedPtr<const OSSymbol> key;
133 OSTaggedPtr<const OSMetaClassBase> value;
134#if XNU_KERNEL_PRIVATE
135 static int compare(const void *, const void *);
136#endif
137 };
138 dictEntry * OS_PTRAUTH_SIGNED_PTR("OSDictionary.dictionary") dictionary;
139
140#else /* APPLE_KEXT_ALIGN_CONTAINERS */
141
142protected:
143 struct dictEntry {
144 OSTaggedPtr<const OSSymbol> key;
145 OSTaggedPtr<const OSMetaClassBase> value;
146#if XNU_KERNEL_PRIVATE
147 static int compare(const void *, const void *);
148#endif
149 };
150 dictEntry * OS_PTRAUTH_SIGNED_PTR("OSDictionary.dictionary") dictionary;
151 unsigned int count;
152 unsigned int capacity;
153 unsigned int capacityIncrement;
154
155 struct ExpansionData { };
156
157/* Reserved for future use. (Internal use only) */
158 ExpansionData * reserved;
159
160#endif /* APPLE_KEXT_ALIGN_CONTAINERS */
161
162// Member functions used by the OSCollectionIterator class.
163 virtual unsigned int iteratorSize() const APPLE_KEXT_OVERRIDE;
164 virtual bool initIterator(void * iterator) const APPLE_KEXT_OVERRIDE;
165 virtual bool getNextObjectForIterator(void * iterator, OSObject ** ret) const APPLE_KEXT_OVERRIDE;
166
167public:
168
169/*!
170 * @function withCapacity
171 *
172 * @abstract
173 * Creates and initializes an empty OSDictionary.
174 *
175 * @param capacity The initial storage capacity of the new dictionary object.
176 *
177 * @result
178 * An empty instance of OSDictionary
179 * with a retain count of 1;
180 * <code>NULL</code> on failure.
181 *
182 * @discussion
183 * <code>capacity</code> must be nonzero.
184 * The new dictionary will grow as needed to accommodate more key/object pairs
185 * (<i>unlike</i> @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
186 * for which the initial capacity is a hard limit).
187 */
188 static OSPtr<OSDictionary> withCapacity(unsigned int capacity);
189
190
191/*!
192 * @function withObjects
193 *
194 * @abstract Creates and initializes an OSDictionary
195 * populated with keys and objects provided.
196 *
197 * @param objects A C array of OSMetaClassBase-derived objects.
198 * @param keys A C array of OSSymbol keys
199 * for the corresponding objects in <code>objects</code>.
200 * @param count The number of keys and objects
201 * to be placed into the dictionary.
202 * @param capacity The initial storage capacity of the new dictionary object.
203 * If 0, <code>count</code> is used; otherwise this value
204 * must be greater than or equal to <code>count</code>.
205 *
206 * @result
207 * An instance of OSDictionary
208 * containing the key/object pairs provided,
209 * with a retain count of 1;
210 * <code>NULL</code> on failure.
211 *
212 * @discussion
213 * <code>objects</code> and <code>keys</code> must be non-<code>NULL</code>,
214 * and <code>count</code> must be nonzero.
215 * If <code>capacity</code> is nonzero,
216 * it must be greater than or equal to <code>count</code>.
217 * The new dictionary will grow as needed
218 * to accommodate more key/object pairs
219 * (<i>unlike</i>
220 * @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
221 * for which the initial capacity is a hard limit).
222 */
223 static OSPtr<OSDictionary> withObjects(
224 const OSObject * objects[],
225 const OSSymbol * keys[],
226 unsigned int count,
227 unsigned int capacity = 0);
228
229/*!
230 * @function withObjects
231 *
232 * @abstract
233 * Creates and initializes an OSDictionary
234 * populated with keys and objects provided.
235 *
236 * @param objects A C array of OSMetaClassBase-derived objects.
237 * @param keys A C array of OSString keys for the corresponding objects
238 * in <code>objects</code>.
239 * @param count The number of keys and objects
240 * to be placed into the dictionary.
241 * @param capacity The initial storage capacity of the new dictionary object.
242 * If 0, <code>count</code> is used; otherwise this value
243 * must be greater than or equal to <code>count</code>.
244 *
245 * @result
246 * An instance of OSDictionary
247 * containing the key/object pairs provided,
248 * with a retain count of 1;
249 * <code>NULL</code> on failure.
250 *
251 * @discussion
252 * <code>objects</code> and <code>keys</code> must be non-<code>NULL</code>,
253 * and <code>count</code> must be nonzero.
254 * If <code>capacity</code> is nonzero, it must be greater than or equal to <code>count</code>.
255 * The new dictionary will grow as needed
256 * to accommodate more key/object pairs
257 * (<i>unlike</i>
258 * @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
259 * for which the initial capacity is a hard limit).
260 */
261 static OSPtr<OSDictionary> withObjects(
262 const OSObject * objects[],
263 const OSString * keys[],
264 unsigned int count,
265 unsigned int capacity = 0);
266
267
268/*!
269 * @function withDictionary
270 *
271 * @abstract
272 * Creates and initializes an OSDictionary
273 * populated with the contents of another dictionary.
274 *
275 * @param dict A dictionary whose contents will be stored
276 * in the new instance.
277 * @param capacity The initial storage capacity of the new dictionary object.
278 * If 0, the capacity is set to the number of key/value pairs
279 * in <code>dict</code>;
280 * otherwise <code>capacity</code> must be greater than or equal to
281 * the number of key/value pairs in <code>dict</code>.
282 *
283 * @result
284 * An instance of OSDictionary
285 * containing the key/value pairs of <code>dict</code>,
286 * with a retain count of 1;
287 * <code>NULL</code> on failure.
288 *
289 * @discussion
290 * <code>dict</code> must be non-<code>NULL</code>.
291 * If <code>capacity</code> is nonzero, it must be greater than or equal to <code>count</code>.
292 * The new dictionary will grow as needed
293 * to accommodate more key/object pairs
294 * (<i>unlike</i>
295 * @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
296 * for which the initial capacity is a hard limit).
297 *
298 * The keys and objects in <code>dict</code> are retained for storage
299 * in the new OSDictionary,
300 * not copied.
301 */
302 static OSPtr<OSDictionary> withDictionary(
303 const OSDictionary * dict,
304 unsigned int capacity = 0);
305
306
307/*!
308 * @function initWithCapacity
309 *
310 * @abstract
311 * Initializes a new instance of OSDictionary.
312 *
313 * @param capacity The initial storage capacity of the new dictionary object.
314 * @result
315 * <code>true</code> on success, <code>false</code> on failure.
316 *
317 * @discussion
318 * Not for general use. Use the static instance creation method
319 * <code>@link //apple_ref/cpp/clm/OSDictionary/withCapacity/staticOSDictionary*\/(unsignedint)
320 * withCapacity@/link</code>
321 * instead.
322 *
323 * <code>capacity</code> must be nonzero.
324 * The new dictionary will grow as needed
325 * to accommodate more key/object pairs
326 * (<i>unlike</i>
327 * @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
328 * for which the initial capacity is a hard limit).
329 */
330 virtual bool initWithCapacity(unsigned int capacity);
331
332
333/*!
334 * @function initWithObjects
335 *
336 * @abstract Initializes a new OSDictionary with keys and objects provided.
337 *
338 * @param objects A C array of OSMetaClassBase-derived objects.
339 * @param keys A C array of OSSymbol keys
340 * for the corresponding objects in <code>objects</code>.
341 * @param count The number of keys and objects to be placed
342 * into the dictionary.
343 * @param capacity The initial storage capacity of the new dictionary object.
344 * If 0, <code>count</code> is used; otherwise this value
345 * must be greater than or equal to <code>count</code>.
346 *
347 * @result
348 * <code>true</code> on success, <code>false</code> on failure.
349 *
350 * @discussion
351 * Not for general use. Use the static instance creation method
352 * <code>@link
353 * //apple_ref/cpp/clm/OSDictionary/withObjects/staticOSDictionary*\/(constOSObject*,constOSString*,unsignedint,unsignedint)
354 * withObjects@/link</code>
355 * instead.
356 *
357 * <code>objects</code> and <code>keys</code> must be non-<code>NULL</code>,
358 * and <code>count</code> must be nonzero.
359 * If <code>capacity</code> is nonzero,
360 * it must be greater than or equal to <code>count</code>.
361 * The new dictionary will grow as neede
362 * to accommodate more key/object pairs
363 * (<i>unlike</i>
364 * @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
365 * for which the initial capacity is a hard limit).
366 */
367 virtual bool initWithObjects(
368 const OSObject * objects[],
369 const OSSymbol * keys[],
370 unsigned int count,
371 unsigned int capacity = 0);
372
373
374/*!
375 * @function initWithObjects
376 *
377 * @abstract
378 * Initializes a new OSDictionary with keys and objects provided.
379 *
380 * @param objects A C array of OSMetaClassBase-derived objects.
381 * @param keys A C array of OSString keys
382 * for the corresponding objects in <code>objects</code>.
383 * @param count The number of keys and objects
384 * to be placed into the dictionary.
385 * @param capacity The initial storage capacity of the new dictionary object.
386 * If 0, <code>count</code> is used; otherwise this value
387 * must be greater than or equal to <code>count</code>.
388 *
389 * @result
390 * <code>true</code> on success, <code>false</code> on failure.
391 *
392 * @discussion
393 * Not for general use. Use the static instance creation method
394 * <code>@link
395 * //apple_ref/cpp/clm/OSDictionary/withObjects/staticOSDictionary*\/(constOSObject*,constOSString*,unsignedint,unsignedint)
396 * withObjects@/link</code>
397 * instead.
398 *
399 * <code>objects</code> and <code>keys</code> must be non-<code>NULL</code>,
400 * and <code>count</code> must be nonzero.
401 * If <code>capacity</code> is nonzero, it must be greater than or equal to <code>count</code>.
402 * The new dictionary will grow as needed
403 * to accommodate more key/object pairs
404 * (<i>unlike</i>
405 * @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
406 * for which the initial capacity is a hard limit).
407 */
408 virtual bool initWithObjects(
409 const OSObject * objects[],
410 const OSString * keys[],
411 unsigned int count,
412 unsigned int capacity = 0);
413
414
415/*!
416 * @function initWithDictionary
417 *
418 * @abstract
419 * Initializes a new OSDictionary
420 * with the contents of another dictionary.
421 *
422 * @param dict A dictionary whose contents will be placed
423 * in the new instance.
424 * @param capacity The initial storage capacity of the new dictionary object.
425 * If 0, the capacity is set to the number of key/value pairs
426 * in <code>dict</code>;
427 * otherwise <code>capacity</code> must be greater than or equal to
428 * the number of key/value pairs in <code>dict</code>.
429 *
430 * @result
431 * <code>true</code> on success, <code>false</code> on failure.
432 *
433 * @discussion
434 * Not for general use. Use the static instance creation method
435 * <code>@link withDictionary withDictionary@/link</code> instead.
436 *
437 * <code>dict</code> must be non-<code>NULL</code>.
438 * If <code>capacity</code> is nonzero,
439 * it must be greater than or equal to <code>count</code>.
440 * The new dictionary will grow as needed
441 * to accommodate more key/object pairs
442 * (<i>unlike</i>
443 * @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
444 * for which the initial capacity is a hard limit).
445 *
446 * The keys and objects in <code>dict</code> are retained for storage
447 * in the new OSDictionary,
448 * not copied.
449 */
450 virtual bool initWithDictionary(
451 const OSDictionary * dict,
452 unsigned int capacity = 0);
453
454
455/*!
456 * @function free
457 *
458 * @abstract
459 * Deallocates or releases any resources
460 * used by the OSDictionary instance.
461 *
462 * @discussion
463 * This function should not be called directly,
464 * use
465 * <code>@link
466 * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
467 * release@/link</code>
468 * instead.
469 */
470 virtual void free() APPLE_KEXT_OVERRIDE;
471
472
473/*!
474 * @function getCount
475 *
476 * @abstract
477 * Returns the current number of key/object pairs
478 * contained within the dictionary.
479 *
480 * @result
481 * The current number of key/object pairs
482 * contained within the dictionary.
483 */
484 virtual unsigned int getCount() const APPLE_KEXT_OVERRIDE;
485
486
487/*!
488 * @function getCapacity
489 *
490 * @abstract
491 * Returns the number of objects the dictionary can store without reallocating.
492 *
493 * @result
494 * The number objects the dictionary can store without reallocating.
495 *
496 * @discussion
497 * OSDictionary objects grow when full
498 * to accommodate additional key/object pairs.
499 * See
500 * <code>@link
501 * //apple_ref/cpp/instm/OSDictionary/getCapacityIncrement/virtualunsignedint/()
502 * getCapacityIncrement@/link</code>
503 * and
504 * <code>@link
505 * //apple_ref/cpp/instm/OSDictionary/ensureCapacity/virtualunsignedint/(unsignedint)
506 * ensureCapacity@/link</code>.
507 */
508 virtual unsigned int getCapacity() const APPLE_KEXT_OVERRIDE;
509
510
511/*!
512 * @function getCapacityIncrement
513 *
514 * @abstract
515 * Returns the storage increment of the dictionary.
516 *
517 * @result
518 * The storage increment of the dictionary.
519 *
520 * @discussion
521 * An OSDictionary allocates storage for key/object pairs in multiples
522 * of the capacity increment.
523 */
524 virtual unsigned int getCapacityIncrement() const APPLE_KEXT_OVERRIDE;
525
526
527/*!
528 * @function setCapacityIncrement
529 *
530 * @abstract
531 * Sets the storage increment of the dictionary.
532 *
533 * @result
534 * The new storage increment of the dictionary,
535 * which may be different from the number requested.
536 *
537 * @discussion
538 * An OSDictionary allocates storage for key/object pairs in multiples
539 * of the capacity increment.
540 * Calling this function does not immediately reallocate storage.
541 */
542 virtual unsigned int setCapacityIncrement(unsigned increment) APPLE_KEXT_OVERRIDE;
543
544
545/*!
546 * @function ensureCapacity
547 *
548 * @abstract
549 * Ensures the dictionary has enough space
550 * to store the requested number of key/object pairs.
551 *
552 * @param newCapacity The total number of key/object pairs the dictionary
553 * should be able to store.
554 *
555 * @result
556 * The new capacity of the dictionary,
557 * which may be different from the number requested
558 * (if smaller, reallocation of storage failed).
559 *
560 * @discussion
561 * This function immediately resizes the dictionary, if necessary,
562 * to accommodate at least <code>newCapacity</code> key/object pairs.
563 * If <code>newCapacity</code> is not greater than the current capacity,
564 * or if an allocation error occurs, the original capacity is returned.
565 *
566 * There is no way to reduce the capacity of an OSDictionary.
567 */
568 virtual unsigned int ensureCapacity(unsigned int newCapacity) APPLE_KEXT_OVERRIDE;
569
570
571/*!
572 * @function flushCollection
573 *
574 * @abstract
575 * Removes and releases all keys and objects within the dictionary.
576 *
577 * @discussion
578 * The dictionary's capacity (and therefore direct memory consumption)
579 * is not reduced by this function.
580 */
581 virtual void flushCollection() APPLE_KEXT_OVERRIDE;
582
583
584/*!
585 * @function setObject
586 *
587 * @abstract
588 * Stores an object in the dictionary under a key.
589 *
590 * @param aKey An OSSymbol identifying the object
591 * placed within the dictionary.
592 * It is automatically retained.
593 * @param anObject The object to be stored in the dictionary.
594 * It is automatically retained.
595 *
596 * @result
597 * <code>true</code> if the addition was successful,
598 * <code>false</code> otherwise.
599 *
600 * @discussion
601 * An object already stored under <code>aKey</code> is released.
602 */
603 virtual bool setObject(
604 const OSSymbol * aKey,
605 const OSMetaClassBase * anObject);
606
607 bool setObject(
608 OSSharedPtr<const OSSymbol> const& aKey,
609 OSSharedPtr<const OSMetaClassBase> const& anObject);
610
611
612/*!
613 * @function setObject
614 *
615 * @abstract Stores an object in the dictionary under a key.
616 *
617 * @param aKey An OSString identifying the object
618 * placed within the dictionary.
619 * @param anObject The object to be stored in the dictionary.
620 * It is automatically retained.
621 *
622 * @result
623 * <code>true</code> if the addition was successful,
624 * <code>false</code> otherwise.
625 *
626 * @discussion
627 * An OSSymbol for <code>aKey</code> is created internally.
628 * An object already stored under <code>aKey</code> is released.
629 */
630 virtual bool setObject(
631 const OSString * aKey,
632 const OSMetaClassBase * anObject);
633
634 bool setObject(
635 const OSString * aKey,
636 OSSharedPtr<const OSMetaClassBase> const& anObject);
637
638
639/*!
640 * @function setObject
641 *
642 * @abstract
643 * Stores an object in the dictionary under a key.
644 *
645 * @param aKey A C string identifying the object
646 * placed within the dictionary.
647 * @param anObject The object to be stored in the dictionary.
648 * It is automatically retained.
649 *
650 * @result
651 * <code>true</code> if the addition was successful,
652 * <code>false</code> otherwise.
653 *
654 * @discussion
655 * An OSSymbol for <code>aKey</code> is created internally.
656 * An object already stored under <code>aKey</code> is released.
657 */
658 virtual bool setObject(
659 const char * aKey,
660 const OSMetaClassBase * anObject);
661
662 bool setObject(
663 const char * aKey,
664 OSSharedPtr<const OSMetaClassBase> const& anObject);
665
666
667/*!
668 * @function removeObject
669 *
670 * @abstract
671 * Removes a key/object pair from the dictionary.
672 *
673 * @param aKey An OSSymbol identifying the object
674 * to be removed from the dictionary.
675 *
676 * @discussion
677 * The removed key (not necessarily <code>aKey</code> itself)
678 * and object are automatically released.
679 */
680 virtual void removeObject(const OSSymbol * aKey);
681
682
683/*!
684 * @function removeObject
685 *
686 * @abstract
687 * Removes a key/object pair from the dictionary.
688 *
689 * @param aKey A OSString identifying the object
690 * to be removed from the dictionary.
691 *
692 * @discussion
693 * The removed key (not necessarily <code>aKey</code> itself)
694 * and object are automatically released.
695 */
696 virtual void removeObject(const OSString * aKey);
697
698
699/*!
700 * @function removeObject
701 *
702 * @abstract
703 * Removes a key/object pair from the dictionary.
704 *
705 * @param aKey A C string identifying the object
706 * to be removed from the dictionary.
707 *
708 * @discussion
709 * The removed key (internally an OSSymbol)
710 * and object are automatically released.
711 */
712 virtual void removeObject(const char * aKey);
713
714
715/*!
716 * @function merge
717 *
718 * @abstract
719 * Merges the contents of a dictionary into the receiver.
720 *
721 * @param aDictionary The dictionary whose contents
722 * are to be merged with the receiver.
723 * @result
724 * <code>true</code> if the merge succeeds, <code>false</code> otherwise.
725 *
726 * @discussion
727 * If there are keys in <code>aDictionary</code> that match keys
728 * in the receiving dictionary,
729 * then the objects in the receiver are replaced
730 * by those from <code>aDictionary</code>,
731 * and the replaced objects are released.
732 */
733 virtual bool merge(const OSDictionary * aDictionary);
734
735
736/*!
737 * @function getObject
738 *
739 * @abstract
740 * Returns the object stored under a given key.
741 *
742 * @param aKey An OSSymbol key identifying the object
743 * to be returned to the caller.
744 *
745 * @result
746 * The object stored under <code>aKey</code>,
747 * or <code>NULL</code> if the key does not exist in the dictionary.
748 *
749 * @discussion
750 * The returned object will be released if removed from the dictionary;
751 * if you plan to store the reference, you should call
752 * <code>@link
753 * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
754 * retain@/link</code>
755 * on that object.
756 */
757 virtual OSObject * getObject(const OSSymbol * aKey) const;
758
759
760/*!
761 * @function getObject
762 *
763 * @abstract Returns the object stored under a given key.
764 *
765 * @param aKey An OSString key identifying the object
766 * to be returned to caller.
767 *
768 * @result
769 * The object stored under <code>aKey</code>,
770 * or <code>NULL</code> if the key does not exist in the dictionary.
771 *
772 * @discussion
773 * The returned object will be released if removed from the dictionary;
774 * if you plan to store the reference, you should call
775 * <code>@link
776 * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
777 * retain@/link</code>
778 * on that object.
779 */
780 virtual OSObject * getObject(const OSString * aKey) const;
781
782
783/*!
784 * @function getObject
785 *
786 * @abstract
787 * Returns the object stored under a given key.
788 *
789 * @param aKey A C string key identifying the object
790 * to be returned to caller.
791 *
792 * @result
793 * The object stored under <code>aKey</code>,
794 * or <code>NULL</code> if the key does not exist in the dictionary.
795 *
796 * @discussion
797 * The returned object will be released if removed from the dictionary;
798 * if you plan to store the reference, you should call
799 * <code>@link
800 * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
801 * retain@/link</code>
802 * on that object.
803 */
804 virtual OSObject * getObject(const char * aKey) const;
805
806
807/*!
808 * @function isEqualTo
809 *
810 * @abstract Tests the equality of two OSDictionary objects
811 * over a subset of keys.
812 *
813 * @param aDictionary The dictionary to be compared against the receiver.
814 * @param keys An OSArray or OSDictionary containing the keys
815 * (as @link //apple_ref/cpp/cl/OSString OSStrings@/link or
816 * @link //apple_ref/cpp/cl/OSSymbol OSSymbols@/link)
817 * describing the intersection for the comparison.
818 *
819 * @result
820 * <code>true</code> if the intersections
821 * of the two dictionaries are equal.
822 *
823 * @discussion
824 * Two OSDictionary objects are considered equal by this function
825 * if both have objects stored for all keys provided,
826 * and if the objects stored in each under
827 * a given key compare as equal using
828 * <code>@link
829 * //apple_ref/cpp/instm/OSMetaClassBase/isEqualTo/virtualbool/(constOSMetaClassBase*)
830 * isEqualTo@/link</code>.
831 */
832 virtual bool isEqualTo(
833 const OSDictionary * aDictionary,
834 const OSCollection * keys) const;
835
836
837/*!
838 * @function isEqualTo
839 *
840 * @abstract Tests the equality of two OSDictionary objects.
841 *
842 * @param aDictionary The dictionary to be compared against the receiver.
843 *
844 * @result
845 * <code>true</code> if the dictionaries are equal,
846 * <code>false</code> if not.
847 *
848 * @discussion
849 * Two OSDictionary objects are considered equal if they have same count,
850 * the same keys, and if the objects stored in each under
851 * a given key compare as equal using
852 * <code>@link
853 * //apple_ref/cpp/instm/OSMetaClassBase/isEqualTo/virtualbool/(constOSMetaClassBase*)
854 * isEqualTo@/link</code>.
855 */
856 virtual bool isEqualTo(const OSDictionary * aDictionary) const;
857
858
859/*!
860 * @function isEqualTo
861 *
862 * @abstract
863 * Tests the equality of an OSDictionary to an arbitrary object.
864 *
865 * @param anObject An object to be compared against the receiver.
866 *
867 * @result
868 * <code>true</code> if the objects are equal.
869 *
870 * @discussion
871 * An OSDictionary is considered equal to another object
872 * if that object is derived from OSDictionary
873 * and contains the same or equivalent objects.
874 */
875 virtual bool isEqualTo(const OSMetaClassBase * anObject) const APPLE_KEXT_OVERRIDE;
876
877
878/*!
879 * @function serialize
880 *
881 * @abstract
882 * Archives the receiver into the provided
883 * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object.
884 *
885 * @param serializer The OSSerialize object.
886 *
887 * @result
888 * <code>true</code> if serialization succeeds, <code>false</code> if not.
889 */
890 virtual bool serialize(OSSerialize * serializer) const APPLE_KEXT_OVERRIDE;
891
892
893/*!
894 * @function setOptions
895 *
896 * @abstract
897 * Recursively sets option bits in the dictionary
898 * and all child collections.
899 *
900 * @param options A bitfield whose values turn the options on (1) or off (0).
901 * @param mask A mask indicating which bits
902 * in <code>options</code> to change.
903 * Pass 0 to get the whole current options bitfield
904 * without changing any settings.
905 * @param context Unused.
906 *
907 * @result
908 * The options bitfield as it was before the set operation.
909 *
910 * @discussion
911 * Kernel extensions should not call this function.
912 *
913 * Child collections' options are changed only if the receiving dictionary's
914 * options actually change.
915 */
916 virtual unsigned setOptions(
917 unsigned options,
918 unsigned mask,
919 void * context = NULL) APPLE_KEXT_OVERRIDE;
920
921
922/*!
923 * @function copyCollection
924 *
925 * @abstract
926 * Creates a deep copy of the dictionary
927 * and its child collections.
928 *
929 * @param cycleDict A dictionary of all of the collections
930 * that have been copied so far,
931 * which is used to track circular references.
932 * To start the copy at the top level,
933 * pass <code>NULL</code>.
934 *
935 * @result
936 * The newly copied dictionary, with a retain count of 1,
937 * or <code>NULL</code> if there is insufficient memory to do the copy.
938 *
939 * @discussion
940 * The receiving dictionary, and any collections it contains, recursively,
941 * are copied.
942 * Objects that are not derived from OSCollection are retained
943 * rather than copied.
944 */
945 OSPtr<OSCollection> copyCollection(OSDictionary * cycleDict = NULL) APPLE_KEXT_OVERRIDE;
946
947#if XNU_KERNEL_PRIVATE
948 bool setObject(const OSSymbol *aKey, const OSMetaClassBase *anObject, bool onlyAdd);
949 void sortBySymbol(void);
950 OSPtr<OSArray> copyKeys(void);
951#endif /* XNU_KERNEL_PRIVATE */
952
953
954/*!
955 * @function iterateObjects
956 *
957 * @abstract
958 * Invoke a callback for each member of the collection.
959 *
960 * @param refcon A reference constant for the callback.
961 * @param callback The callback function,
962 * called with the refcon and each member key & object
963 * of the dictionary in turn, on the callers thread.
964 * The callback should return true to early terminate
965 * the iteration, false otherwise.
966 *
967 * @result
968 * False if the dictionary iteration was made invalid
969 * (see OSCollectionIterator::isValid()) otherwise true.
970 */
971 bool iterateObjects(void * refcon, bool (*callback)(void * refcon, const OSSymbol * key, OSObject * object));
972
973#ifdef __BLOCKS__
974
975/*!
976 * @function iterateObjects
977 *
978 * @abstract
979 * Invoke a block for each member of the collection.
980 *
981 * @param block The block,
982 * called with the refcon and each member key & object
983 * of the dictionary in turn, on the callers thread.
984 * The callback should return true to early terminate
985 * the iteration, false otherwise.
986 *
987 * @result
988 * False if the dictionary iteration was made invalid
989 * (see OSCollectionIterator::isValid()) otherwise true.
990 */
991 bool iterateObjects(bool (^block)(const OSSymbol * key, OSObject * object));
992
993#endif /* __BLOCKS__ */
994
995 OSMetaClassDeclareReservedUnused(OSDictionary, 0);
996 OSMetaClassDeclareReservedUnused(OSDictionary, 1);
997 OSMetaClassDeclareReservedUnused(OSDictionary, 2);
998 OSMetaClassDeclareReservedUnused(OSDictionary, 3);
999 OSMetaClassDeclareReservedUnused(OSDictionary, 4);
1000 OSMetaClassDeclareReservedUnused(OSDictionary, 5);
1001 OSMetaClassDeclareReservedUnused(OSDictionary, 6);
1002 OSMetaClassDeclareReservedUnused(OSDictionary, 7);
1003};
1004
1005#endif /* !_IOKIT_IODICTIONARY_H */
1006