PATH ADC Home > Documentation > Hardware > Device Managers and Drivers > PCI Card Services > Designing PCI Cards and Drivers for Power Macintosh Computers

Using Iterate Routines

Writing code to interate through a set of names consists of a call to begin the iteration, the iteration loop, and a call to end the iteration. The call to end the iteration should be made even in the case of an error, so that allocated data structures can be freed. Here is the basic code structure for traversing names in the Name Registry:



 
Create(...)

Set(...)                    // optional

do {

        Iterate(...);       // or Search(...);

} while (!done);

Dispose(...);

Two different name entry iterations are provided, direction oriented and search oriented. The type of iteration is indicated by the call used to retrieve the next name entry. All the Mac OS routines used are described in Name Iteration and Searching. Rules for direction iteration are given below; rules for search iteration are given in the next section.

RegistryEntryIterate is used to traverse and explore the Name Registry. An iteration operation begins at a starting entry and moves in a direction defined by the relationship parameter. The relationship determines which entries relative to the starting entry are to be included in the search--children, parents, siblings, or descendants. Each iterate call returns the next entry encountered along the designated path. You can change the direction at any time by specifying a new relationship parameter in your next iterate call. You can continue in the current direction by specifying kRegIterContinue for the relationship parameter. Remember that the direction is relative to the last entry returned from the previous iterate call.
When an entry iterator is created via RegistryEntryIterateCreate, it is initialized to the default starting entry root and with a relationship of kRegIterDescendants. This lets you iterate over the entire Name Registry.
You can use RegistryEntryIterateSet to set the iterator to some name entry other than the root, limiting the iteration to some subset of the Name Registry. To change the default relationship, specify a new relationship as a parameter to your first iterate call.
An iteration sequence is complete when either it finds what it is looking for or the done parameter returns true, indicating that there are no more entries in the specified direction. When done is true no error code is returned and the contents of foundEntry are indeterminate. The iterator must be reset, using RegistryEntryIterateSet, before it can be used again for a subsequent search or iterate operation.
Each iterate call should describe the next relationship of interest.
Don't mix iterators for iterate and search routines without reinitializing the iterator value by means of RegistryEntryIterateSet.

Here are some hints for using relationships while iterating:

To iterate through all the descendants of an entry, specify kRegIterDescendants on the first iterate call and then specify kRegIterContinue until done is true.
To iterate through the children of an entry, specify kRegIterChildren on the first iterate call and then specify kRegIterContinue until done is true.
To iterate through the siblings of an entry, specify kRegIterSiblings on the first iterate call and then specify kRegIterContinue until done is true. Siblings do not include the current entry.
To iterate through the parents of an entry, specify kRegIterParents on the first iterate call and then specify kRegIterContinue until done is true. Note that there is only one parent in the current implementation of the Name Registry.
To navigate down the registry hierarchy, specify kRegIterChildren until you find the level you are looking for or until done is true (which indicates that you have reached the bottom). The latter case is useful when deleting a subtree, because you must delete the children before you can delete a parent.
To navigate up the Name Registry hierarchy, specify kRegIterParents until you find the level you are looking for or until done is true (which indicates that you have reached the root).