IDLffXMLDOMDocument::CreateNodeIterator

The IDLffXMLDOMDocument::CreateNodeIterator function method is used to create an instance of an IDLffXMLDOMNodeIterator object. This function returns an object reference to that instance.

Please note the following exceptions in node iteration:

Syntax

Result = Obj->[IDLffXMLDOMDocument::]CreateNodeIterator( RootNode
[, FILTER_NAME=string] [, FILTER_USERDATA=variable]
[, WHAT_TO_SHOW=value] )

Arguments

RootNode

An object reference to an object that is a subclass of IDLffXMLDOMNode that refers to a node in the DOM tree. The iterator's current position is set immediately before this node. If this object reference is NULL, the iterator's current position is set immediately before the document node.

Keywords

FILTER_NAME

Set this keyword to a scalar string containing the name of an IDL function that is called each time the iterator is about to visit a node. The purpose of this function is to allow the iterator to ask the IDL application if it should visit a particular node, and hence return it in response to an IDLffXMLDOMNodeIterator::NextNode or IDLffXMLDOMNodeIterator::PreviousNode method call. The code in this function should analyze the incoming node and then return a value that instructs the iterator to accept or reject the node.

If this keyword is not specified, the node iterator visits every node.

Nodes that are accepted are returned by IDLffXMLDOMNodeIterator::NextNode and IDLffXMLDOMNodeIterator::PreviousNode. Nodes that are rejected are not returned by these methods.

The filter function is called by the iterator for the given node after the determinations are made with respect to the WHAT_TO_SHOW setting. Therefore, the filter function is not called for nodes that are rejected by the WHAT_TO_SHOW property.

The filter function specified by FILTER_NAME must have the following parameters:

The function must return one of three scalar integer values:

Value

Function

1

ACCEPT: this node is visited by the node iterator

2

REJECT: this node is not visited by the node iterator

3

SKIP: this node is not visited by the node iterator (same as REJECT)

SKIP and REJECT have the same meanings for a node iterator, but have different meanings for a tree walker. This makes it possible for a single filter function to be used with either a node iterator or tree walker. If the function returns a value that is not supported, the iterator visits the node, as if the return value was 1 (ACCEPT). If the function returns a value that cannot be converted to a scalar, IDL throws an error.

The function should not destroy the node object passed as the first parameter.

FILTER_USERDATA

Set this keyword to an IDL variable containing data to pass to the filter function each time the iterator calls the filter function. The iterator creates a copy of this variable to pass on each call.

Supplying this keyword without FILTER_NAME produces no effect on the iterator.

WHAT_TO_SHOW

Set this keyword to a scalar unsigned integer containing a bitmask, where each bit indicates types of nodes that the iterator visits. If this keyword is not specified, the node iterator visits every node.

Type

Value (Hex)

Value (Decimal)

ALL

‘ffff’xu

65535U

Element

‘0001’xu

1U

Attribute

‘0002’xu

2U

Text

‘0004’xu

4U

CDATA Section

‘0008’xu

8U

Entity Reference

‘0010’xu

16U

Entity

‘0020’xu

32U

Processing Instruction

‘0040’xu

64U

Comment

‘0080’xu

128U

Document

‘0100’xu

256U

Document Type

‘0200’xu

512U

Document Fragment

‘0400’xu

1024U

Notation

‘0800’xu

2048U

The node iterator performs the WHAT_TO_SHOW test for a node before calling any user-provided filter function.

Version History

6.2

Introduced