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     friend class OSSerialize;
 117
 118 protected:
 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
 138 public:
 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 */