Functions



enterEntry

Abstract: Recurse into the current entry in the registry iteration.
public:

virtual void enterEntry( const IORegistryPlane * plane );

This method recurses into an entry as with enterEntry, but also switches from the current plane to a new one set by the caller.

Parameters

NameDescription
planeThe new plane to switch into.

enterEntry

Abstract: Recurse into the current entry in the registry iteration.
public:

virtual void enterEntry( void );

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


exitEntry

Abstract: Exits a level of recursion, restoring the current entry.
public:

virtual bool exitEntry( void );

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.

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

getCurrentEntry

Abstract: Return the current entry in the registry iteration.
public:

virtual IORegistryEntry * getCurrentEntry( void );

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.

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.

getNextObject

Abstract: Return the next object in the registry iteration.
public:

virtual IORegistryEntry * getNextObject( void );

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.

Parameters

NameDescription
planeA plane object must be specified.
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.

getNextObjectFlat

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

virtual IORegistryEntry * getNextObjectFlat( void );

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.

Parameters

NameDescription
planeA plane object must be specified.
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.

getNextObjectRecursive

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

virtual IORegistryEntry * getNextObjectRecursive( void );

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.

Parameters

NameDescription
planeA plane object must be specified.
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.

isValid

Abstract: Checks that no registry changes have invalidated the iteration.
public:

virtual bool isValid( void );

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.

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

iterateAll

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

virtual OSOrderedSet * iterateAll( void );

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

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.

iterateOver

Abstract: Create an iterator rooted at a given registry entry.
public:

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

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.

Parameters

NameDescription
startThe root entry to begin the iteration at.
planeA plane object must be specified.
optionskIORegistryIterateRecursively 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.
Result: A created IORegistryIterator instance, to be released by the caller when it has finished with it.

iterateOver

Abstract: Create an iterator rooted at the registry root.
public:

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

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.

Parameters

NameDescription
planeA plane object must be specified.
optionskIORegistryIterateRecursively 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.
Result: A created IORegistryIterator instance, to be released by the caller when it has finished with it.

reset

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

virtual void reset( void );

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


© 2000 Apple Computer, Inc. — (Last Updated 2/23/2000)