tpm_iterstart

Allocates a topology iterator.

ade_id

tpm_iterstart(

int source,

int loaded);

Returns an iterator ID (ade_id) or ADE_NULLID.

source	Source flag. Values can be: 1 (iterate through the current and source drawings), or 0 (iterate through the current drawing only). The default is 0.
loaded	Loaded in memory flag. Values can be: 1 (iterate through topologies in memory only), or 0 (iterate through all topologies). The default is 0.

This function allocates an iterator and positions it before the first topology definition. This behavior has implications to remember when you use the function.

• Because tpm_iterstart always generates an iterator ID, even if the drawing has no topologies to iterate through, the function fails only when it is out of memory.
• Because tpm_iterstart positions the iterator before the first topology definition, the function cannot indicate whether any topologies exist in the drawing. The only way to determine whether the drawing has topologies is to call tpm_internext, which fails if no topology exists beyond the current position of the iterator.

You can have more than one iterator running at the same time.

The following sample shows how you can use Topology Iterating functions to find and then describe all the topologies in the current project.

// Iterate through the current drawing only (default)
int nTopoInCurrentAndDwgSet = 0;
// Iterate through all topologies (default)
int nTopoInMemory = 0;
ade_id topoIteratorId = tpm_iterstart(
                            nTopoInCurrentAndDwgSet,
                            nTopoInMemory);
int resultCode = RTERROR;
char* pszTopoName = "";
const int TOPONAMEMAXLEN = 17;
if (ADE_NULLID == topoIteratorId) {
    acutPrintf(
        "\nA topology iterator could not be generated.");
}
else {
    resultCode = tpm_iternext(topoIteratorId);
    if (RTNORM ==  resultCode) {
        acutPrintf(
            "\nThe following named topologies were found in the current project:");
        do {
            resultCode = tpm_itername(
                            topoIteratorId,
                            pszTopoName,
                            TOPONAMEMAXLEN);
            int nTopoType = tpm_itertype(topoIteratorId);
            switch(nTopoType) {
                case 1 :{
                        acutPrintf("\n\n\"%s\" is a node topology.", pszTopoName);
                    }
                    break;
                case 2 :{
                        acutPrintf("\n\n\"%s\" is a network topology.", pszTopoName);
                    }
                    break;
                case 3 :{
                        acutPrintf("\n\n\"%s\" is a polygon topology.", pszTopoName);
                    }
                    break;
                default:{
                        acutPrintf("\nThe topology type can not be determined.");
                    }
               }
           } while (RTNORM == (resultCode = tpm_iternext(topoIteratorId)));
    }
    else {
       acutPrintf("\nNo topologies were detected.");
    }
}