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 | |
42 | class OSArray; |
43 | class OSSymbol; |
44 | class 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 | */ |
113 | class OSDictionary : public OSCollection |
114 | { |
115 | friend class OSSerialize; |
116 | |
117 | OSDeclareDefaultStructors(OSDictionary) |
118 | |
119 | #if APPLE_KEXT_ALIGN_CONTAINERS |
120 | |
121 | protected: |
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 | |
133 | protected: |
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 | |
155 | public: |
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 | |