1. XML C APIリファレンス
  2. XML C用の横断APIパッケージ

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メソッドの概要

関数 概要

XmlDomCreateNodeIter()

ノードのイテレータ・オブジェクトを作成します。

XmlDomCreateTreeWalker()

ツリー・ウォーカ・オブジェクトを作成します。

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、作成する場合はNULL 

xerr
 
IN

NodeIteratorのルート・ノード

 
whatToShow
 
IN

XMLDOM_SHOW_XXXフラグ・ビットのマスク 

nodeFilter
 
IN

使用されるノード・フィルタ、ノード・フィルタがない場合はNULL 

xerr
 
IN

実体参照ノードを拡張するかどうかを指定

戻り値

(xmliter *) 元の、または新規のNodeIteratorオブジェクト。

関連項目:

XmlDomCreateTreeWalker()

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

設定する場合は既存のTreeWalker、作成する場合はNULL 

xerr
 
IN

TreeWalkerのルート・ノード

 
whatToShow
 
IN

XMLDOM_SHOW_XXXフラグ・ビットのマスク 

nodeFilter
 
IN

使用されるノード・フィルタ、ノード・フィルタがない場合はNULL 

xerr
 
IN

実体参照ノードを拡張するかどうかを指定

戻り値

(xmlwalk *) 新規TreeWalkerオブジェクト。

関連項目:

XmlDomCreateNodeIter()

10.2 XML C用の横断APIのNodeFilterインタフェース

次の表にTraversal XML C APIのNodeFilterインタフェースで使用できるメソッドの概要を示します。

表10-2 XML C実装のNodeFilter Traversalメソッドの概要

関数 概要

XMLDOM_ACCEPT_NODE_F()

ノードおよびフィルタに基づいてフィルタリング・アクションを決定します。

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メソッドの概要

関数 概要

XmlDomIterDetach()

ノード・イテレータを分離します(停止します)。

XmlDomIterNextNode()

イテレータの次のノードを戻します。

XmlDomIterPrevNode()

イテレータの前のノードを戻します。

10.3.1 XmlDomIterDetach()

反復しているセットからNodeIteratorを分離して、すべてのリソースを解放し、イテレータをINVALID状態に移行させます。この分離関数が呼び出された後、XmlDomIterNextNodeまたはXmlDomIterPrevNodeをコールすると例外XMLERR_ITER_DETACHEDが発生します。

構文

xmlerr XmlDomIterDetach(
   xmlctx *xctx, 
   xmliter *iter);
パラメータ In/Out 説明 
xctx
 
IN

XMLコンテキスト

 
iter
 
IN

ノード・イテレータ・オブジェクト

関連項目:

XmlDomIterNextNode()、XmlDomIterPrevNode()

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)。

関連項目:

XmlDomIterPrevNode()、XmlDomIterDetach()

10.3.3 XmlDomIterPrevNode()

セットの前のノードを戻し、セットのイテレータの位置を後方に移動します。

構文

xmlnode* XmlDomIterPrevNode(
   xmlctx *xctx, 
   xmliter *iter, 
   xmlerr *xerr);
パラメータ In/Out 説明 
xctx
 
IN

XMLコンテキスト

 
iter
 
IN

ノード・イテレータ・オブジェクト

 
xerr
 
OUT

数値のリターン・エラー・コード

戻り値

(xmlnode *) 反復しているセットの前のノード(またはNULL)。

関連項目:

XmlDomIterNextNode()、XmlDomIterDetach()

10.4 XML C用の横断APIのTreeWalkerインタフェース

表10-4にTraversal XML C APIのTreeWalkerインタフェースで使用できるメソッドの概要を示します。

表10-4 XML C実装のTreeWalker Traversalメソッドの概要

関数 概要

XmlDomWalkerFirstChild()

現在のノードで最初に参照できる子を戻します。

XmlDomWalkerGetCurrentNode()

現在のノードを戻します。

XmlDomWalkerGetRoot()

ルート・ノードを戻します。

XmlDomWalkerLastChild()

現在のノードで最後に参照される子を戻します。

XmlDomWalkerNextNode()

