libkern/libkern/c++/OSDictionary.h

   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     OSDeclareDefaultStructors(OSDictionary)
 116
 117 protected:
 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
 137 public:
 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 */