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     friend class OSSerialize;
 116
 117     OSDeclareDefaultStructors(OSDictionary)
 118
 119 #if APPLE_KEXT_ALIGN_CONTAINERS
 120
 121 protected:
 122     unsigned int   count;
 123     unsigned int   capacity;
 124     unsigned int   capacityIncrement;
 125     struct dictEntry {
 126         const OSSymbol        * key;
 127         const OSMetaClassBase * value;
 128     };
 129     dictEntry    * dictionary;
 130
 131 #else /* APPLE_KEXT_ALIGN_CONTAINERS */
 132
 133 protected:
 134     struct dictEntry {
 135         const OSSymbol        * key;
 136         const OSMetaClassBase * value;
 137     };
 138     dictEntry    * dictionary;
 139     unsigned int   count;
 140     unsigned int   capacity;
 141     unsigned int   capacityIncrement;
 142
 143     struct ExpansionData { };
 144
 145    /* Reserved for future use.  (Internal use only)  */
 146     ExpansionData * reserved;
 147
 148 #endif /* APPLE_KEXT_ALIGN_CONTAINERS */
 149
 150     // Member functions used by the OSCollectionIterator class.
 151     virtual unsigned int iteratorSize() const APPLE_KEXT_OVERRIDE;
 152     virtual bool initIterator(void * iterator) const APPLE_KEXT_OVERRIDE;
 153     virtual bool getNextObjectForIterator(void * iterator, OSObject ** ret) const APPLE_KEXT_OVERRIDE;
 154
 155 public:
 156
 157    /*!
 158     * @function withCapacity
 159     *
 160     * @abstract
 161     * Creates and initializes an empty OSDictionary.
 162     *
 163     * @param  capacity  The initial storage capacity of the new dictionary object.
 164     *
 165     * @result
 166     * An empty instance of OSDictionary
 167     * with a retain count of 1;
 168     * <code>NULL</code> on failure.
 169     *
 170     * @discussion
 171     * <code>capacity</code> must be nonzero.
 172     * The new dictionary will grow as needed to accommodate more key/object pairs
 173     * (<i>unlike</i> @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
 174     * for which the initial capacity is a hard limit).
 175     */
 176     static OSDictionary * withCapacity(unsigned int capacity);
 177
 178
 179    /*!
 180     * @function withObjects
 181     *
 182     * @abstract Creates and initializes an OSDictionary
 183     *           populated with keys and objects provided.
 184     *
 185     * @param objects   A C array of OSMetaClassBase-derived objects.
 186     * @param keys      A C array of OSSymbol keys
 187     *                  for the corresponding objects in <code>objects</code>.
 188     * @param count     The number of keys and objects
 189     *                  to be placed into the dictionary.
 190     * @param capacity  The initial storage capacity of the new dictionary object.
 191     *                  If 0, <code>count</code> is used; otherwise this value
 192     *                  must be greater than or equal to <code>count</code>.
 193     *
 194     * @result
 195     * An instance of OSDictionary
 196     * containing the key/object pairs provided,
 197     * with a retain count of 1;
 198     * <code>NULL</code> on failure.
 199     *
 200     * @discussion
 201     * <code>objects</code> and <code>keys</code> must be non-<code>NULL</code>,
 202     * and <code>count</code> must be nonzero.
 203     * If <code>capacity</code> is nonzero,
 204     * it must be greater than or equal to <code>count</code>.
 205     * The new dictionary will grow as needed
 206     * to accommodate more key/object pairs
 207     * (<i>unlike</i>
 208     * @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
 209     * for which the initial capacity is a hard limit).
 210     */
 211     static OSDictionary * withObjects(
 212         const OSObject * objects[],
 213         const OSSymbol * keys[],
 214         unsigned int     count,
 215         unsigned int     capacity = 0);
 216
 217    /*!
 218     * @function withObjects
 219     *
 220     * @abstract
 221     * Creates and initializes an OSDictionary
 222     * populated with keys and objects provided.
 223     *
 224     * @param objects   A C array of OSMetaClassBase-derived objects.
 225     * @param keys      A C array of OSString keys for the corresponding objects
 226     *                  in <code>objects</code>.
 227     * @param count     The number of keys and objects
 228     *                  to be placed into the dictionary.
 229     * @param capacity  The initial storage capacity of the new dictionary object.
 230     *                  If 0, <code>count</code> is used; otherwise this value
 231     *                  must be greater than or equal to <code>count</code>.
 232     *
 233     * @result
 234     * An instance of OSDictionary
 235     * containing the key/object pairs provided,
 236     * with a retain count of 1;
 237     * <code>NULL</code> on failure.
 238     *
 239     * @discussion
 240     * <code>objects</code> and <code>keys</code> must be non-<code>NULL</code>,
 241     * and <code>count</code> must be nonzero.
 242     * If <code>capacity</code> is nonzero, it must be greater than or equal to <code>count</code>.
 243     * The new dictionary will grow as needed
 244     * to accommodate more key/object pairs
 245     * (<i>unlike</i>
 246     * @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
 247     * for which the initial capacity is a hard limit).
 248     */
 249     static OSDictionary * withObjects(
 250         const OSObject * objects[],
 251         const OSString * keys[],
 252         unsigned int     count,
 253         unsigned int     capacity = 0);
 254
 255
 256    /*!
 257     * @function withDictionary
 258     *
 259     * @abstract
 260     * Creates and initializes an OSDictionary
 261     * populated with the contents of another dictionary.
 262     *
 263     * @param dict      A dictionary whose contents will be stored
 264     *                  in the new instance.
 265     * @param capacity  The initial storage capacity of the new dictionary object.
 266     *                  If 0, the capacity is set to the number of key/value pairs
 267     *                  in <code>dict</code>;
 268     *                  otherwise <code>capacity</code> must be greater than or equal to
 269     *                  the number of key/value pairs in <code>dict</code>.
 270     *
 271     * @result
 272     * An instance of OSDictionary
 273     * containing the key/value pairs of <code>dict</code>,
 274     * with a retain count of 1;
 275     * <code>NULL</code> on failure.
 276     *
 277     * @discussion
 278     * <code>dict</code> must be non-<code>NULL</code>.
 279     * If <code>capacity</code> is nonzero, it must be greater than or equal to <code>count</code>.
 280     * The new dictionary will grow as needed
 281     * to accommodate more key/object pairs
 282     * (<i>unlike</i>
 283     *  @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
 284     * for which the initial capacity is a hard limit).
 285     *
 286     * The keys and objects in <code>dict</code> are retained for storage
 287     * in the new OSDictionary,
 288     * not copied.
 289     */
 290     static OSDictionary * withDictionary(
 291         const OSDictionary * dict,
 292         unsigned int         capacity = 0);
 293
 294
 295    /*!
 296     * @function initWithCapacity
 297     *
 298     * @abstract
 299     * Initializes a new instance of OSDictionary.
 300     *
 301     * @param capacity  The initial storage capacity of the new dictionary object.
 302     * @result
 303     * <code>true</code> on success, <code>false</code> on failure.
 304     *
 305     * @discussion
 306     * Not for general use. Use the static instance creation method
 307     * <code>@link //apple_ref/cpp/clm/OSDictionary/withCapacity/staticOSDictionary*\/(unsignedint)
 308     * withCapacity@/link</code>
 309     * instead.
 310     *
 311     * <code>capacity</code> must be nonzero.
 312     * The new dictionary will grow as needed
 313     * to accommodate more key/object pairs
 314     * (<i>unlike</i>
 315     * @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
 316     * for which the initial capacity is a hard limit).
 317     */
 318     virtual bool initWithCapacity(unsigned int capacity);
 319
 320
 321    /*!
 322     * @function initWithObjects
 323     *
 324     * @abstract Initializes a new OSDictionary with keys and objects provided.
 325     *
 326     * @param objects   A C array of OSMetaClassBase-derived objects.
 327     * @param keys      A C array of OSSymbol keys
 328     *                  for the corresponding objects in <code>objects</code>.
 329     * @param count     The number of keys and objects to be placed
 330     *                  into the dictionary.
 331     * @param capacity  The initial storage capacity of the new dictionary object.
 332     *                  If 0, <code>count</code> is used; otherwise this value
 333     *                  must be greater than or equal to <code>count</code>.
 334     *
 335     * @result
 336     * <code>true</code> on success, <code>false</code> on failure.
 337     *
 338     * @discussion
 339     * Not for general use. Use the static instance creation method
 340     * <code>@link
 341     * //apple_ref/cpp/clm/OSDictionary/withObjects/staticOSDictionary*\/(constOSObject*,constOSString*,unsignedint,unsignedint)
 342     * withObjects@/link</code>
 343     * instead.
 344     *
 345     * <code>objects</code> and <code>keys</code> must be non-<code>NULL</code>,
 346     * and <code>count</code> must be nonzero.
 347     * If <code>capacity</code> is nonzero,
 348     * it must be greater than or equal to <code>count</code>.
 349     * The new dictionary will grow as neede
 350     * to accommodate more key/object pairs
 351     * (<i>unlike</i>
 352     * @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
 353     * for which the initial capacity is a hard limit).
 354     */
 355     virtual bool initWithObjects(
 356         const OSObject * objects[],
 357         const OSSymbol * keys[],
 358         unsigned int     count,
 359         unsigned int     capacity = 0);
 360
 361
 362    /*!
 363     * @function initWithObjects
 364     *
 365     * @abstract
 366     * Initializes a new OSDictionary with keys and objects provided.
 367     *
 368     * @param objects   A C array of OSMetaClassBase-derived objects.
 369     * @param keys      A C array of OSString keys
 370     *                  for the corresponding objects in <code>objects</code>.
 371     * @param count     The number of keys and objects
 372     *                  to be placed into the dictionary.
 373     * @param capacity  The initial storage capacity of the new dictionary object.
 374     *                  If 0, <code>count</code> is used; otherwise this value
 375     *                  must be greater than or equal to <code>count</code>.
 376     *
 377     * @result
 378     * <code>true</code> on success, <code>false</code> on failure.
 379     *
 380     * @discussion
 381     * Not for general use. Use the static instance creation method
 382     * <code>@link
 383     * //apple_ref/cpp/clm/OSDictionary/withObjects/staticOSDictionary*\/(constOSObject*,constOSString*,unsignedint,unsignedint)
 384     * withObjects@/link</code>
 385     * instead.
 386     *
 387     * <code>objects</code> and <code>keys</code> must be non-<code>NULL</code>,
 388     * and <code>count</code> must be nonzero.
 389     * If <code>capacity</code> is nonzero, it must be greater than or equal to <code>count</code>.
 390     * The new dictionary will grow as needed
 391     * to accommodate more key/object pairs
 392     * (<i>unlike</i>
 393     * @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
 394     * for which the initial capacity is a hard limit).
 395     */
 396     virtual bool initWithObjects(
 397         const OSObject * objects[],
 398         const OSString * keys[],
 399         unsigned int     count,
 400         unsigned int     capacity = 0);
 401
 402
 403    /*!
 404     * @function initWithDictionary
 405     *
 406     * @abstract
 407     * Initializes a new OSDictionary
 408     * with the contents of another dictionary.
 409     *
 410     * @param dict      A dictionary whose contents will be placed
 411     *                  in the new instance.
 412     * @param capacity  The initial storage capacity of the new dictionary object.
 413     *                  If 0, the capacity is set to the number of key/value pairs
 414     *                  in <code>dict</code>;
 415     *                  otherwise <code>capacity</code> must be greater than or equal to
 416     *                  the number of key/value pairs in <code>dict</code>.
 417     *
 418     * @result
 419     * <code>true</code> on success, <code>false</code> on failure.
 420     *
 421     * @discussion
 422     * Not for general use. Use the static instance creation method
 423     * <code>@link withDictionary withDictionary@/link</code> instead.
 424     *
 425     * <code>dict</code> must be non-<code>NULL</code>.
 426     * If <code>capacity</code> is nonzero,
 427     * it must be greater than or equal to <code>count</code>.
 428     * The new dictionary will grow as needed
 429     * to accommodate more key/object pairs
 430     * (<i>unlike</i>
 431     * @link //apple_ref/doc/uid/20001497 CFMutableDictionary@/link,
 432     * for which the initial capacity is a hard limit).
 433     *
 434     * The keys and objects in <code>dict</code> are retained for storage
 435     * in the new OSDictionary,
 436     * not copied.
 437     */
 438     virtual bool initWithDictionary(
 439         const OSDictionary * dict,
 440         unsigned int         capacity = 0);
 441
 442
 443    /*!
 444     * @function free
 445     *
 446     * @abstract
 447     * Deallocates or releases any resources
 448     * used by the OSDictionary instance.
 449     *
 450     * @discussion
 451     * This function should not be called directly,
 452     * use
 453     * <code>@link
 454     * //apple_ref/cpp/instm/OSObject/release/virtualvoid/()
 455     * release@/link</code>
 456     * instead.
 457     */
 458     virtual void free() APPLE_KEXT_OVERRIDE;
 459
 460
 461    /*!
 462     * @function getCount
 463     *
 464     * @abstract
 465     * Returns the current number of key/object pairs
 466     * contained within the dictionary.
 467     *
 468     * @result
 469     * The current number of key/object pairs
 470     * contained within the dictionary.
 471     */
 472     virtual unsigned int getCount() const APPLE_KEXT_OVERRIDE;
 473
 474
 475    /*!
 476     * @function getCapacity
 477     *
 478     * @abstract
 479     * Returns the number of objects the dictionary can store without reallocating.
 480     *
 481     * @result
 482     * The number objects the dictionary can store without reallocating.
 483     *
 484     * @discussion
 485     * OSDictionary objects grow when full
 486     * to accommodate additional key/object pairs.
 487     * See
 488     * <code>@link
 489     * //apple_ref/cpp/instm/OSDictionary/getCapacityIncrement/virtualunsignedint/()
 490     * getCapacityIncrement@/link</code>
 491     * and
 492     * <code>@link
 493     * //apple_ref/cpp/instm/OSDictionary/ensureCapacity/virtualunsignedint/(unsignedint)
 494     * ensureCapacity@/link</code>.
 495     */
 496     virtual unsigned int getCapacity() const APPLE_KEXT_OVERRIDE;
 497
 498
 499    /*!
 500     * @function getCapacityIncrement
 501     *
 502     * @abstract
 503     * Returns the storage increment of the dictionary.
 504     *
 505     * @result
 506     * The storage increment of the dictionary.
 507     *
 508     * @discussion
 509     * An OSDictionary allocates storage for key/object pairs in multiples
 510     * of the capacity increment.
 511     */
 512     virtual unsigned int getCapacityIncrement() const APPLE_KEXT_OVERRIDE;
 513
 514
 515    /*!
 516     * @function setCapacityIncrement
 517     *
 518     * @abstract
 519     * Sets the storage increment of the dictionary.
 520     *
 521     * @result
 522     * The new storage increment of the dictionary,
 523     * which may be different from the number requested.
 524     *
 525     * @discussion
 526     * An OSDictionary allocates storage for key/object pairs in multiples
 527     * of the capacity increment.
 528     * Calling this function does not immediately reallocate storage.
 529     */
 530     virtual unsigned int setCapacityIncrement(unsigned increment) APPLE_KEXT_OVERRIDE;
 531
 532
 533    /*!
 534     * @function ensureCapacity
 535     *
 536     * @abstract
 537     * Ensures the dictionary has enough space
 538     * to store the requested number of key/object  pairs.
 539     *
 540     * @param newCapacity  The total number of key/object pairs the dictionary
 541     *                     should be able to store.
 542     *
 543     * @result
 544     * The new capacity of the dictionary,
 545     * which may be different from the number requested
 546     * (if smaller, reallocation of storage failed).
 547     *
 548     * @discussion
 549     * This function immediately resizes the dictionary, if necessary,
 550     * to accommodate at least <code>newCapacity</code> key/object pairs.
 551     * If <code>newCapacity</code> is not greater than the current capacity,
 552     * or if an allocation error occurs, the original capacity is returned.
 553     *
 554     * There is no way to reduce the capacity of an OSDictionary.
 555     */
 556     virtual unsigned int ensureCapacity(unsigned int newCapacity) APPLE_KEXT_OVERRIDE;
 557
 558
 559    /*!
 560     * @function flushCollection
 561     *
 562     * @abstract
 563     * Removes and releases all keys and objects within the dictionary.
 564     *
 565     * @discussion
 566     * The dictionary's capacity (and therefore direct memory consumption)
 567     * is not reduced by this function.
 568     */
 569     virtual void flushCollection() APPLE_KEXT_OVERRIDE;
 570
 571
 572    /*!
 573     * @function setObject
 574     *
 575     * @abstract
 576     * Stores an object in the dictionary under a key.
 577     *
 578     * @param aKey      An OSSymbol identifying the object
 579     *                  placed within the dictionary.
 580     *                  It is automatically retained.
 581     * @param anObject  The object to be stored in the dictionary.
 582     *                  It is automatically retained.
 583     *
 584     * @result
 585     * <code>true</code> if the addition was successful,
 586     * <code>false</code> otherwise.
 587     *
 588     * @discussion
 589     * An object already stored under <code>aKey</code> is released.
 590     */
 591     virtual bool setObject(
 592         const OSSymbol        * aKey,
 593         const OSMetaClassBase * anObject);
 594
 595
 596    /*!
 597     * @function setObject
 598     *
 599     * @abstract Stores an object in the dictionary under a key.
 600     *
 601     * @param aKey      An OSString identifying the object
 602     *                  placed within the dictionary.
 603     * @param anObject  The object to be stored in the dictionary.
 604     *                  It is automatically retained.
 605     *
 606     * @result
 607     * <code>true</code> if the addition was successful,
 608     * <code>false</code> otherwise.
 609     *
 610     * @discussion
 611     * An OSSymbol for <code>aKey</code> is created internally.
 612     * An object already stored under <code>aKey</code> is released.
 613     */
 614     virtual bool setObject(
 615         const OSString        * aKey,
 616         const OSMetaClassBase * anObject);
 617
 618
 619    /*!
 620     * @function setObject
 621     *
 622     * @abstract
 623     * Stores an object in the dictionary under a key.
 624     *
 625     * @param aKey      A C string identifying the object
 626     *                  placed within the dictionary.
 627     * @param anObject  The object to be stored in the dictionary.
 628     *                  It is automatically retained.
 629     *
 630     * @result
 631     * <code>true</code> if the addition was successful,
 632     * <code>false</code> otherwise.
 633     *
 634     * @discussion
 635     * An OSSymbol for <code>aKey</code> is created internally.
 636     * An object already stored under <code>aKey</code> is released.
 637     */
 638     virtual bool setObject(
 639         const char            * aKey,
 640         const OSMetaClassBase * anObject);
 641
 642
 643    /*!
 644     * @function removeObject
 645     *
 646     * @abstract
 647     * Removes a key/object pair from the dictionary.
 648     *
 649     * @param aKey  An OSSymbol identifying the object
 650     *              to be removed from the dictionary.
 651     *
 652     * @discussion
 653     * The removed key (not necessarily <code>aKey</code> itself)
 654     * and object are automatically released.
 655     */
 656     virtual void removeObject(const OSSymbol * aKey);
 657
 658
 659    /*!
 660     * @function removeObject
 661     *
 662     * @abstract
 663     * Removes a key/object pair from the dictionary.
 664     *
 665     * @param aKey  A OSString identifying the object
 666     *              to be removed from the dictionary.
 667     *
 668     * @discussion
 669     * The removed key (not necessarily <code>aKey</code> itself)
 670     * and object are automatically released.
 671     */
 672     virtual void removeObject(const OSString * aKey);
 673
 674
 675    /*!
 676     * @function removeObject
 677     *
 678     * @abstract
 679     * Removes a key/object pair from the dictionary.
 680     *
 681     * @param aKey  A C string identifying the object
 682     *              to be removed from the dictionary.
 683     *
 684     * @discussion
 685     * The removed key (internally an OSSymbol)
 686     * and object are automatically released.
 687     */
 688     virtual void removeObject(const char * aKey);
 689
 690
 691    /*!
 692     * @function merge
 693     *
 694     * @abstract
 695     * Merges the contents of a dictionary into the receiver.
 696     *
 697     * @param aDictionary  The dictionary whose contents
 698     *                     are to be merged with the receiver.
 699     * @result
 700     * <code>true</code> if the merge succeeds, <code>false</code> otherwise.
 701     *
 702     * @discussion
 703     * If there are keys in <code>aDictionary</code> that match keys
 704     * in the receiving dictionary,
 705     * then the objects in the receiver are replaced
 706     * by those from <code>aDictionary</code>,
 707     * and the replaced objects are released.
 708     */
 709     virtual bool merge(const OSDictionary * aDictionary);
 710
 711
 712    /*!
 713     * @function getObject
 714     *
 715     * @abstract
 716     * Returns the object stored under a given key.
 717     *
 718     * @param aKey  An OSSymbol key identifying the object
 719     *              to be returned to the caller.
 720     *
 721     * @result
 722     * The object stored under <code>aKey</code>,
 723     * or <code>NULL</code> if the key does not exist in the dictionary.
 724     *
 725     * @discussion
 726     * The returned object will be released if removed from the dictionary;
 727     * if you plan to store the reference, you should call
 728     * <code>@link
 729     * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
 730     * retain@/link</code>
 731     * on that object.
 732     */
 733     virtual OSObject * getObject(const OSSymbol * aKey) const;
 734
 735
 736    /*!
 737     * @function getObject
 738     *
 739     * @abstract Returns the object stored under a given key.
 740     *
 741     * @param aKey  An OSString key identifying the object
 742     *              to be returned to caller.
 743     *
 744     * @result
 745     * The object stored under <code>aKey</code>,
 746     * or <code>NULL</code> if the key does not exist in the dictionary.
 747     *
 748     * @discussion
 749     * The returned object will be released if removed from the dictionary;
 750     * if you plan to store the reference, you should call
 751     * <code>@link
 752     * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
 753     * retain@/link</code>
 754     * on that object.
 755     */
 756     virtual OSObject * getObject(const OSString * aKey) const;
 757
 758
 759    /*!
 760     * @function getObject
 761     *
 762     * @abstract
 763     * Returns the object stored under a given key.
 764     *
 765     * @param aKey  A C string key identifying the object
 766     *              to be returned to caller.
 767     *
 768     * @result
 769     * The object stored under <code>aKey</code>,
 770     * or <code>NULL</code> if the key does not exist in the dictionary.
 771     *
 772     * @discussion
 773     * The returned object will be released if removed from the dictionary;
 774     * if you plan to store the reference, you should call
 775     * <code>@link
 776     * //apple_ref/cpp/instm/OSObject/retain/virtualvoid/()
 777     * retain@/link</code>
 778     * on that object.
 779     */
 780     virtual OSObject * getObject(const char * aKey) const;
 781
 782
 783    /*!
 784     * @function isEqualTo
 785     *
 786     * @abstract Tests the equality of two OSDictionary objects
 787     * over a subset of keys.
 788     *
 789     * @param aDictionary  The dictionary to be compared against the receiver.
 790     * @param keys         An OSArray or OSDictionary containing the keys
 791     *                     (as @link //apple_ref/cpp/cl/OSString OSStrings@/link or
 792     *                     @link //apple_ref/cpp/cl/OSSymbol OSSymbols@/link)
 793     *                     describing the intersection for the comparison.
 794     *
 795     * @result
 796     * <code>true</code> if the intersections
 797     * of the two dictionaries are equal.
 798     *
 799     * @discussion
 800     * Two OSDictionary objects are considered equal by this function
 801     * if both have objects stored for all keys provided,
 802     * and if the objects stored in each under
 803     * a given key compare as equal using
 804     * <code>@link
 805     * //apple_ref/cpp/instm/OSMetaClassBase/isEqualTo/virtualbool/(constOSMetaClassBase*)
 806     * isEqualTo@/link</code>.
 807     */
 808     virtual bool isEqualTo(
 809         const OSDictionary * aDictionary,
 810         const OSCollection * keys) const;
 811
 812
 813    /*!
 814     * @function isEqualTo
 815     *
 816     * @abstract Tests the equality of two OSDictionary objects.
 817     *
 818     * @param aDictionary  The dictionary to be compared against the receiver.
 819     *
 820     * @result
 821     * <code>true</code> if the dictionaries are equal,
 822     * <code>false</code> if not.
 823     *
 824     * @discussion
 825     * Two OSDictionary objects are considered equal if they have same count,
 826     * the same keys, and if the objects stored in each under
 827     * a given key compare as equal using
 828     * <code>@link
 829     * //apple_ref/cpp/instm/OSMetaClassBase/isEqualTo/virtualbool/(constOSMetaClassBase*)
 830     * isEqualTo@/link</code>.
 831     */
 832     virtual bool isEqualTo(const OSDictionary * aDictionary) const;
 833
 834
 835    /*!
 836     * @function isEqualTo
 837     *
 838     * @abstract
 839     * Tests the equality of an OSDictionary to an arbitrary object.
 840     *
 841     * @param anObject An object to be compared against the receiver.
 842     *
 843     * @result
 844     * <code>true</code> if the objects are equal.
 845     *
 846     * @discussion
 847     * An OSDictionary is considered equal to another object
 848     * if that object is derived from OSDictionary
 849     * and contains the same or equivalent objects.
 850     */
 851     virtual bool isEqualTo(const OSMetaClassBase * anObject) const APPLE_KEXT_OVERRIDE;
 852
 853
 854    /*!
 855     * @function serialize
 856     *
 857     * @abstract
 858     * Archives the receiver into the provided
 859     * @link //apple_ref/doc/class/OSSerialize OSSerialize@/link object.
 860     *
 861     * @param serializer  The OSSerialize object.
 862     *
 863     * @result
 864     * <code>true</code> if serialization succeeds, <code>false</code> if not.
 865     */
 866     virtual bool serialize(OSSerialize * serializer) const APPLE_KEXT_OVERRIDE;
 867
 868
 869    /*!
 870     * @function setOptions
 871     *
 872     * @abstract
 873     * Recursively sets option bits in the dictionary
 874     * and all child collections.
 875     *
 876     * @param options  A bitfield whose values turn the options on (1) or off (0).
 877     * @param mask     A mask indicating which bits
 878     *                 in <code>options</code> to change.
 879     *                 Pass 0 to get the whole current options bitfield
 880     *                 without changing any settings.
 881     * @param context  Unused.
 882     *
 883     * @result
 884     * The options bitfield as it was before the set operation.
 885     *
 886     * @discussion
 887     * Kernel extensions should not call this function.
 888     *
 889     * Child collections' options are changed only if the receiving dictionary's
 890     * options actually change.
 891     */
 892     virtual unsigned setOptions(
 893         unsigned   options,
 894         unsigned   mask,
 895         void     * context = 0) APPLE_KEXT_OVERRIDE;
 896
 897
 898    /*!
 899     * @function copyCollection
 900     *
 901     * @abstract
 902     * Creates a deep copy of the dictionary
 903     * and its child collections.
 904     *
 905     * @param cycleDict  A dictionary of all of the collections
 906     *                   that have been copied so far,
 907     *                   which is used to track circular references.
 908     *                   To start the copy at the top level,
 909     *                   pass <code>NULL</code>.
 910     *
 911     * @result
 912     * The newly copied dictionary, with a retain count of 1,
 913     * or <code>NULL</code> if there is insufficient memory to do the copy.
 914     *
 915     * @discussion
 916     * The receiving dictionary, and any collections it contains, recursively,
 917     * are copied.
 918     * Objects that are not derived from OSCollection are retained
 919     * rather than copied.
 920     */
 921     OSCollection * copyCollection(OSDictionary * cycleDict = 0) APPLE_KEXT_OVERRIDE;
 922
 923 #if XNU_KERNEL_PRIVATE
 924     bool setObject(const OSSymbol *aKey, const OSMetaClassBase *anObject, bool onlyAdd);
 925     OSArray * copyKeys(void);
 926 #endif /* XNU_KERNEL_PRIVATE */
 927
 928     OSMetaClassDeclareReservedUnused(OSDictionary, 0);
 929     OSMetaClassDeclareReservedUnused(OSDictionary, 1);
 930     OSMetaClassDeclareReservedUnused(OSDictionary, 2);
 931     OSMetaClassDeclareReservedUnused(OSDictionary, 3);
 932     OSMetaClassDeclareReservedUnused(OSDictionary, 4);
 933     OSMetaClassDeclareReservedUnused(OSDictionary, 5);
 934     OSMetaClassDeclareReservedUnused(OSDictionary, 6);
 935     OSMetaClassDeclareReservedUnused(OSDictionary, 7);
 936 };
 937
 938 #endif /* !_IOKIT_IODICTIONARY_H */