次に参照できるノードを戻します。

XmlDomWalkerNextSibling()

直後の兄弟関係ノードを戻します。

XmlDomWalkerParentNode()

親ノードを戻します。

XmlDomWalkerPrevNode()

前のノードを戻します。

XmlDomWalkerPrevSibling()

直前の兄弟関係ノードを戻します。

XmlDomWalkerSetCurrentNode()

現在のノードを設定します。

XmlDomWalkerSetRoot()

ルート・ノードを設定します。

10.4.1 XmlDomWalkerFirstChild()

TreeWalkerを現在のノードの最初の可視の子に移動し、新規ノードを返します。現在のノードに参照可能な子が存在しない場合、NULLを戻し、現在のノードを保持します。

構文

xmlnode* XmlDomWalkerFirstChild(
   xmlctx *xctx,
   xmlwalk *walker,
   xmlerr *xerr);
パラメータ In/Out 説明 
xctx
 
IN

XMLコンテキスト

 
walker
 
IN

TreeWalkerオブジェクト 

xerr
 
OUT

数値のリターン・エラー・コード

戻り値

(xmlnode *) 最初に参照できる子(またはNULL)。

関連項目:

XmlDomWalkerLastChild()

10.4.2 XmlDomWalkerGetCurrentNode()

現在のノードを戻します(取得します)。エラーの場合はNULLを戻します。

構文

xmlnode* XmlDomWalkerGetCurrentNode(
   xmlctx *xctx, 
   xmlwalk *walker, 
   xmlerr *xerr);
パラメータ In/Out 説明 
xctx
 
IN

XMLコンテキスト

 
walker
 
IN

TreeWalkerオブジェクト 

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)。

関連項目:

XmlDomWalkerPrevNode()、XmlDomWalkerNextSibling()、XmlDomWalkerPrevSibling()

10.4.6 XmlDomWalkerNextSibling()

TreeWalkerを現在のノードの次の兄弟まで移動させ、新規ノードを返します。現在のノードに参照可能な直後の兄弟関係が存在しない場合、NULLを戻し、現在のノードを保持します。

構文

xmlnode* XmlDomWalkerNextSibling(
   xmlctx *xctx, 
   xmlwalk *walker, 
   xmlerr *xerr);
パラメータ In/Out 説明 
xctx
 
IN

XMLコンテキスト

 
walker
 
IN

TreeWalkerオブジェクト 

xerr
 
OUT

数値のリターン・エラー・コード

戻り値

(xmlnode *) 直後の兄弟関係(またはNULL)。

関連項目:

XmlDomWalkerNextNode()、XmlDomWalkerPrevNode()、XmlDomWalkerPrevSibling()

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

TreeWalkerオブジェクト 

xerr
 
OUT

数値のリターン・エラー・コード

戻り値

(xmlnode *) 前のノード(またはNULL)。

関連項目:

XmlDomWalkerNextNode()、XmlDomWalkerNextSibling()、XmlDomWalkerPrevSibling()

10.4.9 XmlDomWalkerPrevSibling()

TreeWalkerを現在のノードの前の兄弟まで移動させ、新規ノードを返します。現在のノードに参照可能な直前の兄弟関係が存在しない場合、NULLを戻し、現在のノードを保持します。

構文

xmlnode* XmlDomWalkerPrevSibling(
   xmlctx *xctx, 
   xmlwalk *walker, 
   xmlerr *xerr);
パラメータ In/Out 説明 
xctx
 
IN

XMLコンテキスト

 
walker
 
IN

TreeWalkerオブジェクト 

xerr
 
OUT

数値のリターン・エラー・コード

戻り値

(xmlnode *) 直前の兄弟関係(またはNULL)。

関連項目:

XmlDomWalkerNextNode()、XmlDomWalkerPrevNode()、XmlDomWalkerNextSibling()

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

TreeWalkerオブジェクト 

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

TreeWalkerオブジェクト 

node
 
IN

新しいルート・ノード

 
xerr
 
OUT

数値のリターン・エラー・コード

戻り値

(xmlnode *) 新しいルート・ノード。