10 XML C用の横断APIパッケージ
横断パッケージには、横断のルールと動作を実装するAPIが含まれます。便宜上、APIを4つの一般的なインタフェース・タイプにグループ化しました。
10.1 Traversal XML C APIのDocumentTraversalインタフェース
次の表にTraversal
XML C APIのDocumentTraversal
インタフェースで使用できるメソッドの概要を示します。
表10-1 XML C実装のDocumentTraversal Traversalメソッドの概要
関数 | 概要 |
---|---|
ノードのイテレータ・オブジェクトを作成します。 |
|
ツリー・ウォーカ・オブジェクトを作成します。 |
10.1.1 XmlDomCreateNodeIter()
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、作成する場合は |
xerr |
IN |
NodeIteratorのルート・ノード |
whatToShow |
IN |
|
nodeFilter |
IN |
使用されるノード・フィルタ、ノード・フィルタがない場合は |
xerr |
IN |
実体参照ノードを拡張するかどうかを指定 |
戻り値
(xmliter *)
元の、または新規のNodeIterator
オブジェクト。
関連項目:
10.1.2 XmlDomCreateTreeWalker()
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 |
設定する場合は既存の |
xerr |
IN |
|
whatToShow |
IN |
|
nodeFilter |
IN |
使用されるノード・フィルタ、ノード・フィルタがない場合は |
xerr |
IN |
実体参照ノードを拡張するかどうかを指定 |
戻り値
(xmlwalk *)
新規TreeWalker
オブジェクト。
関連項目:
10.2 XML C用の横断APIのNodeFilterインタフェース
次の表にTraversal
XML C APIのNodeFilter
インタフェースで使用できるメソッドの概要を示します。
表10-2 XML C実装のNodeFilter Traversalメソッドの概要
関数 | 概要 |
---|---|
ノードおよびフィルタに基づいてフィルタリング・アクションを決定します。 |
10.2.1 XMLDOM_ACCEPT_NODE_F()
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)
フィルタリング結果
10.3 XML C用の横断APIのNodeIteratorインタフェース
次の表にTraversal
XML C APIのNodeIterator
インタフェースで使用できるメソッドの概要を示します。
表10-3 XML C実装のNodeIterator Traversalメソッドの概要
関数 | 概要 |
---|---|
ノード・イテレータを分離します(停止します)。 |
|
イテレータの次のノードを戻します。 |
|
イテレータの前のノードを戻します。 |
10.3.1 XmlDomIterDetach()
反復しているセットからNodeIterator
を分離して、すべてのリソースを解放し、イテレータをINVALID
状態に移行させます。この分離関数が呼び出された後、XmlDomIterNextNode
またはXmlDomIterPrevNode
をコールすると例外XMLERR_ITER_DETACHED
が発生します。
構文
xmlerr XmlDomIterDetach( xmlctx *xctx, xmliter *iter);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
iter |
IN |
ノード・イテレータ・オブジェクト |
10.3.2 XmlDomIterNextNode()
セットの次のノードを戻し、セットのイテレータの位置を進めます。ノード・イテレータが作成された後、最初にXmlDomIterNextNode
をコールするとセットの最初のノードが戻されます。参照ノード(現在のイテレータの位置)は削除されないものと想定されます。それ以外の場合、基本のDOMツリーに変更を加えてもイテレータは無効になりません。
構文
xmlnode* XmlDomIterNextNode( xmlctx *xctx, xmliter *iter, xmlerr *xerr);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
iter |
IN |
ノード・イテレータ・オブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
反復しているセットの次のノード(またはNULL
)。
10.4 XML C用の横断APIのTreeWalkerインタフェース
表10-4にTraversal
XML C APIのTreeWalker
インタフェースで使用できるメソッドの概要を示します。
表10-4 XML C実装のTreeWalker Traversalメソッドの概要
関数 | 概要 |
---|---|
現在のノードで最初に参照できる子を戻します。 |
|
現在のノードを戻します。 |
|
ルート・ノードを戻します。 |
|
現在のノードで最後に参照される子を戻します。 |
|
次に参照できるノードを戻します。 |
|
直後の兄弟関係ノードを戻します。 |
|
親ノードを戻します。 |
|
前のノードを戻します。 |
|
直前の兄弟関係ノードを戻します。 |
|
現在のノードを設定します。 |
|
ルート・ノードを設定します。 |
10.4.1 XmlDomWalkerFirstChild()
TreeWalker
を現在のノードの最初の可視の子に移動し、新規ノードを返します。現在のノードに参照可能な子が存在しない場合、NULL
を戻し、現在のノードを保持します。
構文
xmlnode* XmlDomWalkerFirstChild( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
|
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
最初に参照できる子(またはNULL
)。
関連項目:
10.4.2 XmlDomWalkerGetCurrentNode()
現在のノードを戻します(取得します)。エラーの場合はNULL
を戻します。
構文
xmlnode* XmlDomWalkerGetCurrentNode( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
|
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
現在のノード
10.4.3 XmlDomWalkerGetRoot()
ルート・ードを戻します(取得します)。エラーの場合はNULL
を戻します。現在のノードは、ノードが属するサブツリーと一緒にルート・ノード下から削除できるため、ウォーカ内の現在のルート・ノードでは現在のノードとの関連性が失われる場合があります。TreeWalker
の反復は現在のノードに基づきます。ただしルート・ノードは反復の空間を定義します。この関数は、ルート・ノード(祖先)が現在のノードとまだ関連性があるかどうかをチェックします。関連性がある場合、このルート・ノードを戻します。それ以外の場合、現在のルートが属するツリーのルートを検出し、このルートをウォーカのルート・ノードとして設定し、戻します。ウォーカがNULL
ポインタの場合、NULL
を戻します。
構文
xmlnode* XmlDomWalkerGetRoot( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalkerオブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
ルート・ノード
10.4.4 XmlDomWalkerLastChild()
TreeWalker
を現在のノードの最後の可視の子まで移動させ、新規ノードを返します。現在のノードに参照可能な子が存在しない場合、NULL
を戻し、現在のノードを保持します。
構文
xmlnode* XmlDomWalkerLastChild( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalkerオブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
最後に参照できる子(またはNULL
)。
10.4.5 XmlDomWalkerNextNode()
TreeWalker
を現在のノードについてドキュメント順に次の可視ノードまで移動し、新規ノードを返します。現在のノードに次のノードが存在しない場合、または次のノードの検索で、TreeWalker
のルート・ノードより上の検索が試行された場合は、NULL
を戻し、現在のノードを保持します。
構文
xmlnode* XmlDomWalkerNextNode( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalkerオブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
次のノード(またはNULL
)。
10.4.6 XmlDomWalkerNextSibling()
TreeWalker
を現在のノードの次の兄弟まで移動させ、新規ノードを返します。現在のノードに参照可能な直後の兄弟関係が存在しない場合、NULL
を戻し、現在のノードを保持します。
構文
xmlnode* XmlDomWalkerNextSibling( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
|
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
直後の兄弟関係(またはNULL
)。
10.4.7 XmlDomWalkerParentNode()
現在のノードのもっとも近い可視の上位ノードに移動し、そのノードを返します。親ノードの検索でTreeWalker
のルート・ノードよりも上の検索が試行された場合、または参照可能な祖先モードが見つからなかった場合、このメソッドは現在の位置を保持し、NULLを戻します。
構文
xmlnode* XmlDomWalkerParentNode( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
TreeWalkerオブジェクト |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
親ノード(またはNULL
)。
10.4.8 XmlDomWalkerPrevNode()
TreeWalker
を現在のノードについてドキュメント順に前の可視ノードまで移動し、新規ノードを返します。現在のノードに前のノードが存在しない場合、または前のノード検索で、TreeWalker
のルート・ノードより上の検索が試行された場合、NULL
を戻し、現在のノードを保持します。
構文
xmlnode* XmlDomWalkerPrevNode( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
|
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
前のノード(またはNULL
)。
10.4.9 XmlDomWalkerPrevSibling()
TreeWalker
を現在のノードの前の兄弟まで移動させ、新規ノードを返します。現在のノードに参照可能な直前の兄弟関係が存在しない場合、NULL
を戻し、現在のノードを保持します。
構文
xmlnode* XmlDomWalkerPrevSibling( xmlctx *xctx, xmlwalk *walker, xmlerr *xerr);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
|
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
直前の兄弟関係(またはNULL
)。
10.4.10 XmlDomWalkerSetCurrentNode()
新しい現在のノードを設定し、このノードを戻します。またルート・ノードが新しい現在のノードの祖先かどうかをチェックします。祖先ではない場合、現在のノードを設定せず、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 |
|
node |
IN |
新しい現在のノード |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
新しい現在のノード。
10.4.11 XmlDomWalkerSetRoot()
ルート・ノードを設定します。新しいルート・ノードが現在のノードの祖先である場合は、このノードを戻します。祖先でない場合はエラーを送り、現在のルート・ノードが現在のノードの祖先かどうかをチェックします。祖先の場合、現在のノードを戻します。それ以外の場合、現在のノードが所属するツリーのルートにルート・ノードを設定し、そのルートを戻します。ウォーカまたはルート・ノード・パラメータがNULL
ポインタの場合、NULL
を戻します。
構文
xmlnode* XmlDomWalkerSetRoot( xmlctx *xctx, xmlwalk *walker, xmlnode *node, xmlerr *xerr);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
walker |
IN |
|
node |
IN |
新しいルート・ノード |
xerr |
OUT |
数値のリターン・エラー・コード |
戻り値
(xmlnode *)
新しいルート・ノード。