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