横断パッケージには4つのインタフェースのAPIが含まれます。
この章の内容は次のとおりです。
関連項目:
|
表9-1にDocumentTraversalインタフェースで使用できるメソッドの概要を示します。
DocumentTraversal
インタフェースの2つあるメソッドの1つであり、NodeIterator
オブジェクトの作成に使用されます。このメソッドは、戻されるオブジェクト・タイプを除いてはXmlDomCreateTreeWalker()と同一です。
whatToShow
引数はフラグ・ビットのマスクであり、各ノード・タイプに1つずつ割り当てられます。値XMLDOM_SHOW_ALL
では、すべてのノード・タイプが渡されますが、それ以外の場合はビットが設定されているタイプのみが渡されます。
Entity
参照拡張機能は、entrefExpansion
フラグにより制御されます。TRUE
の場合、実体参照は最終内容と置き換えられます。FALSE
の場合、実体参照はノードとして残されます。
構文
xmliter* XmlDomCreateNodeIter( xmlctx *xctx, xmliter *iter, xmlnode *root, xmlshowbits whatToShow, XMLDOM_ACCEPT_NODE_F( (*nodeFilter), xctx, node), boolean entrefExpand);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
iter |
IN |
設定する場合は既存のNodeIterator、作成する場合はNULL |
xerr |
IN |
NodeIteratorのルート・ノード |
whatToShow |
IN |
XMLDOM_SHOW_ XXX フラグ・ビットのマスク |
nodeFilter |
IN |
使用されるノード・フィルタ、ノード・フィルタがない場合はNULL |
xerr |
IN |
実体参照ノードを拡張するかどうかを指定 |
戻り値
(xmliter *)
元の、または新規のNodeIterator
オブジェクト。
DocumentTraversalインタフェースの2つのメソッドのうち1つで、TreeWalker
オブジェクトの作成に使用されます。このメソッドは、戻されるオブジェクト・タイプを除いてはXmlDomCreateNodeIter()と同一です。
whatToShow
引数はフラグ・ビットのマスクであり、各ノード・タイプに1つずつ割り当てられます。値XMLDOM_SHOW_ALL
では、すべてのノード・タイプが渡されますが、それ以外の場合はビットが設定されているタイプのみが渡されます。
Entity
参照拡張機能は、entrefExpansion
フラグにより制御されます。TRUE
の場合、実体参照は最終内容と置き換えられます。FALSE
の場合、実体参照はノードとして残されます。
構文
xmlwalk* XmlDomCreateTreeWalker( xmlctx *xctx, xmlwalk* walker, xmlnode *root, xmlshowbits whatToShow, XMLDOM_ACCEPT_NODE_F( (*nodeFilter), xctx, node), boolean entrefExpansion);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
設定する場合は既存のTreeWalker 、作成する場合はNULL |
xerr |
IN |
TreeWalker のルート・ノード |
whatToShow |
IN |
XMLDOM_SHOW_ XXX フラグ・ビットのマスク |
nodeFilter |
IN |
使用されるノード・フィルタ、ノード・フィルタがない場合はNULL |
xerr |
IN |
実体参照ノードを拡張するかどうかを指定 |
戻り値
(xmlwalk *)
新規TreeWalker
オブジェクト。
表9-2にNodeFilterインタフェースで使用できるメソッドの概要を示します。
NodeFilter
インタフェースの唯一のメソッド。ノードとフィルタが指定された場合、実行するフィルタリング・アクションを決定します。
この関数ポインタは、必要に応じてノード・イテレータ/ツリー・ウォーカ・メソッドに渡されます。
xmlerrの値は次のとおりです。
XMLERR_OK
: ノードを受け取ります。NodeIterator
またはTreeWalker
に定義されたナビゲーション・メソッドはこのノードを戻します。
XMLERR_FILTER_REJECT
: ノードを拒否します。NodeIterator
またはTreeWalker
に定義されたナビゲーション・メソッドはこのノードを戻しません。TreeWalker
の場合、このノードの子も拒否されます。NodeIterator
はこれをXMLDOM_FILTER_SKIP
のシノニムとして処理します。
XMLERR_FILTER_SKIP
: この単一ノードをスキップします。NodeIterator
またはTreeWalker
に定義されたナビゲーション・メソッドはこのノードを戻しません。NodeIterator
とTreeWalker
のいずれの場合も、このノードの子は依然として考慮されます。
構文
#define XMLDOM_ACCEPT_NODE_F(func, xctx, node) xmlerr func( xmlctx *xctx, xmlnode *node);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
node |
IN |
テストするノード |
戻り値
(xmlerr)
フィルタリング結果。
表9-3にNodeIterator
インタフェースで使用できるメソッドの概要を示します。
反復しているセットからNodeIterator
を分離して、すべてのリソースを解放し、イテレータをINVALID
状態に移行させます。この分離関数が呼び出された後、XmlDomIterNextNode
またはXmlDomIterPrevNode
をコールすると例外XMLERR_ITER_DETACHED
が発生します。
構文
xmlerr XmlDomIterDetach( xmlctx *xctx, xmliter *iter);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
iter |
IN |
ノード・イテレータ・オブジェクト |
セットの次のノードを戻し、セットのイテレータの位置を進めます。ノード・イテレータが作成された後、最初にXmlDomIterNextNode
をコールするとセットの最初のノードが戻されます。参照ノード(現在のイテレータの位置)は削除されないものと想定されます。それ以外の場合、基本のDOMツリーに変更を加えてもイテレータは無効になりません。
構文
xmlnode* XmlDomIterNextNode( xmlctx *xctx, xmliter *iter, xmlerr *xerr);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
iter |
IN |
ノード・イテレータ・オブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
反復しているセットの次のノード(またはNULL
)。
セットの前のノードを戻し、セットのイテレータの位置を後方に移動します。
構文
xmlnode* XmlDomIterPrevNode( xmlctx *xctx, xmliter *iter, xmlerr *xerr);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
iter |
IN |
ノード・イテレータ・オブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
反復しているセットの前のノード(またはNULL
)。
表9-4にTreeWalker
インタフェースで使用できるメソッドの概要を示します。
表9-4 TreeWalkerメソッドの概要: 横断パッケージ
関数 | 概要 |
---|---|
|
現在のノードで最初に参照できる子を戻します。 |
|
現在のノードを戻します。 |
|
ルート・ノードを戻します。 |
|
現在のノードで最後に参照される子を戻します。 |
|
次に参照できるノードを戻します。 |
|
直後の兄弟関係ノードを戻します。 |
|
親ノードを戻します。 |
|
前のノードを戻します。 |
|
直前の兄弟関係ノードを戻します。 |
|
現在のノードを設定します。 |
|
ルート・ノードを設定します。 |
現在のノードで最初に参照できる子にTreeWalker
を移動し、新しいノードを戻します。現在のノードに参照可能な子が存在しない場合、NULL
を戻し、現在のノードを保持します。
構文
xmlnode* XmlDomWalkerFirstChild( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalker オブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
最初に参照できる子(またはNULL
)。
現在のノードを戻します(取得します)。エラーの場合はNULL
を戻します。
構文
xmlnode* XmlDomWalkerGetCurrentNode( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalker オブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
現在のノード。
ルート・ノードを戻します(取得します)。エラーの場合はNULL
を戻します。現在のノードは、ノードが属するサブツリーと一緒にルート・ノード下から削除できるため、ウォーカ内の現在のルート・ノードでは現在のノードとの関連性が失われる場合があります。TreeWalker
の反復は現在のノードに基づきます。ただしルート・ノードは反復の空間を定義します。この関数は、ルート・ノード(祖先)が現在のノードとまだ関連性があるかどうかをチェックします。関連性がある場合、このルート・ノードを戻します。それ以外の場合、現在のルートが属するツリーのルートを検出し、このルートをウォーカのルート・ノードとして設定し、戻します。ウォーカがNULL
ポインタの場合、NULL
を戻します。
構文
xmlnode* XmlDomWalkerGetRoot( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalkerオブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
ルート・ノード。
現在のノードで最後に参照される子にTreeWalker
を移動し、新しいノードを戻します。現在のノードに参照可能な子が存在しない場合、NULL
を戻し、現在のノードを保持します。
構文
xmlnode* XmlDomWalkerLastChild( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalkerオブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
最後に参照できる子(またはNULL
)。
TreeWalker
を、ドキュメント内の順序において現在のノードの次に参照可能なノードに移動し、新しいノードを戻します。現在のノードに次のノードが存在しない場合、または次のノードの検索で、TreeWalker
のルート・ノードより上の検索が試行された場合は、NULL
を戻し、現在のノードを保持します。
構文
xmlnode* XmlDomWalkerNextNode( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalkerオブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
次のノード(またはNULL
)。
現在のノードの直後の兄弟関係にTreeWalker
を移動し、新しいノードを戻します。現在のノードに参照可能な直後の兄弟関係が存在しない場合、NULL
を戻し、現在のノードを保持します。
構文
xmlnode* XmlDomWalkerNextSibling( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalker オブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
直後の兄弟関係(またはNULL
)。
現在のノードで参照可能な最も近い祖先ノードに移動し、その祖先モードを戻します。親ノードの検索でTreeWalker
のルート・ノードよりも上の検索が試行された場合、または参照可能な祖先モードが見つからなかった場合、このメソッドは現在の位置を保持し、NULLを戻します。
構文
xmlnode* XmlDomWalkerParentNode( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalkerオブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
親ノード(またはNULL
)。
TreeWalker
を、ドキュメント内の順序において現在のノードの前の、参照可能なノードに移動し、新しいノードを戻します。現在のノードに前のノードが存在しない場合、または前のノード検索で、TreeWalker
のルート・ノードより上の検索が試行された場合、NULL
を戻し、現在のノードを保持します。
構文
xmlnode* XmlDomWalkerPrevNode( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalker オブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
前のノード(またはNULL
)。
現在のノードの直前の兄弟関係にTreeWalker
を移動し、新しいノードを戻します。現在のノードに参照可能な直前の兄弟関係が存在しない場合、NULL
を戻し、現在のノードを保持します。
構文
xmlnode* XmlDomWalkerPrevSibling( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalker オブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
直前の兄弟関係(またはNULL
)。
新しい現在のノードを設定し、このノードを戻します。またルート・ノードが新しい現在のノードの祖先かどうかをチェックします。祖先ではない場合、現在のノードを設定せず、NULL
を戻して、retvalをXMLDOM_WALKER_BAD_NEW_CUR
に設定します。エラーの場合はNULL
を戻します。
構文
xmlnode* XmlDomWalkerSetCurrentNode( xmlctx *xctx, xmlwalk *walker, xmlnode *node, xmlerr *xerr);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalker オブジェクト |
node |
IN |
新しい現在のノード |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
新しい現在のノード。
ルート・ノードを設定します。新しいルート・ノードが現在のノードの祖先である場合は、このノードを戻します。祖先でない場合はエラーを送り、現在のルート・ノードが現在のノードの祖先かどうかをチェックします。祖先の場合、現在のノードを戻します。それ以外の場合、現在のノードが所属するツリーのルートにルート・ノードを設定し、そのルートを戻します。ウォーカまたはルート・ノード・パラメータがNULL
ポインタの場合、NULL
を戻します。
構文
xmlnode* XmlDomWalkerSetRoot( xmlctx *xctx, xmlwalk *walker, xmlnode *node, xmlerr *xerr);
パラメータ | IN/OUT | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalker オブジェクト |
node |
IN |
新しいルート・ノード |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
新しいルート・ノード。