iokit/IOKit/IORegistryEntry.h

   1 /*
   2  * Copyright (c) 1998-2000 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * The contents of this file constitute Original Code as defined in and
   7  * are subject to the Apple Public Source License Version 1.1 (the
   8  * "License").  You may not use this file except in compliance with the
   9  * License.  Please obtain a copy of the License at
  10  * http://www.apple.com/publicsource and read it before using this file.
  11  *
  12  * This Original Code and all software distributed under the License are
  13  * distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16  * FITNESS FOR A PARTICULAR PURPOSE OR NON-INFRINGEMENT.  Please see the
  17  * License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * @APPLE_LICENSE_HEADER_END@
  21  */
  22 /*
  23  * Copyright (c) 1998 Apple Computer, Inc.  All rights reserved.
  24  *
  25  * HISTORY
  26  *
  27  */
  28
  29
  30 #ifndef _IOKIT_IOREGISTRYENTRY_H
  31 #define _IOKIT_IOREGISTRYENTRY_H
  32
  33 #include <IOKit/IOTypes.h>
  34 #include <libkern/c++/OSContainers.h>
  35
  36
  37 extern const OSSymbol * gIONameKey;
  38 extern const OSSymbol * gIOLocationKey;
  39
  40 class IORegistryEntry;
  41 class IORegistryPlane;
  42 class IORegistryIterator;
  43
  44 typedef void (*IORegistryEntryApplierFunction)(IORegistryEntry * entry,
  45                                                void * context);
  46
  47 enum {
  48     kIORegistryIterateRecursively       = 0x00000001,
  49     kIORegistryIterateParents           = 0x00000002
  50 };
  51
  52 /*! @class IORegistryEntry : public OSObject
  53     @abstract The base class for all objects in the registry.
  54     @discussion The IORegistryEntry base class provides functions for describing graphs of connected registry entries, each with a dictionary-based property table. Entries may be connected in different planes, with differing topologies. Access to the registry is protected against multiple threads. Inside the kernel planes are specified with plane objects and are published by the creator - IOService exports the gIOServicePlane plane object for example. Non kernel clients specify planes by their name.
  55 */
  56
  57 class IORegistryEntry : public OSObject
  58 {
  59     friend IORegistryIterator;
  60
  61     OSDeclareDefaultStructors(IORegistryEntry)
  62
  63 protected:
  64 /*! @struct ExpansionData
  65     @discussion This structure will be used to expand the capablilties of this class in the future.
  66     */
  67     struct ExpansionData { };
  68
  69 /*! @var reserved
  70     Reserved for future use.  (Internal use only)  */
  71     ExpansionData * reserved;
  72
  73 private:
  74
  75     OSDictionary *      fRegistryTable;
  76     OSDictionary *      fPropertyTable;
  77
  78 public:
  79     /* methods available in Mac OS X 10.1 or later */
  80
  81 /*! @function copyProperty
  82     @abstract Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy. Available in Mac OS X 10.1 or later.
  83     @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the OSDictionary::getObject semantics. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s).
  84     @param aKey The property's name as a C-string.
  85     @param plane The plane to iterate over, eg. gIOServicePlane.
  86     @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard getProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children.
  87     @result The property value found, or zero. A reference on any found property is returned to caller, which should be released. */
  88
  89     virtual OSObject * copyProperty( const char *           aKey,
  90                                      const IORegistryPlane * plane,
  91                                      IOOptionBits            options =
  92                                         kIORegistryIterateRecursively |
  93                                         kIORegistryIterateParents) const;
  94 /*! @function copyProperty
  95     @abstract Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy. Available in Mac OS X 10.1 or later.
  96     @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the OSDictionary::getObject semantics. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s).
  97     @param aKey The property's name as an OSString.
  98     @param plane The plane to iterate over, eg. gIOServicePlane.
  99     @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard getProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children.
 100     @result The property value found, or zero. A reference on any found property is returned to caller, which should be released. */
 101
 102     virtual OSObject * copyProperty( const OSString *        aKey,
 103                                      const IORegistryPlane * plane,
 104                                      IOOptionBits            options =
 105                                         kIORegistryIterateRecursively |
 106                                         kIORegistryIterateParents) const;
 107
 108 /*! @function copyProperty
 109     @abstract Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy. Available in Mac OS X 10.1 or later.
 110     @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the OSDictionary::getObject semantics. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s).
 111     @param aKey The property's name as an OSSymbol.
 112     @param plane The plane to iterate over, eg. gIOServicePlane.
 113     @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard getProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children.
 114     @result The property value found, or zero. A reference on any found property is returned to caller, which should be released. */
 115
 116     virtual OSObject * copyProperty( const OSSymbol *        aKey,
 117                                      const IORegistryPlane * plane,
 118                                      IOOptionBits            options =
 119                                         kIORegistryIterateRecursively |
 120                                         kIORegistryIterateParents) const;
 121
 122 /*! @function copyParentEntry
 123     @abstract Returns an registry entry's first parent entry in a plane. Available in Mac OS X 10.1 or later.
 124     @discussion This function will return the parent to which a registry entry was first attached. Since the majority of registry entrys have only one provider, this is a useful simplification.
 125     @param plane The plane object.
 126     @result Returns the first parent of the registry entry, or zero if the entry is not attached into the registry in that plane. A reference on the entry is returned to caller, which should be released. */
 127
 128     virtual IORegistryEntry * copyParentEntry( const IORegistryPlane * plane ) const;
 129
 130 /*! @function copyChildEntry
 131     @abstract Returns an registry entry's first child entry in a plane. Available in Mac OS X 10.1 or later.
 132     @discussion This function will return the child which first attached to a registry entry.
 133     @param plane The plane object.
 134     @result Returns the first child of the registry entry, or zero if the entry is not attached into the registry in that plane. A reference on the entry is returned to caller, which should be released. */
 135
 136     virtual IORegistryEntry * copyChildEntry( const IORegistryPlane * plane ) const;
 137
 138 private:
 139
 140     OSMetaClassDeclareReservedUsed(IORegistryEntry, 0);
 141     OSMetaClassDeclareReservedUsed(IORegistryEntry, 1);
 142     OSMetaClassDeclareReservedUsed(IORegistryEntry, 2);
 143     OSMetaClassDeclareReservedUsed(IORegistryEntry, 3);
 144     OSMetaClassDeclareReservedUsed(IORegistryEntry, 4);
 145
 146     OSMetaClassDeclareReservedUnused(IORegistryEntry, 5);
 147     OSMetaClassDeclareReservedUnused(IORegistryEntry, 6);
 148     OSMetaClassDeclareReservedUnused(IORegistryEntry, 7);
 149     OSMetaClassDeclareReservedUnused(IORegistryEntry, 8);
 150     OSMetaClassDeclareReservedUnused(IORegistryEntry, 9);
 151     OSMetaClassDeclareReservedUnused(IORegistryEntry, 10);
 152     OSMetaClassDeclareReservedUnused(IORegistryEntry, 11);
 153     OSMetaClassDeclareReservedUnused(IORegistryEntry, 12);
 154     OSMetaClassDeclareReservedUnused(IORegistryEntry, 13);
 155     OSMetaClassDeclareReservedUnused(IORegistryEntry, 14);
 156     OSMetaClassDeclareReservedUnused(IORegistryEntry, 15);
 157     OSMetaClassDeclareReservedUnused(IORegistryEntry, 16);
 158     OSMetaClassDeclareReservedUnused(IORegistryEntry, 17);
 159     OSMetaClassDeclareReservedUnused(IORegistryEntry, 18);
 160     OSMetaClassDeclareReservedUnused(IORegistryEntry, 19);
 161     OSMetaClassDeclareReservedUnused(IORegistryEntry, 20);
 162     OSMetaClassDeclareReservedUnused(IORegistryEntry, 21);
 163     OSMetaClassDeclareReservedUnused(IORegistryEntry, 22);
 164     OSMetaClassDeclareReservedUnused(IORegistryEntry, 23);
 165     OSMetaClassDeclareReservedUnused(IORegistryEntry, 24);
 166     OSMetaClassDeclareReservedUnused(IORegistryEntry, 25);
 167     OSMetaClassDeclareReservedUnused(IORegistryEntry, 26);
 168     OSMetaClassDeclareReservedUnused(IORegistryEntry, 27);
 169     OSMetaClassDeclareReservedUnused(IORegistryEntry, 28);
 170     OSMetaClassDeclareReservedUnused(IORegistryEntry, 29);
 171     OSMetaClassDeclareReservedUnused(IORegistryEntry, 30);
 172     OSMetaClassDeclareReservedUnused(IORegistryEntry, 31);
 173
 174 public:
 175
 176     /* Registry accessors */
 177
 178 /*! @function getRegistryRoot
 179     @abstract Returns a pointer to the root instance of the registry.
 180     @discussion This method provides an accessor to the root of the registry for the machine. The root may be passed to a registry iterator when iterating a plane, and contains properties that describe the available planes, and diagnostic information for IOKit. Keys for these properties are in IOKitKeys.h.
 181     @result A pointer to the IORegistryEntry root instance. It should not be released by the caller. */
 182
 183     static IORegistryEntry * getRegistryRoot( void );
 184
 185 /*! @function getGenerationCount
 186     @abstract Returns an generation count for all registry changing operations.
 187     @discussion This method provides an accessor to the current generation count (or seed) of the registry which changes when any topology change occurs in the registry - this does not include property table changes. It may be used to invalidate any caching of the results from IORegistryEntry methods.
 188     @result An integer generation count. */
 189
 190     static SInt32            getGenerationCount( void );
 191
 192 /*! @function getPlane
 193     @abstract Looks up the plane object by a C-string name.
 194     @discussion Planes are usually provided as globals by the creator, eg. gIOServicePlane, gIODeviceTreePlane, or gIOAudioPlane, however they may also be looked up by name with this method.
 195     @result A pointer to the plane object, or zero if no such plane exists. The returned plane should not be released. */
 196
 197     static const IORegistryPlane * getPlane( const char * name );
 198
 199     /* Registry Entry allocation & init */
 200
 201 /*! @function init
 202     @abstract Standard init method for all IORegistryEntry subclasses.
 203     @discussion A registry entry must be initialized with this method before it can be used. A property dictionary may passed and will be retained by this method for use as the registry entry's property table, or an empty one will be created.
 204     @param A dictionary that will become the registry entry's property table (retaining it), or zero which will cause an empty property table to be created.
 205     @result true on success, or false on a resource failure. */
 206
 207     virtual bool init( OSDictionary * dictionary = 0 );
 208
 209 /*! @function free
 210     @abstract Standard free method for all IORegistryEntry subclasses.
 211     @discussion This method will release any resources of the entry, in particular its property table. Note that the registry entry must always be detached from the registry before free may be called, and subclasses (namely IOService) will have additional protocols for removing registry entries. free should never need be called directly. */
 212
 213     virtual void free( void );
 214
 215 /*! @function setPropertyTable
 216     @abstract Replace a registry entry's property table.
 217     @discussion This method will release the current property table of a the entry and replace it with another, retaining the new property table.
 218     @param dict The new dictionary to be used as the entry's property table. */
 219
 220     virtual void setPropertyTable( OSDictionary * dict );
 221
 222     /* Synchronized property accessors; wrappers to OSDictionary
 223      * plus property creation helpers */
 224
 225 /*! @function setProperty
 226     @abstract Synchronized method to add a property to a registry entry's property table.
 227     @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table.
 228     @param aKey The properties name as an OSSymbol.
 229     @param anObject The property value.
 230     @result true on success or false on a resource failure. */
 231
 232     virtual bool setProperty(const OSSymbol * aKey, OSObject * anObject);
 233
 234 /*! @function setProperty
 235     @abstract Synchronized method to add a property to a registry entry's property table.
 236     @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table.
 237     @param aKey The property's name as an OSString.
 238     @param anObject The property value.
 239     @result true on success or false on a resource failure. */
 240
 241     virtual bool setProperty(const OSString * aKey, OSObject * anObject);
 242
 243 /*! @function setProperty
 244     @abstract Synchronized method to add a property to a registry entry's property table.
 245     @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table.
 246     @param aKey The property's name as a C-string.
 247     @param anObject The property value.
 248     @result true on success or false on a resource failure. */
 249
 250     virtual bool setProperty(const char * aKey, OSObject * anObject);
 251
 252 /*! @function setProperty
 253     @abstract Synchronized method to construct and add a OSString property to a registry entry's property table.
 254     @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. The property is created as an OSString from the supplied C-string, set in the property table with the given name, and released.
 255     @param aKey The property's name as a C-string.
 256     @param aString The property value as a C-string.
 257     @result true on success or false on a resource failure. */
 258
 259     virtual bool setProperty(const char * aKey, const char * aString);
 260
 261 /*! @function setProperty
 262     @abstract Synchronized method to construct and add an OSBoolean property to a registry entry's property table.
 263     @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. The property is created as an OSBoolean from the supplied value, set in the property table with the given name, and released.
 264     @param aKey The property's name as a C-string.
 265     @param aBoolean The property's boolean value.
 266     @result true on success or false on a resource failure. */
 267
 268     virtual bool setProperty(const char * aKey, bool aBoolean);
 269
 270 /*! @function setProperty
 271     @abstract Synchronized method to construct and add an OSNumber property to a registry entry's property table.
 272     @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. The property is created as an OSNumber from the supplied value and size, set in the property table with the given name, and released.
 273     @param aKey The property's name as a C-string.
 274     @param aValue The property's numeric value.
 275     @param aNumberOfBits The property's size in bits, for OSNumber.
 276     @result true on success or false on a resource failure. */
 277
 278     virtual bool setProperty( const char *       aKey,
 279                               unsigned long long aValue,
 280                               unsigned int       aNumberOfBits);
 281
 282 /*! @function setProperty
 283     @abstract Synchronized method to construct and add an OSData property to a registry entry's property table.
 284     @discussion This method will add or replace a property in a registry entry's property table, using the OSDictionary::setObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table. The property is created as an OSData copied from the supplied date and length, set in the property table with the given name, and released.
 285     @param aKey The property's name as a C-string.
 286     @param bytes The property's value as a pointer. OSData will copy this data.
 287     @param length The property's size in bytes, for OSData.
 288     @result true on success or false on a resource failure. */
 289
 290     virtual bool setProperty( const char *       aKey,
 291                               void *             bytes,
 292                               unsigned int       length);
 293
 294 /*! @function removeProperty
 295     @abstract Synchronized method to remove a property from a registry entry's property table.
 296     @discussion This method will remove a property from a registry entry's property table, using the OSDictionary::removeObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table.
 297     @param aKey The property's name as an OSSymbol. */
 298
 299     virtual void removeProperty( const OSSymbol * aKey);
 300
 301 /*! @function removeProperty
 302     @abstract Synchronized method to remove a property from a registry entry's property table.
 303     @discussion This method will remove a property from a registry entry's property table, using the OSDictionary::removeObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table.
 304     @param aKey The property's name as an OSString. */
 305
 306     virtual void removeProperty( const OSString * aKey);
 307
 308 /*! @function removeProperty
 309     @abstract Synchronized method to remove a property from a registry entry's property table.
 310     @discussion This method will remove a property from a registry entry's property table, using the OSDictionary::removeObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table.
 311     @param aKey The property's name as a C-string. */
 312
 313     virtual void removeProperty( const char * aKey);
 314
 315 /*! @function getProperty
 316     @abstract Synchronized method to obtain a property from a registry entry's property table.
 317     @discussion This method will lookup a property in a registry entry's property table, using the OSDictionary::getObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table.
 318     @param aKey The property's name as an OSSymbol.
 319     @result The property value found, or zero. */
 320
 321     virtual OSObject * getProperty( const OSSymbol * aKey) const;
 322
 323 /*! @function getProperty
 324     @abstract Synchronized method to obtain a property from a registry entry's property table.
 325     @discussion This method will lookup a property in a registry entry's property table, using the OSDictionary::getObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table.
 326     @param aKey The property's name as an OSString.
 327     @result The property value found, or zero. */
 328
 329     virtual OSObject * getProperty( const OSString * aKey) const;
 330
 331 /*! @function getProperty
 332     @abstract Synchronized method to obtain a property from a registry entry's property table.
 333     @discussion This method will lookup a property in a registry entry's property table, using the OSDictionary::getObject semantics. This method is synchronized with other IORegistryEntry accesses to the property table.
 334     @param aKey The property's name as a C-string.
 335     @result The property value found, or zero. */
 336
 337     virtual OSObject * getProperty( const char * aKey) const;
 338
 339 /*! @function getProperty
 340     @abstract Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy.
 341     @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the OSDictionary::getObject semantics. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s).
 342     @param aKey The property's name as an OSSymbol.
 343     @param plane The plane to iterate over, eg. gIOServicePlane.
 344     @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard getProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children.
 345     @result The property value found, or zero. */
 346
 347     virtual OSObject * getProperty( const OSSymbol *        aKey,
 348                                     const IORegistryPlane * plane,
 349                                     IOOptionBits            options =
 350                                         kIORegistryIterateRecursively |
 351                                         kIORegistryIterateParents) const;
 352
 353 /*! @function getProperty
 354     @abstract Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy.
 355     @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the OSDictionary::getObject semantics. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s).
 356     @param aKey The property's name as an OSString.
 357     @param plane The plane to iterate over, eg. gIOServicePlane.
 358     @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard getProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children.
 359     @result The property value found, or zero. */
 360
 361     virtual OSObject * getProperty( const OSString *        aKey,
 362                                     const IORegistryPlane * plane,
 363                                     IOOptionBits            options =
 364                                         kIORegistryIterateRecursively |
 365                                         kIORegistryIterateParents) const;
 366
 367 /*! @function getProperty
 368     @abstract Synchronized method to obtain a property from a registry entry or one of its parents (or children) in the hierarchy.
 369     @discussion This method will search for a property, starting first with this registry entry's property table, then iterating recusively through either the parent registry entries or the child registry entries of this entry. Once the first occurrence is found, it will lookup and return the value of the property, using the OSDictionary::getObject semantics. The iteration keeps track of entries that have been recursed into previously to avoid loops. This method is synchronized with other IORegistryEntry accesses to the property table(s).
 370     @param aKey The property's name as a C-string.
 371     @param plane The plane to iterate over, eg. gIOServicePlane.
 372     @param options kIORegistryIterateRecursively may be set to recurse automatically into the registry hierarchy. Without this option, this method degenerates into the standard getProperty() call. kIORegistryIterateParents may be set to iterate the parents of the entry, in place of the children.
 373     @result The property value found, or zero. */
 374
 375     virtual OSObject * getProperty( const char *            aKey,
 376                                     const IORegistryPlane * plane,
 377                                     IOOptionBits            options =
 378                                         kIORegistryIterateRecursively |
 379                                         kIORegistryIterateParents) const;
 380
 381 /*! @function copyProperty
 382     @abstract Synchronized method to obtain a property from a registry entry's property table.
 383     @discussion This method will lookup a property in a registry entry's property table, using the OSDictionary::getObject semantics, and return a reference to the caller. This method is synchronized with other IORegistryEntry accesses to the property table.
 384     @param aKey The property's name as an OSSymbol.
 385     @result The property value found, or zero. It should be released by the caller. */
 386
 387     virtual OSObject * copyProperty( const OSSymbol * aKey) const;
 388
 389 /*! @function copyProperty
 390     @abstract Synchronized method to obtain a property from a registry entry's property table.
 391     @discussion This method will lookup a property in a registry entry's property table, using the OSDictionary::getObject semantics, and return a reference to the caller. This method is synchronized with other IORegistryEntry accesses to the property table.
 392     @param aKey The property's name as an OSString.
 393     @result The property value found, or zero. It should be released by the caller. */
 394
 395     virtual OSObject * copyProperty( const OSString * aKey) const;
 396
 397 /*! @function copyProperty
 398     @abstract Synchronized method to obtain a property from a registry entry's property table.
 399     @discussion This method will lookup a property in a registry entry's property table, using the OSDictionary::getObject semantics, and return a reference to the caller. This method is synchronized with other IORegistryEntry accesses to the property table.
 400     @param aKey The property's name as a C-string.
 401     @result The property value found, or zero. It should be released by the caller. */
 402
 403     virtual OSObject * copyProperty( const char * aKey) const;
 404
 405 /*! @function dictionaryWithProperties
 406     @abstract Synchronized method to obtain copy a registry entry's property table.
 407     @discussion This method will copy a registry entry's property table, using the OSDictionary::withDictionary semantics. This method is synchronized with other IORegistryEntry accesses to the property table. Since OSDictionary will only copy property values by reference, synchronization is not guaranteed to any collection values.
 408     @result The created dictionary, or zero on a resource value. It should be released by the caller. */
 409
 410     virtual OSDictionary * dictionaryWithProperties( void ) const;
 411
 412 /*! @function serializeProperties
 413     @abstract Synchronized method to serialize a registry entry's property table.
 414     @discussion This method will serialize a registry entry's property table, using the OSDictionary::serialize semantics. This method is synchronized with other IORegistryEntry accesses to the property table. Many non-kernel clients of IOKit read information from the registry via properties, and will invoke this method in a registry entry to create a serialization of all the entry's properties, which is then reconstructed in the client's task as a CFDictionary. This method may be intercepted by subclasses to update their properties or implement a different serialization method, though it is usually better to implement such functionality by creating objects in the property table and implementing their serialize methods, avoiding any need to implement serializeProperties.
 415     @param serialize The OSSerialize instance representing the serialization request.
 416     @result True on success, false otherwise. */
 417
 418     virtual bool serializeProperties( OSSerialize * serialize ) const;
 419
 420     /* Unsynchronized(!) property table access */
 421
 422 /*! @function getPropertyTable
 423     @abstract Unsynchronized accessor to a registry entry's property table.
 424     @discussion This method will return a pointer to the live property table as an OSDictionery. Its use is not recommended in most cases, instead use the synchronized accessors and helper functions of IORegistryEntry to access properties. It can only safely be used by one thread, which usually means it can only be used before a registry entry is entered into the registry.
 425     @result A pointer to the property table as an OSDictionary. The pointer is valid while the registry entry is retained, and should not be released by the caller. */
 426
 427     inline OSDictionary * getPropertyTable( void ) const
 428                         { return(fPropertyTable); }
 429
 430     /* Set properties from user level, to be overridden if supported */
 431
 432 /*! @function setProperties
 433     @abstract Optionally supported external method to set properties in a registry entry.
 434     @discussion This method is not implemented by IORegistryEntry, but is available to kernel and non-kernel clients to set properties in a registry entry. IOUserClient provides connection based, more controlled access to this functionality and may be more appropriate for many uses, since there is no differentiation between clients available to this method.
 435     @param properties Any OSObject subclass, to be interpreted by the implementing method - for example an OSDictionary, OSData etc. may all be appropriate.
 436     @result An IOReturn code to be returned to the caller. */
 437
 438     virtual IOReturn setProperties( OSObject * properties );
 439
 440     /* Topology */
 441
 442 /*! @function getParentIterator
 443     @abstract Returns an iterator over an registry entry's parent entries in a specified plane.
 444     @param plane The plane object.
 445     @result Returns an iterator over the parents of the registry entry, or zero if there is a resource failure. The iterator must be released when the iteration is finished. All objects returned by the iteration are retained while the iterator is valid, though they may no longer be attached during the iteration. */
 446
 447     virtual OSIterator * getParentIterator( const IORegistryPlane * plane )
 448                                                                         const;
 449     virtual void applyToParents( IORegistryEntryApplierFunction applier,
 450                                  void * context,
 451                                  const IORegistryPlane * plane ) const;
 452
 453 /*! @function getParentEntry
 454     @abstract Returns an registry entry's first parent entry in a plane.
 455     @discussion This function will return the parent to which a registry entry was first attached. Since the majority of registry entrys have only one provider, this is a useful simplification.
 456     @param plane The plane object.
 457     @result Returns the first parent of the registry entry, or zero if the entry is not attached into the registry in that plane. The parent is retained while the entry is attached, and should not be released by the caller. */
 458
 459     virtual IORegistryEntry * getParentEntry( const IORegistryPlane * plane ) const;
 460
 461 /*! @function getChildIterator
 462     @abstract Returns an iterator over an registry entry's child entries in a plane.
 463     @discussion This method creates an iterator which will return each of a registry entry's child entries in a specified plane.
 464     @param plane The plane object.
 465     @result Returns an iterator over the children of the entry, or zero if there is a resource failure. The iterator must be released when the iteration is finished. All objects returned by the iteration are retained while the iterator is valid, though they may no longer be attached during the iteration. */
 466
 467     virtual OSIterator * getChildIterator( const IORegistryPlane * plane )
 468                                                                         const;
 469
 470     virtual void applyToChildren( IORegistryEntryApplierFunction applier,
 471                                   void * context,
 472                                   const IORegistryPlane * plane ) const;
 473
 474 /*! @function getChildEntry
 475     @abstract Returns an registry entry's first child entry in a plane.
 476     @discussion This function will return the child which first attached to a registry entry.
 477     @param plane The plane object.
 478     @result Returns the first child of the registry entry, or zero if the entry is not attached into the registry in that plane. The child is retained while the entry is attached, and should not be released by the caller. */
 479
 480     virtual IORegistryEntry * getChildEntry( const IORegistryPlane * plane ) const;
 481
 482 /*! @function isChild
 483     @abstract Determines whether a registry entry is the child of another in a plane.
 484     @discussion This method called in the parent entry determines if the specified entry is a child, in a plane. Additionally, it can check if the child is the only child of the parent entry.
 485     @param child The possible child registry entry.
 486     @param plane The plane object.
 487     @param onlyChild If true, check also if the child is the only child.
 488     @result If the child argument is not a child of the registry entry, false is returned. If onlyChild is true and the child is not the only child of the entry, false is returned, otherwise true is returned. */
 489
 490     virtual bool isChild( IORegistryEntry * child,
 491                                 const IORegistryPlane * plane,
 492                                 bool onlyChild = false ) const;
 493
 494 /*! @function isParent
 495     @abstract Determines whether a registry entry is the parent of another in a plane.
 496     @discussion This method called in the child entry determines if the specified entry is a parent, in a plane. Additionally, it can check if the parent is the only parent of the child entry.
 497     @param parent The possible parent registry entry.
 498     @param plane The plane object.
 499     @param onlyParent If true, check also if the parent is the only parent.
 500     @result If the parent argument is not a parent of the registry entry, false is returned. If onlyParent is true and the parent is not the only parent of the entry, false is returned, otherwise true is returned. */
 501
 502     virtual bool isParent( IORegistryEntry * parent,
 503                                 const IORegistryPlane * plane,
 504                                 bool onlyParent = false ) const;
 505
 506 /*! @function inPlane
 507     @abstract Determines whether a registry entry is attached in a plane.
 508     @discussion This method determines if the entry is attached in a plane to any other entry.
 509     @param plane The plane object.
 510     @result If the entry has a parent in the plane, true is returned, otherwise false is returned. */
 511
 512     virtual bool inPlane( const IORegistryPlane * plane ) const;
 513
 514 /*! @function getDepth
 515     @abstract Counts the maximum number of entries between an entry and the registry root, in a plane.
 516     @discussion This method counts the number of entries between and entry and the registry root, in a plane, for each parent of the entry and returns the maximum value.
 517     @param plane The plane object.
 518     @result The maximum number of entries between the entry and the root. Zero is returned if the entry is not attached in the plane. */
 519
 520     virtual unsigned int getDepth( const IORegistryPlane * plane ) const;
 521
 522     /* Attach / detach */
 523
 524 /*! @function attachToParent
 525     @abstract Attaches a entry to a parent entry in a plane.
 526     @discussion This is the usual method of entering an entry into the registry. It is a no-op and success if the entry is already attached to the parent. Attaching the  entry into the registry retains both the child and parent while they are attached. This method will call attachToChild in the parent entry if it is not being called from attachToChild.
 527     @param parent The registry entry to attach to.
 528     @param plane The plane object.
 529     @result true on success, or false on a resource failure, or if the parent is the same as the child. */
 530
 531     virtual bool attachToParent( IORegistryEntry * parent,
 532                                 const IORegistryPlane * plane );
 533
 534 /*! @function detachFromParent
 535     @abstract Detaches an entry from a parent entry in a plane.
 536     @discussion This is the usual method of removing an entry from the registry. It is a no-op if the entry is not attached to the parent. Detaching the entry will release both the child and parent. This method will call detachFromChild in the parent entry if it is not being called from detachFromChild.
 537     @param parent The registry entry to detach from.
 538     @param plane The plane object. */
 539
 540     virtual void detachFromParent( IORegistryEntry * parent,
 541                                 const IORegistryPlane * plane );
 542
 543 /*! @function attachToChild
 544     @abstract Method called in the parent entry when a child attaches.
 545     @discussion This method is called in the parent entry when a child attaches, to make overrides possible. This method will also call attachToParent in the child entry if it is not being called from attachToParent. It is a no-op and success if the entry is already a child. Attaching the  entry into the registry retains both the child and parent while they are attached.
 546     @param child The registry entry being attached.
 547     @param plane The plane object.
 548     @result true on success, or false on a resource failure, or if the parent is the same as the child. */
 549
 550     virtual bool attachToChild( IORegistryEntry * child,
 551                                 const IORegistryPlane * plane );
 552
 553 /*! @function detachFromChild
 554     @abstract Detaches a child entry from its parent in a plane.
 555     @discussion This method is called in the parent entry when a child detaches, to make overrides possible. It is a no-op if the entry is not a child of the parent. Detaching the entry will release both the child and parent. This method will call detachFromParent in the child entry if it is not being called from detachFromParent.
 556     @param parent The registry entry to detach.
 557     @param plane The plane object. */
 558
 559     virtual void detachFromChild( IORegistryEntry * child,
 560                                 const IORegistryPlane * plane );
 561
 562 /*! @function detachAbove
 563     @abstract Detaches an entry from all its parent entries in a plane.
 564     @discussion This method calls detachFromParent in the entry for each of its parent entries in the plane.
 565     @param plane The plane object. */
 566
 567     virtual void detachAbove( const IORegistryPlane * plane );
 568
 569 /*! @function detachAll
 570     @abstract Detaches an entry and all its children recursively in a plane.
 571     @discussion This method breaks the registry connections for a subtree. detachAbove is called in the entry, and all child entries and their children in the plane.
 572     @param plane The plane object. */
 573
 574     virtual void detachAll( const IORegistryPlane * plane );
 575
 576     /* Name, location and path accessors */
 577
 578 /*! @function getName
 579     @abstract Returns the name assigned to the registry entry as a C-string.
 580     @discussion Entries can be named in a particular plane, or globally. If the entry is named in plane and the plane is specified that name will be returned, otherwise the global name is returned. The global name defaults to the entry's meta class name if it has not been named.
 581     @param plane The plane object, or zero for the global name.
 582     @result A C-string name, valid while the entry is retained. */
 583
 584     virtual const char * getName( const IORegistryPlane * plane = 0 ) const;
 585
 586 /*! @function copyName
 587     @abstract Returns the name assigned to the registry entry as an OSSymbol.
 588     @discussion Entries can be named in a particular plane, or globally. If the entry is named in plane and the plane is specified that name will be returned, otherwise the global name is returned. The global name defaults to the entry's meta class name if it has not been named.
 589     @param plane The plane object, or zero for the global name.
 590     @result A reference to an OSSymbol for the name, which should be released by the caller. */
 591
 592     virtual const OSSymbol * copyName(
 593                                 const IORegistryPlane * plane = 0 ) const;
 594
 595 /*! @function compareNames
 596     @abstract Compares the name of the entry with one or more names, and optionally returns the matching name.
 597     @discussion This method is called during IOService name matching and elsewhere to compare the entry's global name with a list of names, or a single name. A list of names may be passed as any OSCollection of OSStrings, while a single name may be passed an OSString, in the name parameter. compareNames will call the compareName method for each name, for overrides.
 598     @param name The name or names to compare with as any OSCollection (eg. OSArray, OSSet, OSDictionary) of OSStrings, or a single name may be passed an OSString.
 599     @param matched If the caller wants the successfully matched name returned, pass a non-zero pointer for the matched parameter and an OSString will be returned here. It should be released by the caller.
 600     @result True if one of the names compared true with the entry's global name. */
 601
 602     virtual bool compareNames( OSObject * name, OSString ** matched = 0 ) const;
 603
 604 /*! @function compareName
 605     @abstract Compares the name of the entry with one name, and optionally returns the matching name.
 606     @discussion This method is called during IOService name matching and elsewhere from the compareNames method. It should be overridden to provide non-standard name matching.
 607     @param name The name to compare with as an OSString.
 608     @param matched If the caller wants the successfully matched name returned, pass a non-zero pointer for the matched parameter and an OSString will be returned here. It should be released by the caller. Generally, this will be the same as the name parameter, but may not be if wildcards are used.
 609     @result True if the name compared true with the entry's global name. */
 610
 611     virtual bool compareName( OSString * name, OSString ** matched = 0 ) const;
 612
 613 /*! @function setName
 614     @abstract Sets a name for the registry entry, in a particular plane, or globally.
 615     @discussion Entries can be named in a particular plane, or globally. If the plane is specified the name applies only to that plane, otherwise the global name is set. The global name defaults to the entry's meta class name if it has not been named.
 616     @param name An OSSymbol which will be retained.
 617     @param plane The plane object, or zero to set the global name. */
 618
 619     virtual void setName( const OSSymbol * name,
 620                                 const IORegistryPlane * plane = 0 );
 621
 622 /*! @function setName
 623     @abstract Sets a name for the registry entry, in a particular plane, or globally.
 624     @discussion Entries can be named in a particular plane, or globally. If the plane is specified the name applies only to that plane, otherwise the global name is set. The global name defaults to the entry's meta class name if it has not been named.
 625     @param name A const C-string name which will be copied.
 626     @param plane The plane object, or zero to set the global name. */
 627
 628     virtual void setName( const char * name,
 629                                 const IORegistryPlane * plane = 0 );
 630
 631 /*! @function getLocation
 632     @abstract Returns the location string assigned to the registry entry as a C-string.
 633     @discussion Entries can given a location string in a particular plane, or globally. If the entry has had a location set in a plane and the plane is specified that location string will be returned, otherwise the global location string is returned. If no global location string has been set, zero is returned.
 634     @param plane The plane object, or zero for the global name.
 635     @result A C-string location string, valid while the entry is retained, or zero. */
 636
 637     virtual const char * getLocation( const IORegistryPlane * plane = 0 ) const;
 638
 639 /*! @function copyLocation
 640     @abstract Returns the location string assigned to the registry entry as an OSSymbol.
 641     @discussion Entries can given a location string in a particular plane, or globally. If the entry has had a location set in a plane and the plane is specified that location string will be returned, otherwise the global location string is returned. If no global location string has been set, zero is returned.
 642     @param plane The plane object, or zero for the global name.
 643     @result A reference to an OSSymbol for the location if one exists, which should be released by the caller, or zero. */
 644
 645     virtual const OSSymbol * copyLocation(
 646                                 const IORegistryPlane * plane = 0 ) const;
 647
 648 /*! @function setLocation
 649     @abstract Sets a location string for the registry entry, in a particular plane, or globally.
 650     @discussion Entries can be given a location string in a particular plane, or globally. If the plane is specified the location applies only to that plane, otherwise the global location is set. The location string may be used during path lookups of registry entries, to distinguish between sibling entries with the same name. The default IORegistryEntry parsing of location strings expects a list of hex numbers separated by commas, though subclasses of IORegistryEntry might do their own parsing.
 651     @param location A C-string location string which will be copied, or an OSSymbol which will be retained.
 652     @param plane The plane object, or zero to set the global location string. */
 653
 654     virtual void setLocation( const OSSymbol * location,
 655                                 const IORegistryPlane * plane = 0 );
 656     virtual void setLocation( const char * location,
 657                                 const IORegistryPlane * plane = 0 );
 658
 659 /*! @function getPath
 660     @abstract Create a path for a registry entry.
 661     @discussion The path for a registry entry is copied to the caller's buffer. The path describes the entry's attachment in a particular plane, which must be specified. The path begins with the plane name followed by a colon, and then followed by '/' separated path components for each of the entries between the root and the registry entry. Each component is constructed with the getPathComponent method called in each entry. An alias may also exist for the entry, which are described as properties in a registry entry found at /aliases in the plane. If a property value interpreted as a path in a call to IORegistryEntry::fromPath yields the entry, then the property name is used as the entry's path.
 662     @param path A char buffer allocated by the caller.
 663     @param length An in/out parameter - the caller sets the length of the buffer available, and getPath returns the total length of the path copied to the buffer.
 664     @param plane The plane object.
 665     @result getPath will fail if the entry is not attached in the plane, or if the buffer is not large enough to contain the path. */
 666
 667     virtual bool getPath( char * path, int * length,
 668                             const IORegistryPlane * plane) const;
 669
 670 /*! @function getPathComponent
 671     @abstract Create a path component for a registry entry.
 672     @discussion Each component of a path created with getPath is created with getPathComponent. The default implementation concatenates the entry's name in the the plane, with the "at" symbol and the location string of the entry in the plane if it has been set.
 673     @param path A char buffer allocated by the caller.
 674     @param length An in/out parameter - the caller sets the length of the buffer available, and getPathComponent returns the total length of the path component copied to the buffer.
 675     @param plane The plane object.
 676     @result true if the path fits into the supplied buffer or false on a overflow. */
 677
 678     virtual bool getPathComponent( char * path, int * length,
 679                                     const IORegistryPlane * plane ) const;
 680
 681 /*! @function fromPath
 682     @abstract Looks up a registry entry by path.
 683     @discussion This function parses paths to lookup registry entries. The path may begin with the <plane name>: created by getPath, or the plane may be set by the caller. If there are characters remaining unparsed after an entry has been looked up, this may be considered an invalid lookup, or those characters may be passed back to the caller and the lookup successful.
 684     @param path A C-string path.
 685     @param plane The plane to lookup up the path, or zero, in which case the path must begin with the plane name.
 686     @param residualPath If the path may contain residual characters after the last path component, the residual will be copied back to the caller's residualPath buffer. If there are residual characters and no residual buffer is specified, fromPath will fail.
 687     @param residualLength An in/out parameter - the caller sets the length of the residual buffer available, and fromPath returns the total length of the residual path copied to the buffer. If there is no residualBuffer (residualPath = 0) then residualLength may be zero also.
 688     @param fromEntry The lookup will proceed rooted at this entry if non-zero, otherwise it proceeds from the root of the plane.
 689     @result A retained registry entry is returned on success, or zero on failure. The caller should release the entry. */
 690
 691     static IORegistryEntry * fromPath(  const char * path,
 692                                         const IORegistryPlane * plane = 0,
 693                                         char * residualPath = 0,
 694                                         int * residualLength = 0,
 695                                         IORegistryEntry * fromEntry = 0 );
 696
 697 /*! @function fromPath
 698     @abstract Looks up a registry entry by relative path.
 699     @discussion This function looks up a entry below the called entry by a relative path. It is just a convenience that calls IORegistryEntry::fromPath with this as the fromEntry parameter.
 700     @param path See IORegistryEntry::fromPath.
 701     @param plane See IORegistryEntry::fromPath.
 702     @param residualPath See IORegistryEntry::fromPath.
 703     @param residualLength See IORegistryEntry::fromPath.
 704     @result See IORegistryEntry::fromPath. */
 705
 706     virtual IORegistryEntry * childFromPath( const char * path,
 707                                              const IORegistryPlane * plane = 0,
 708                                              char * residualPath = 0,
 709                                              int * residualLength = 0 );
 710
 711 /*! @function dealiasPath
 712     @abstract Strips any aliases from the head of path and returns the full path.
 713     @discussion If the path specified begins with an alias found in the /aliases entry, the value of the alias is returned, and a pointer into the passed in path after the alias is passed back to the caller. If an alias is not found, zero is returned and the path parameter is unchanged.
 714     @param opath An in/out paramter - the caller passes in a pointer to a C-string pointer to a path. If an alias is found, dealiasPath returns a pointer into the path just beyond the end of the alias.
 715     @param plane A plane object must be specified.
 716     @result A C-string pointer to the value of the alias if one is found, or zero if not. */
 717
 718     static const char * dealiasPath( const char ** opath,
 719                                     const IORegistryPlane * plane );
 720
 721     /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 722     /* * * * * * * * * * * * internals * * * * * * * * * * * */
 723     /* * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 724
 725 public:
 726     static IORegistryEntry * initialize( void );
 727     static const IORegistryPlane * makePlane( const char * name );
 728     // don't even think about using this
 729     virtual bool init( IORegistryEntry * from,
 730                                 const IORegistryPlane * inPlane );
 731 private:
 732     inline bool arrayMember( OSArray * set,
 733                             const IORegistryEntry * member,
 734                             unsigned int * index = 0 ) const;
 735
 736     bool makeLink( IORegistryEntry * to,
 737                     unsigned int relation,
 738                     const IORegistryPlane * plane ) const;
 739     void breakLink( IORegistryEntry * to,
 740                     unsigned int relation,
 741                     const IORegistryPlane * plane ) const;
 742
 743     virtual OSArray * getParentSetReference( const IORegistryPlane * plane )
 744                                                                         const;
 745     virtual OSArray * getChildSetReference( const IORegistryPlane * plane )
 746                                                                         const;
 747     virtual IORegistryEntry * getChildFromComponent( const char ** path,
 748                                 const IORegistryPlane * plane );
 749
 750     virtual const OSSymbol * hasAlias(  const IORegistryPlane * plane,
 751                                     char * opath = 0, int * length = 0 ) const;
 752     virtual const char * matchPathLocation( const char * cmp,
 753                                 const IORegistryPlane * plane );
 754
 755 };
 756
 757 /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
 758
 759 /*! @class IORegistryIterator : public OSIterator
 760     @abstract An iterator over the registry.
 761     @discussion An iterator that can traverse the children or parents of a registry entry in a plane, and recurse. Access to the registry is protected against multiple threads, but an IORegistryIterator instance is for use by one thread only. */
 762
 763 class IORegistryIterator : public OSIterator
 764 {
 765     OSDeclareAbstractStructors(IORegistryIterator)
 766
 767 private:
 768     struct IORegCursor {
 769         IORegCursor          *  next;
 770         IORegistryEntry      *  current;
 771         OSIterator           *  iter;
 772     };
 773     IORegCursor                 start;
 774     IORegCursor           *     where;
 775     IORegistryEntry       *     root;
 776     OSOrderedSet          *     done;
 777     const IORegistryPlane *     plane;
 778     IOOptionBits                options;
 779
 780     virtual void free( void );
 781
 782 public:
 783 /*! @function iterateOver
 784     @abstract Create an iterator rooted at a given registry entry.
 785     @discussion This method creates an IORegistryIterator that is set up with options to iterate children or parents of a root entry, and to recurse automatically into entries as they are returned, or only when instructed. The iterator object keeps track of entries that have been recursed into previously to avoid loops.
 786     @param start The root entry to begin the iteration at.
 787     @param plane A plane object must be specified.
 788     @param options kIORegistryIterateRecursively may be set to recurse automatically into each entry as it is returned. This option affects the behaviour of the getNextObject method, which is defined in the OSIterator superclass. Other methods will override this behaviour. kIORegistryIterateParents may be set to iterate the parents of each entry, by default the children are iterated.
 789     @result A created IORegistryIterator instance, to be released by the caller when it has finished with it. */
 790
 791     static IORegistryIterator * iterateOver( IORegistryEntry * start,
 792                                              const IORegistryPlane * plane,
 793                                              IOOptionBits options = 0 );
 794
 795 /*! @function iterateOver
 796     @abstract Create an iterator rooted at the registry root.
 797     @discussion This method creates an IORegistryIterator that is set up with options to iterate children of the registry root entry, and to recurse automatically into entries as they are returned, or only when instructed. The iterator object keeps track of entries that have been recursed into previously to avoid loops.
 798     @param plane A plane object must be specified.
 799     @param options kIORegistryIterateRecursively may be set to recurse automatically into each entry as it is returned. This option affects the behaviour of the getNextObject method, which is defined in the OSIterator superclass. Other methods will override this behaviour. kIORegistryIterateParents may be set to iterate the parents of each entry, by default the children are iterated.
 800     @result A created IORegistryIterator instance, to be released by the caller when it has finished with it. */
 801
 802     static IORegistryIterator * iterateOver( const IORegistryPlane * plane,
 803                                              IOOptionBits options = 0 );
 804
 805 /*! @function getNextObject
 806     @abstract Return the next object in the registry iteration.
 807     @discussion This method calls either getNextObjectFlat or getNextObjectRecursive depending on the options the iterator was created with. This implements the OSIterator defined getNextObject method. The object returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it.
 808     @result The next registry entry in the iteration (the current entry), or zero if the iteration has finished at this level of recursion. The entry returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. */
 809
 810     virtual IORegistryEntry * getNextObject( void );
 811
 812 /*! @function getNextObjectFlat
 813     @abstract Return the next object in the registry iteration, ignoring the kIORegistryIterateRecursively option.
 814     @discussion This method returns the next child, or parent if the kIORegistryIterateParents option was used to create the iterator, of the current root entry. The object returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it.
 815     @result The next registry entry in the iteration (the current entry), or zero if the iteration has finished at this level of recursion, or the iteration is invalid (see isValid). The entry returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. */
 816
 817     virtual IORegistryEntry * getNextObjectFlat( void );
 818
 819 /*! @function getNextObjectRecursive
 820     @abstract Return the next object in the registry iteration, and enter it.
 821     @discussion If the iterator has a current entry, and the iterator has not already entered previously, enterEntry is called to recurse into it, ie. make it the new root, and the next child, or parent if the kIORegistryIterateParents option was used to create the iterator, at this new level of recursion is returned. If there is no current entry at this level of recursion, exitEntry is called and the process repeats, until the iteration returns to the entry the iterator was created with and zero is returned. The object returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it.
 822     @result The next registry entry in the iteration (the current entry), or zero if its finished, or the iteration is invalid (see isValid). The entry returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. */
 823
 824     virtual IORegistryEntry * getNextObjectRecursive( void );
 825
 826 /*! @function getCurrentEntry
 827     @abstract Return the current entry in the registry iteration.
 828     @discussion This method returns the current entry, last returned by getNextObject et al. The object returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. If the iteration is no longer valid (see isValid), the current entry is zero.
 829     @result The current registry entry in the iteration, or zero if the last iteration returned zero, or the iteration is invalid (see isValid). The entry returned is retained while the iterator is pointing at it (its the current entry), or recursing into it. The caller should not release it. */
 830
 831     virtual IORegistryEntry * getCurrentEntry( void );
 832
 833 /*! @function enterEntry
 834     @abstract Recurse into the current entry in the registry iteration.
 835     @discussion This method makes the current entry, ie. the last entry returned by getNextObject et al., the root in a new level of recursion. */
 836
 837     virtual void enterEntry( void );
 838
 839 /*! @function enterEntry
 840     @abstract Recurse into the current entry in the registry iteration.
 841     @discussion This method recurses into an entry as with enterEntry, but also switches from the current plane to a new one set by the caller.
 842     @param plane The new plane to switch into. */
 843
 844     virtual void enterEntry( const IORegistryPlane * plane );
 845
 846 /*! @function exitEntry
 847     @abstract Exits a level of recursion, restoring the current entry.
 848     @discussion This method undoes an enterEntry, restoring the current entry. If there are no more levels of recursion to exit false is returned, otherwise true is returned.
 849     @result true if a level of recursion was undone, false if no recursive levels are left in the iteration. */
 850
 851     virtual bool exitEntry( void );
 852
 853 /*! @function reset
 854     @abstract Exits all levels of recursion, restoring the iterator to its state at creation.
 855     @discussion This method exits all levels of recursion, and restores the iterator to its state at creation. */
 856
 857     virtual void reset( void );
 858
 859 /*! @function isValid
 860     @abstract Checks that no registry changes have invalidated the iteration.
 861     @discussion If a registry iteration is invalidated by changes to the registry, it will be made invalid, the currentEntry will be considered zero, and further calls to getNextObject et al. will return zero. The iterator should be reset to restart the iteration when this happens.
 862     @result false if the iterator has been invalidated by changes to the registry, true otherwise. */
 863
 864     virtual bool isValid( void );
 865
 866 /*! @function iterateAll
 867     @abstract Iterates all entries (with getNextObject) and returns a set of all returned entries.
 868     @discussion This method will reset, then iterate all entries in the iteration (with getNextObject) until successful (ie. the iterator is valid at the end of the iteration).
 869     @result A set of entries returned by the iteration. The caller should release the set when it has finished with it. Zero is returned on a resource failure. */
 870
 871     virtual OSOrderedSet * iterateAll( void );
 872 };
 873
 874 #endif /* _IOKIT_IOREGISTRYENTRY_H */