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