TreeWalker Interface

Table 8-4 summarizes the methods of available through the TreeWalker interface.

Table 8-4 Summary of TreeWalker Methods; Traversal Package

Function	Summary
XmlDomWalkerFirstChild	Return first visible child of current node.
XmlDomWalkerGetCurrentNode	Return current node.
XmlDomWalkerGetRoot	Return root node.
XmlDomWalkerLastChild	Return last visible child of current node.
XmlDomWalkerNextNode	Return next visible node.
XmlDomWalkerNextSibling	Return next sibling node.
XmlDomWalkerParentNode	Return parent node.
XmlDomWalkerPrevNode	Return previous node.
XmlDomWalkerPrevSibling	Return previous sibling node.
XmlDomWalkerSetCurrentNode	Set current node.
XmlDomWalkerSetRoot	Set the root node.

XmlDomWalkerFirstChild

Moves the TreeWalker to the first visible child of the current node, and returns the new node. If the current node has no visible children, returns NULL, and retains the current node.

Syntax

xmlnode* XmlDomWalkerFirstChild(
   xmlctx *xctx,
   xmlwalk *walker,
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
walker	IN	`TreeWalker` object
xerr	OUT	numeric return error code

Returns

(xmlnode *) first visible child [or NULL]

See Also:

XmlDomWalkerLastChild

XmlDomWalkerGetCurrentNode

Return (get) current node, or NULL on error.

Syntax

xmlnode* XmlDomWalkerGetCurrentNode(
   xmlctx *xctx, 
   xmlwalk *walker, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
walker	IN	`TreeWalker` object
xerr	OUT	numeric return error code

Returns

(xmlnode *) current node

XmlDomWalkerGetRoot

Return (get) root node, or NULL on error. Since the current node can be removed from under the root node together with a subtree where it belongs to, the current root node in a walker might have no relation to the current node any more. The TreeWalker iterations are based on the current node. However, the root node defines the space of an iteration. This function checks if the root node is still in the root node (ancestor) relation to the current node. If so, it returns this root node. Otherwise, it finds the root of the tree where the current node belongs to, and sets and returns this root as the root node of the walker. It returns NULL if the walker is a NULL pointer.

Syntax

xmlnode* XmlDomWalkerGetRoot(
   xmlctx *xctx, 
   xmlwalk *walker, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
walker	IN	TreeWalker object
xerr	OUT	numeric return error code

Returns

(xmlnode *) root node

XmlDomWalkerLastChild

Moves the TreeWalker to the last visible child of the current node, and returns the new node. If the current node has no visible children, returns NULL, and retains the current node.

Syntax

xmlnode* XmlDomWalkerLastChild(
   xmlctx *xctx, 
   xmlwalk *walker,
    xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
walker	IN	TreeWalker object
xerr	OUT	numeric return error code

Returns

(xmlnode *) last visible children [or NULL]

XmlDomWalkerNextNode

Moves the TreeWalker to the next visible node in document order relative to the current node, and returns the new node. If the current node has no next node, or if the search for the next node attempts to step upward from the TreeWalker's root node, returns NULL, and retains the current node.

Syntax

xmlnode* XmlDomWalkerNextNode(
   xmlctx *xctx, 
   xmlwalk *walker, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
walker	IN	TreeWalker object
xerr	OUT	numeric return error code

Returns

(xmlnode *) next node [or NULL]

XmlDomWalkerNextSibling

Moves the TreeWalker to the next sibling of the current node, and returns the new node. If the current node has no visible next sibling, returns NULL, and retains the current node.

Syntax

xmlnode* XmlDomWalkerNextSibling(
   xmlctx *xctx, 
   xmlwalk *walker, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
walker	IN	`TreeWalker` object
xerr	OUT	numeric return error code

Returns

(xmlnode *) next sibling [or NULL]

XmlDomWalkerParentNode

Moves to and returns the closest visible ancestor node of the current node. If the search for the parent node attempts to step upward from the TreeWalker's root node, or if it fails to find a visible ancestor node, this method retains the current position and returns null.

Syntax

xmlnode* XmlDomWalkerParentNode(
   xmlctx *xctx, 
   xmlwalk *walker, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
walker	IN	TreeWalker object
xerr	OUT	numeric return error code

Returns

(xmlnode *) parent node [or NULL]

XmlDomWalkerPrevNode

Moves the TreeWalker to the previous visible node in document order relative to the current node, and returns the new node. If the current node has no previous node, or if the search for the previous node attempts to step upward from the TreeWalker's root node, returns NULL, and retains the current node.

Syntax

xmlnode* XmlDomWalkerPrevNode(
   xmlctx *xctx, 
   xmlwalk *walker, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
walker	IN	`TreeWalker` object
xerr	OUT	numeric return error code

Returns

(xmlnode *) previous node [or NULL]

XmlDomWalkerPrevSibling

Moves the TreeWalker to the previous sibling of the current node, and returns the new node. If the current node has no visible previous sibling, returns NULL, and retains the current node.

Syntax

xmlnode* XmlDomWalkerPrevSibling(
   xmlctx *xctx, 
   xmlwalk *walker, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
walker	IN	`TreeWalker` object
xerr	OUT	numeric return error code

Returns

(xmlnode *) previous sibling [or NULL]

XmlDomWalkerSetCurrentNode

Sets and returns new current node. It also checks if the root node is an ancestor of the new current node. If not it does not set the current node, returns NULL, and sets retval to XMLDOM_WALKER_BAD_NEW_CUR. Returns NULL if an error.

Syntax

xmlnode* XmlDomWalkerSetCurrentNode(
   xmlctx *xctx, 
   xmlwalk *walker, 
   xmlnode *node, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
walker	IN	`TreeWalker` object
node	IN	new current node
xerr	OUT	numeric return error code

Returns

(xmlnode *) new current node

XmlDomWalkerSetRoot

Set the root node. Returns new root node if it is an ancestor of the current node. If not it signals an error and checks if the current root node is an ancestor of the current node. If yes it returns it. Otherwise it sets the root node to and returns the root of the tree where the current node belongs to. It returns NULL if the walker or the root node parameter is a NULL pointer.

Syntax

xmlnode* XmlDomWalkerSetRoot(
   xmlctx *xctx, 
   xmlwalk *walker, 
   xmlnode *node, 
   xmlerr *xerr);

Parameter	In/Out	Description
xctx	IN	XML context
walker	IN	`TreeWalker` object
node	IN	new root node
xerr	OUT	numeric return error code

Returns

(xmlnode *) new root node