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