PEXGetDescendants - Get Descendants (5.0)

Synopsis

 
   PEXStructurePath *PEXGetDescendants(
         Display *display,
         PEXStructure structure,
         int path_part,
         unsigned long path_depth,
         unsigned long *count_return
   )

Arguments

display: A pointer to a display structure returned by a successful XOpenDisplay call.
structure: The resource identifier of the structure.
path_part: The part of the path to return (PEXTopPart or PEXBottomPart).
path_depth: The maximum number of structure network path levels to be returned in each path found.
count_return: Returns the number of unique paths found.

Returns

An array of structure paths defining the descendants of the specified structure; a null pointer if unsuccessful.

Description

Invoke PEXGetDescendants to get a list of structure network paths referenced by the specified structure.

The elements of the returned array are of type PEXStructurePath. Paths are returned as lists of element references, each of which is represented as a structure resource identifier and an offset that gives the element's position in the structure. Full paths start with the given structure and the offset of an element referencing another structure and work down to a final entry with the structure identifier of a leaf node and an offset of zero. Only unique paths are returned; in other words, there are no duplicates in the returned paths.

PEXlib defines the following values for path_part:

PEXTopPart -: requests that the top of the structure paths be returned.
PEXBottomPart -: requests that the bottom of the structure paths be returned.

The path depth specifies the maximum number of element references to be returned in each path. If you set the path depth to 1, then only one element reference is returned for each path. A path depth of 2 returns two elements, and so on. If you set the path depth to 0, then the entire path is returned.

For instance, if you specify a path depth of 0, then this function returns all unique paths from structure to leaf nodes in the structure network tree. If you specify a path depth of 1 and a path part of PEXBottomPart, then this function determines the bottom-most structures of the structure network rooted at structure.

PEXlib allocates memory for the returned descendant information. Invoke PEXFreeStructurePaths to deallocate the memory.

Errors