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