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