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     @class OSDictionary
  48     @abstract A collection class whose instances maintain a list of object references.  Objects in the collection are acquired with unique associative keys.
  49     @discussion
  50     An instance of OSDictionary is a mutable container which contains a list of OSMetaClassBase derived object references and these objects are identified and acquired by unique associative keys.  When an object is placed into a dictionary, a unique identifier or key must provided to identify the object within the collection. The key then must be provided to find the object within the collection.  If an object is not found within the collection, a 0 is returned.  Placing an object into a dictionary for a key, which already identifies an object within that dictionary, will replace the current object with the new object.
  51
  52     Objects placed into a dictionary are automatically retained and objects removed or replaced are automatically released.  All objects are released when the collection is freed.
  53 */
  54 class OSDictionary : public OSCollection
  55 {
  56     OSDeclareDefaultStructors(OSDictionary)
  57
  58 protected:
  59     struct dictEntry {
  60         const OSSymbol *key;
  61         const OSMetaClassBase *value;
  62     };
  63     dictEntry *dictionary;
  64     unsigned int count;
  65     unsigned int capacity;
  66     unsigned int capacityIncrement;
  67
  68     struct ExpansionData { };
  69
  70     /*! @var reserved
  71         Reserved for future use.  (Internal use only)  */
  72     ExpansionData *reserved;
  73
  74     // Member functions used by the OSCollectionIterator class.
  75     virtual unsigned int iteratorSize() const;
  76     virtual bool initIterator(void *iterator) const;
  77     virtual bool getNextObjectForIterator(void *iterator, OSObject **ret) const;
  78
  79 public:
  80     /*!
  81         @function withCapacity
  82         @abstract A static constructor function to create and initialize an instance of OSDictionary.
  83         @param capacity The initial storage capacity of the dictionary object.
  84         @result Returns an instance of OSDictionary or 0 on failure.
  85     */
  86     static OSDictionary *withCapacity(unsigned int capacity);
  87     /*!
  88         @function withObjects
  89         @abstract A static constructor function to create and initialize an instance of OSDictionary and populate it with objects provided.
  90         @param objects A static array of OSMetaClassBase derived objects.
  91         @param keys A static array of OSSymbol keys.
  92         @param count The number of items to be placed into the dictionary.
  93         @param capacity The initial storage capacity of the dictionary object.  If 0, the capacity will be set to the size of 'count', else this value must be greater or equal to 'count'.
  94         @result Returns an instance of OSDictionary or 0 on failure.
  95     */
  96     static OSDictionary *withObjects(const OSObject *objects[],
  97                                      const OSSymbol *keys[],
  98                                      unsigned int count,
  99                                      unsigned int capacity = 0);
 100     /*!
 101         @function withObjects
 102         @abstract A static constructor function to create and initialize an instance of OSDictionary and populate it with objects provided.
 103         @param objects A static array of OSMetaClassBase derived objects.
 104         @param keys A static array of OSString keys.
 105         @param count The number of items to be placed into the dictionary.
 106         @param capacity The initial storage capacity of the dictionary object.  If 0, the capacity will be set to the size of 'count', else this value must be greater or equal to 'count'.
 107         @result Returns an instance of OSDictionary or 0 on failure.
 108     */
 109     static OSDictionary *withObjects(const OSObject *objects[],
 110                                      const OSString *keys[],
 111                                      unsigned int count,
 112                                      unsigned int capacity = 0);
 113     /*!
 114         @function withDictionary
 115         @abstract A static constructor function to create and initialize an instance of OSDictionary and populate it with objects from another dictionary.
 116         @param dict A dictionary whose contents will be placed in the new instance.
 117         @param capacity The initial storage capacity of the dictionary object.  If 0, the capacity will be set to the number of elements in the dictionary object, else the capacity must be greater than or equal to the number of elements in the dictionary.
 118         @result Returns an instance of OSDictionary or 0 on failure.
 119     */
 120     static OSDictionary *withDictionary(const OSDictionary *dict,
 121                                         unsigned int capacity = 0);
 122
 123     /*!
 124         @function initWithCapacity
 125         @abstract A member function to initialize an instance of OSDictionary.
 126         @param capacity The initial storage capacity of the dictionary object.
 127         @result Returns true if initialization succeeded or false on failure.
 128     */
 129     virtual bool initWithCapacity(unsigned int capacity);
 130     /*!
 131         @function initWithObjects
 132         @abstract A member function to initialize an instance of OSDictionary and populate it with the provided objects and keys.
 133         @param objects A static array of OSMetaClassBase derived objects to be placed into the dictionary.
 134         @param keys A static array of OSSymbol keys which identify the corresponding objects provided in the 'objects' parameter.
 135         @param count The number of objects provided to the dictionary.
 136         @param capacity The initial storage capacity of the dictionary object.  If 0, the capacity will be set to the size of 'count', else the capacity must be greater than or equal to the value of 'count'.
 137         @result Returns true if initialization succeeded or false on failure.
 138     */
 139     virtual bool initWithObjects(const OSObject *objects[],
 140                                  const OSSymbol *keys[],
 141                                  unsigned int count,
 142                                  unsigned int capacity = 0);
 143     /*!
 144         @function initWithObjects
 145         @abstract A member function to initialize an instance of OSDictionary and populate it with the provided objects and keys.
 146         @param objects A static array of OSMetaClassBase derived objects to be placed into the dictionary.
 147         @param keys A static array of OSString keys which identify the corresponding objects provided in the 'objects' parameter.
 148         @param count The number of objects provided to the dictionary.
 149         @param capacity The initial storage capacity of the dictionary object.  If 0, the capacity will be set to the size of 'count', else the capacity must be greater than or equal to the value of 'count'.
 150         @result Returns true if initialization succeeded or false on failure.
 151     */
 152     virtual bool initWithObjects(const OSObject *objects[],
 153                                  const OSString *keys[],
 154                                  unsigned int count,
 155                                  unsigned int capacity = 0);
 156     /*!
 157         @function initWithDictionary
 158         @abstract A member function to initialize an instance of OSDictionary and populate it with the contents of another dictionary.
 159         @param dict The dictionary containing the objects to be used to populate the receiving dictionary.
 160         @param capacity The initial storage capacity of the dictionary.  If 0, the value of capacity will be set to the number of elements in the dictionary object, else the value of capacity must be greater than or equal to the number of elements in the dictionary object.
 161         @result Returns true if initialization succeeded or false on failure.
 162     */
 163     virtual bool initWithDictionary(const OSDictionary *dict,
 164                                     unsigned int capacity = 0);
 165     /*!
 166         @function free
 167         @abstract A member functions to deallocate and release all resources used by the OSDictionary instance.
 168         @discussion This function should not be called directly, use release() instead.
 169     */
 170     virtual void free();
 171
 172     /*!
 173         @function getCount
 174         @abstract A member function which returns the current number of objects within the collection.
 175         @result Returns the number of objects contained within the dictionary.
 176     */
 177     virtual unsigned int getCount() const;
 178     /*!
 179         @function getCapacity
 180         @abstract A member function which returns the storage capacity of the collection.
 181         @result Returns the storage capacity of the dictionary.
 182     */
 183     virtual unsigned int getCapacity() const;
 184     /*!
 185         @function getCapacityIncrement
 186         @abstract A member function which returns the growth size for the collection.
 187     */
 188     virtual unsigned int getCapacityIncrement() const;
 189     /*!
 190         @function setCapacityIncrement
 191         @abstract A member function to set the growth size of the collection.
 192         @param increment The new growth size.
 193         @result Returns the new capacity increment.
 194     */
 195     virtual unsigned int setCapacityIncrement(unsigned increment);
 196
 197     /*!
 198         @function ensureCapacity
 199         @abstract Member function to grow the size of the collection.
 200         @param newCapacity The new capacity for the dictionary to expand to.
 201         @result Returns the new capacity of the dictionary or the previous capacity upon error.
 202     */
 203     virtual unsigned int ensureCapacity(unsigned int newCapacity);
 204
 205     /*!
 206         @function flushCollection
 207         @abstract A member function which removes and releases all objects within the collection.
 208     */
 209     virtual void flushCollection();
 210
 211     /*!
 212         @function setObject
 213         @abstract A member function which places an object into the dictionary and identified by a unique key.
 214         @param aKey A unique OSSymbol identifying the object placed within the collection.
 215         @param anObject The object to be stored in the dictionary.  It is automatically retained.
 216         @result Returns true if the addition of an object was successful, false otherwise.
 217     */
 218     virtual bool setObject(const OSSymbol *aKey, const OSMetaClassBase *anObject);
 219     /*!
 220         @function setObject
 221         @abstract A member function which places an object into the dictionary and identified by a unique key.
 222         @param aKey A unique OSString identifying the object placed within the collection.
 223         @param anObject The object to be stored in the dictionary.  It is automatically retained.
 224         @result Returns true if the addition of an object was successful, false otherwise.
 225     */
 226     virtual bool setObject(const OSString *aKey, const OSMetaClassBase *anObject);
 227     /*!
 228         @function setObject
 229         @abstract A member function which places an object into the dictionary and identified by a unique key.
 230         @param aKey A unique string identifying the object placed within the collection.
 231         @param anObject The object to be stored in the dictionary.  It is automatically retained.
 232         @result Returns true if the addition of an object was successful, false otherwise.
 233     */
 234     virtual bool setObject(const char *aKey, const OSMetaClassBase *anObject);
 235
 236     /*!
 237         @function removeObject
 238         @abstract A member function which removes an object from the dictionary.  The removed object is automatically released.
 239         @param aKey A unique OSSymbol identifying the object to be removed from the dictionary.
 240     */
 241     virtual void removeObject(const OSSymbol *aKey);
 242     /*!
 243         @function removeObject
 244         @abstract A member function which removes an object from the dictionary.  The removed object is automatically released.
 245         @param aKey A unique OSString identifying the object to be removed from the dictionary.
 246     */
 247     virtual void removeObject(const OSString *aKey);
 248     /*!
 249         @function removeObject
 250         @abstract A member function which removes an object from the dictionary.  The removed object is automatically released.
 251         @param aKey A unique string identifying the object to be removed from the dictionary.
 252     */
 253     virtual void removeObject(const char *aKey);
 254
 255     /*!
 256         @function merge
 257         @abstract A member function which merges the contents of a dictionary into the receiver.
 258         @param aDictionary The dictionary whose contents are to be merged with the receiver.
 259         @result Returns true if the merger is successful, false otherwise.
 260         @discussion If there are keys in 'aDictionary' which match keys in the receiving dictionary, then the objects in the receiver are replaced by those from 'aDictionary', the replaced objects are released.
 261     */
 262     virtual bool merge(const OSDictionary *aDictionary);
 263
 264     /*!
 265         @function getObject
 266         @abstract A member function to find an object in the dictionary associated by a given key.
 267         @param aKey The unique OSSymbol key identifying the object to be returned to caller.
 268         @result Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.
 269     */
 270     virtual OSObject *getObject(const OSSymbol *aKey) const;
 271     /*!
 272         @function getObject
 273         @abstract A member function to find an object in the dictionary associated by a given key.
 274         @param aKey The unique OSString key identifying the object to be returned to caller.
 275         @result Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.
 276     */
 277     virtual OSObject *getObject(const OSString *aKey) const;
 278     /*!
 279         @function getObject
 280         @abstract A member function to find an object in the dictionary associated by a given key.
 281         @param aKey The unique string identifying the object to be returned to caller.
 282         @result Returns a reference to the object corresponding to the given key, or 0 if the key does not exist in the dictionary.
 283     */
 284     virtual OSObject *getObject(const char *aKey) const;
 285
 286     /*!
 287         @function isEqualTo
 288         @abstract A member function to test the equality of the intersections of two dictionaries.
 289         @param aDictionary The dictionary to be compared against the receiver.
 290         @param keys An OSArray or OSDictionary containing the keys describing the intersection for the comparison.
 291         @result Returns true if the intersections of the two dictionaries are equal.
 292     */
 293     virtual bool isEqualTo(const OSDictionary *aDictionary, const OSCollection *keys) const;
 294     /*!
 295         @function isEqualTo
 296         @abstract A member function to test the equality of two dictionaries.
 297         @param aDictionary The dictionary to be compared against the receiver.
 298         @result Returns true if the dictionaries are equal.
 299     */
 300     virtual bool isEqualTo(const OSDictionary *aDictionary) const;
 301     /*!
 302         @function isEqualTo
 303         @abstract A member function to test the equality between the receiver and an unknown object.
 304         @param anObject An object to be compared against the receiver.
 305         @result Returns true if the objects are equal.
 306     */
 307     virtual bool isEqualTo(const OSMetaClassBase *anObject) const;
 308
 309     /*!
 310         @function serialize
 311         @abstract A member function which archives the receiver.
 312         @param s The OSSerialize object.
 313         @result Returns true if serialization was successful, false if not.
 314     */
 315     virtual bool serialize(OSSerialize *s) const;
 316
 317     /*!
 318         @function setOptions
 319         @abstract This function is used to recursively set option bits in this dictionary and all child collections.
 320         @param options Set the (options & mask) bits.
 321         @param mask The mask of bits which need to be set, 0 to get the current value.
 322         @result The options before the set operation, NB setOptions(?,0) returns the current value of this collection.
 323      */
 324     virtual unsigned setOptions(unsigned options, unsigned mask, void * = 0);
 325
 326     /*!
 327         @function copyCollection
 328         @abstract Do a deep copy of this dictionary and its collections.
 329         @discussion This function copies this dictionary and all included collections recursively.  Objects that don't derive from OSContainter are NOT copied, that is objects like OSString and OSData.
 330         @param cycleDict Is a dictionary of all of the collections that have been, to start the copy at the top level just leave this field 0.
 331         @result The newly copied collecton or 0 if insufficient memory
 332     */
 333     OSCollection *copyCollection(OSDictionary *cycleDict = 0);
 334
 335
 336     OSMetaClassDeclareReservedUnused(OSDictionary, 0);
 337     OSMetaClassDeclareReservedUnused(OSDictionary, 1);
 338     OSMetaClassDeclareReservedUnused(OSDictionary, 2);
 339     OSMetaClassDeclareReservedUnused(OSDictionary, 3);
 340     OSMetaClassDeclareReservedUnused(OSDictionary, 4);
 341     OSMetaClassDeclareReservedUnused(OSDictionary, 5);
 342     OSMetaClassDeclareReservedUnused(OSDictionary, 6);
 343     OSMetaClassDeclareReservedUnused(OSDictionary, 7);
 344 };
 345
 346 #endif /* !_IOKIT_IODICTIONARY_H */