9 C用の横断APIパッケージ

横断パッケージには4つのインタフェースのAPIが含まれます。

この章の内容は次のとおりです。

• DocumentTraversalインタフェース

• NodeFilterインタフェース

• NodeIteratorインタフェース

• TreeWalkerインタフェース

関連項目: 『Oracle XML Developer's Kitプログラマーズ・ガイド』 『Oracle XML DB開発者ガイド』

---

DocumentTraversalインタフェース

表9-1にDocumentTraversalインタフェースで使用できるメソッドの概要を示します。

表9-1 DocumentTraversalメソッドの概要: 横断パッケージ

関数	概要
XmlDomCreateNodeIter()	ノードのイテレータ・オブジェクトを作成します。
XmlDomCreateTreeWalker()	ツリー・ウォーカ・オブジェクトを作成します。

---

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

---

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

---

NodeFilterインタフェース

表9-2にNodeFilterインタフェースで使用できるメソッドの概要を示します。

表9-2 NodeFilterメソッドの概要: 横断パッケージ

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

---

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) フィルタリング結果。

---

NodeIteratorインタフェース

表9-3にNodeIteratorインタフェースで使用できるメソッドの概要を示します。

表9-3 NodeIteratorメソッドの概要: 横断パッケージ

関数	概要
XmlDomIterDetach()	ノード・イテレータを分離します（停止します）。
XmlDomIterNextNode()	イテレータの次のノードを戻します。
XmlDomIterPrevNode()	イテレータの前のノードを戻します。

---

XmlDomIterDetach()

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

構文

xmlerr XmlDomIterDetach(
   xmlctx *xctx,
   xmliter *iter);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
iter	IN	ノード・イテレータ・オブジェクト

関連項目: XmlDomIterNextNode()、XmlDomIterPrevNode()

---

XmlDomIterNextNode()

セットの次のノードを戻し、セットのイテレータの位置を進めます。ノード・イテレータが作成された後、最初にXmlDomIterNextNodeをコールするとセットの最初のノードが戻されます。参照ノード（現在のイテレータの位置）は削除されないものと想定されます。それ以外の場合、基本のDOMツリーに変更を加えてもイテレータは無効になりません。

構文

xmlnode* XmlDomIterNextNode(
   xmlctx *xctx,
   xmliter *iter,
   xmlerr *xerr);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
iter	IN	ノード・イテレータ・オブジェクト
xerr	OUT	数値のリターン・エラー・コード

戻り値

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

関連項目: XmlDomIterPrevNode()、XmlDomIterDetach()

---

XmlDomIterPrevNode()

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

構文

xmlnode* XmlDomIterPrevNode(
   xmlctx *xctx,
   xmliter *iter,
   xmlerr *xerr);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
iter	IN	ノード・イテレータ・オブジェクト
xerr	OUT	数値のリターン・エラー・コード

戻り値

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

関連項目: XmlDomIterNextNode()、XmlDomIterDetach()

---

TreeWalkerインタフェース

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

表9-4 TreeWalkerメソッドの概要: 横断パッケージ

関数	概要
XmlDomWalkerFirstChild()	現在のノードで最初に参照できる子を戻します。
XmlDomWalkerGetCurrentNode()	現在のノードを戻します。
XmlDomWalkerGetRoot()	ルート・ノードを戻します。
XmlDomWalkerLastChild()	現在のノードで最後に参照される子を戻します。
XmlDomWalkerNextNode()	次に参照できるノードを戻します。
XmlDomWalkerNextSibling()	直後の兄弟関係ノードを戻します。
XmlDomWalkerParentNode()	親ノードを戻します。
XmlDomWalkerPrevNode()	前のノードを戻します。
XmlDomWalkerPrevSibling()	直前の兄弟関係ノードを戻します。
XmlDomWalkerSetCurrentNode()	現在のノードを設定します。
XmlDomWalkerSetRoot()	ルート・ノードを設定します。

---

XmlDomWalkerFirstChild()

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

構文

xmlnode* XmlDomWalkerFirstChild(
   xmlctx *xctx,
   xmlwalk *walker,
   xmlerr *xerr);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
walker	IN	TreeWalkerオブジェクト
xerr	OUT	数値のリターン・エラー・コード

戻り値

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

関連項目: XmlDomWalkerLastChild()

---

XmlDomWalkerGetCurrentNode()

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

構文

xmlnode* XmlDomWalkerGetCurrentNode(
   xmlctx *xctx,
   xmlwalk *walker,
   xmlerr *xerr);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
walker	IN	TreeWalkerオブジェクト
xerr	OUT	数値のリターン・エラー・コード

戻り値

(xmlnode *) 現在のノード。

---

XmlDomWalkerGetRoot()

ルート・ノードを戻します（取得します）。エラーの場合はNULLを戻します。現在のノードは、ノードが属するサブツリーと一緒にルート・ノード下から削除できるため、ウォーカ内の現在のルート・ノードでは現在のノードとの関連性が失われる場合があります。TreeWalkerの反復は現在のノードに基づきます。ただしルート・ノードは反復の空間を定義します。この関数は、ルート・ノード（祖先）が現在のノードとまだ関連性があるかどうかをチェックします。関連性がある場合、このルート・ノードを戻します。それ以外の場合、現在のルートが属するツリーのルートを検出し、このルートをウォーカのルート・ノードとして設定し、戻します。ウォーカがNULLポインタの場合、NULLを戻します。

構文

xmlnode* XmlDomWalkerGetRoot(
   xmlctx *xctx,
   xmlwalk *walker,
   xmlerr *xerr);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
walker	IN	TreeWalkerオブジェクト
xerr	OUT	数値のリターン・エラー・コード

戻り値

(xmlnode *) ルート・ノード。

---

XmlDomWalkerLastChild()

現在のノードで最後に参照される子にTreeWalkerを移動し、新しいノードを戻します。現在のノードに参照可能な子が存在しない場合、NULLを戻し、現在のノードを保持します。

構文

xmlnode* XmlDomWalkerLastChild(
   xmlctx *xctx,
   xmlwalk *walker,
    xmlerr *xerr);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
walker	IN	TreeWalkerオブジェクト
xerr	OUT	数値のリターン・エラー・コード

戻り値

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

---

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

---

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

---

XmlDomWalkerParentNode()

現在のノードで参照可能な最も近い祖先ノードに移動し、その祖先モードを戻します。親ノードの検索でTreeWalkerのルート・ノードよりも上の検索が試行された場合、または参照可能な祖先モードが見つからなかった場合、このメソッドは現在の位置を保持し、NULLを戻します。

構文

xmlnode* XmlDomWalkerParentNode(
   xmlctx *xctx,
   xmlwalk *walker,
   xmlerr *xerr);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
walker	IN	TreeWalkerオブジェクト
xerr	OUT	数値のリターン・エラー・コード

戻り値

(xmlnode *) 親ノード（またはNULL）。

---

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

---

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

---

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 *) 新しい現在のノード。

---

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 *) 新しいルート・ノード。