ADC Home > Reference Library > Reference > Darwin > Kernel Framework Reference

IORegistryIterator

Inherits from:	OSIterator
Declared In:	IORegistryEntry.h

Overview

An iterator over the registry.

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.

Functions

enterEntry(): Recurse into the current entry in the registry iteration.
enterEntry(const IORegistryPlane *): Recurse into the current entry in the registry iteration.
exitEntry: Exits a level of recursion, restoring the current entry.
getCurrentEntry: Return the current entry in the registry iteration.
getNextObject: Return the next object in the registry iteration.
getNextObjectFlat: Return the next object in the registry iteration, ignoring the kIORegistryIterateRecursively option.
getNextObjectRecursive: Return the next object in the registry iteration, and enter it.
isValid: Checks that no registry changes have invalidated the iteration.
iterateAll: Iterates all entries (with getNextObject) and returns a set of all returned entries.
iterateOver(const IORegistryPlane *, IOOptionBits): Create an iterator rooted at the registry root.
iterateOver(IORegistryEntry *, const IORegistryPlane *, IOOptionBits): Create an iterator rooted at a given registry entry.
reset: Exits all levels of recursion, restoring the iterator to its state at creation.

enterEntry()

Recurse into the current entry in the registry iteration.

public

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.

enterEntry(const IORegistryPlane *)

Recurse into the current entry in the registry iteration.

public

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.

exitEntry

Exits a level of recursion, restoring the current entry.

public

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.

getCurrentEntry

Return the current entry in the registry iteration.

public

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.

getNextObject

Return the next object in the registry iteration.

public

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.

getNextObjectFlat

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

public

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.

getNextObjectRecursive

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

public

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.

isValid

Checks that no registry changes have invalidated the iteration.

public

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.

iterateAll

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

public

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

iterateOver(const IORegistryPlane *, IOOptionBits)

Create an iterator rooted at the registry root.

public

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.

iterateOver(IORegistryEntry , const IORegistryPlane , IOOptionBits)

Create an iterator rooted at a given registry entry.

public

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.

reset

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

public

virtual void reset(
    void );

Discussion

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

Did this document help you?

Yes: Tell us what works for you.

It’s good, but: Report typos, inaccuracies, and so forth.

It wasn’t helpful: Tell us what would have helped.

Last Updated: 2008-12-19