Skip Headers

Oracle® XML API Reference 10g Release 1 (10.1) Part No. B10789-01 |
| Contents

## 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`]

See Also: XmlDomWalkerPrevNode, XmlDomWalkerNextSibling, XmlDomWalkerPrevSibling

### 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`]

See Also: XmlDomWalkerNextNode, XmlDomWalkerPrevNode, XmlDomWalkerPrevSibling

### 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`]

See Also: XmlDomWalkerNextNode, XmlDomWalkerNextSibling, XmlDomWalkerPrevSibling

### 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`]

See Also: XmlDomWalkerNextNode, XmlDomWalkerPrevNode, XmlDomWalkerNextSibling

### 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