Mac Developer Library

Developer

IORegistryIterator Class Reference

Options
Deployment Target:

On This Page
Language:

IORegistryIterator

An iterator over the registry.

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.

Inheritance


Not Applicable

Conforms To


Not Applicable

Import Statement


Not Applicable

Objective-C

@import Kernel;

Availability


Available in OS X v10.0 and later.
  • Recurse into the current entry in the registry iteration.

    Declaration

    C++

    virtual void enterEntry( void );

    Discussion

    This method makes the current entry, ie. the last entry returned by getNextObject et al., the root in a new level of recursion.

  • Recurse into the current entry in the registry iteration.

    Declaration

    C++

    virtual void enterEntry( const IORegistryPlane *plane );

    Parameters

    plane

    The new plane to switch into.

    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.

  • Exits a level of recursion, restoring the current entry.

    Declaration

    C++

    virtual bool exitEntry( void );

    Return Value

    true if a level of recursion was undone, false if no recursive levels are left in the iteration.

    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.

  • Return the current entry in the registry iteration.

    Declaration

    C++

    virtual IORegistryEntry * getCurrentEntry( void );

    Return Value

    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.

    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.

  • Return the next object in the registry iteration.

    Declaration

    C++

    virtual IORegistryEntry * getNextObject( void );

    Return Value

    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.

    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.

  • Return the next object in the registry iteration, ignoring the kIORegistryIterateRecursively option.

    Declaration

    C++

    virtual IORegistryEntry * getNextObjectFlat( void );

    Return Value

    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.

    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.

  • Return the next object in the registry iteration, and enter it.

    Declaration

    C++

    virtual IORegistryEntry * getNextObjectRecursive( void );

    Return Value

    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.

    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.

  • Checks that no registry changes have invalidated the iteration.

    Declaration

    C++

    virtual bool isValid( void );

    Return Value

    false if the iterator has been invalidated by changes to the registry, true otherwise.

    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.

  • Iterates all entries (with getNextObject) and returns a set of all returned entries.

    Declaration

    C++

    virtual OSOrderedSet * iterateAll( void );

    Return Value

    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.

    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).

  • Create an iterator rooted at the registry root.

    Declaration

    C++

    static IORegistryIterator * iterateOver( const IORegistryPlane *plane, IOOptionBits options = 0 );

    Parameters

    plane

    A plane object must be specified.

    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.

    Return Value

    A created IORegistryIterator instance, to be released by the caller when it has finished with it.

    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.

  • Create an iterator rooted at a given registry entry.

    Declaration

    C++

    static IORegistryIterator * iterateOver( IORegistryEntry *start, const IORegistryPlane *plane, IOOptionBits options = 0 );

    Parameters

    start

    The root entry to begin the iteration at.

    plane

    A plane object must be specified.

    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.

    Return Value

    A created IORegistryIterator instance, to be released by the caller when it has finished with it.

    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.

  • Exits all levels of recursion, restoring the iterator to its state at creation.

    Declaration

    C++

    virtual void reset( void );

    Discussion

    This method exits all levels of recursion, and restores the iterator to its state at creation.