PEXGetAncestors - Get Ancestors (5.0)

Synopsis

 
   PEXStructurePath *PEXGetAncestors(
         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 ancestors of the specified structure; a null pointer if unsuccessful.

Description

Invoke PEXGetAncestors to get a list of structure network paths which reference the specified structure.

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 root structures and work down to a final entry with a structure identifier equal to structure and an offset of zero. Only unique paths are returned; in other words there are no duplicates in the list of 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.

If you specify a path depth of 0, then this function returns all unique paths from the root structures of the network to structure. If you specify a path depth of 1 and a path part of PEXTopPart, then this function returns the root structures of all structure networks which contain structure. Specifying a path depth of 2 and path part of PEXBottomPart returns all of the structure's immediate ancestors. Determine the number of references to structure by setting the path depth to 1 and the path part to PEXBottomPart.

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

Errors