5 C用の範囲APIパッケージ

範囲パッケージには、2つのインタフェースのAPIが含まれます。

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

• DocumentRangeインタフェース

• Rangeインタフェース

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

---

DocumentRangeインタフェース

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

表5-1 DocumentRangeメソッドの概要: 範囲パッケージ

関数	概要
XmlDomCreateRange()	範囲オブジェクトを作成します。

---

XmlDomCreateRange()

範囲オブジェクトの作成に使用される、唯一のDocumentRangeインタフェースのメソッド。

構文

xmlrange* XmlDomCreateRange(
   xmlctx *xctx,
   xmlrange *range,
   xmldocnode *doc);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
range	IN	既存のNodeIterator、または新規NodeIteratorを割り当てる場合はNULL
doc	IN	新規の範囲が追加されるドキュメント

戻り値

(xmlrange *) 元の、または新規の範囲オブジェクト。

---

Rangeインタフェース

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

表5-2 Rangeメソッドの概要: 範囲パッケージ

関数	概要
XmlDomRangeClone()	範囲を複製します。
XmlDomRangeCloneContents()	範囲で選択された内容を複製します。
XmlDomRangeCollapse()	範囲をスタート・ポイントかエンド・ポイントまで縮小します。
XmlDomRangeCompareBoundaryPoints()	2つの範囲の境界点を比べます。
XmlDomRangeDeleteContents()	範囲で選択された内容を削除します。
XmlDomRangeDetach()	範囲を分離します。
XmlDomRangeExtractContents()	範囲で選択された内容を抽出します。
XmlDomRangeGetCollapsed()	範囲が縮小されているかどうかを戻します。
XmlDomRangeGetCommonAncestor()	2つの境界点の最も深い共通の祖先ノードを戻します。
XmlDomRangeGetDetached()	範囲が分離されているかどうかを戻します。
XmlDomRangeGetEndContainer()	範囲終了コンテナ・ノードを戻します。
XmlDomRangeGetEndOffset()	範囲終了オフセットを戻します。
XmlDomRangeGetStartContainer()	範囲開始コンテナ・ノードを戻します。
XmlDomRangeGetStartOffset()	範囲開始オフセットを戻します。
XmlDomRangeIsConsistent()	範囲が一貫しているかどうかを戻します。
XmlDomRangeSelectNode()	ノードを範囲として選択します。
XmlDomRangeSelectNodeContents()	ノード内容を選択するための範囲を定義します。
XmlDomRangeSetEnd()	エンド・ポイントを設定します。
XmlDomRangeSetEndBefore()	ノードの前にエンド・ポイントを設定します。
XmlDomRangeSetStart()	スタート・ポイントを設定します。
XmlDomRangeSetStartAfter()	ノードの後にスタート・ポイントを設定します。
XmlDomRangeSetStartBefore()	ノードの前にスタート・ポイントを設定します。

---

XmlDomRangeClone()

範囲を複製します。元の範囲で選択された内容に影響することなく、範囲を複製します。エラーの場合はNULLを戻します。

構文

xmlrange* XmlDomRangeClone(
   xmlctx *xctx,
   xmlrange *range,
   xmlerr *xerr);

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

戻り値

(xmlrange *) 古い範囲を複製した新しい範囲。

---

XmlDomRangeCloneContents()

範囲で選択された内容を複製します。複製しますが、範囲で選択された内容を削除しません。範囲の一貫性チェックを実行し、エラーがあればretvalをエラー・コードに設定します。

構文

xmlnode* XmlDomRangeCloneContents(
   xmlctx *xctx,
   xmlrange *range,
   xmlerr *xerr);

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

戻り値

(xmlnode *) 複製された内容。

---

XmlDomRangeCollapse()

範囲をスタート・ポイントかエンド・ポイントまで縮小します。縮小のポイントは、この範囲が追加されるドキュメント内の有効なポイントとみなされます。

構文

xmlerr XmlDomRangeCollapse(
   xmlctx *xctx,
   xmlrange *range,
   boolean tostart);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
range	IN	範囲オブジェクト
tostart	IN	スタート・ポイント（TRUE）かエンド・ポイント（FALSE）のどちらまで縮小するか指示

戻り値

(xmlerr) 数値のリターン・コード。

---

XmlDomRangeCompareBoundaryPoints()

2つの異なる範囲の2つの境界点を比較します。範囲（range）の対応する境界点が2番目の範囲（srange）の対応する境界点の前、同じ位置、後のいずれに位置するかにより-1、0、1を戻します。2つの範囲が2つの異なるドキュメントに追加される場合、またはいずれかの範囲が分離されている場合は~(int)0を戻します。

構文

sb4 XmlDomRangeCompareBoundaryPoints(
   xmlctx *xctx,
   xmlrange *range,
   xmlcmphow how,
   xmlrange *srange,
   xmlerr *xerr);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
range	IN	範囲オブジェクト
how	IN	xmlcmphow値。比較方法
srange	IN	比較対象の範囲オブジェクト
xerr	OUT	数値のリターン・コード

戻り値

(sb4) strcmpのような比較結果。

---

XmlDomRangeDeleteContents()

範囲で選択された内容を削除します。範囲の一貫性チェックを実行し、エラーがあればretvalをエラー・コードに設定します。

構文

xmlerr XmlDomRangeDeleteContents(
   xmlctx *xctx,
   xmlrange *range);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
range	IN	範囲オブジェクト

戻り値

(xmlerr) 数値のリターン・コード。

---

XmlDomRangeDetach()

範囲をドキュメントから分離させ、その範囲（range）を無効な状態にします。

構文

xmlerr XmlDomRangeDetach(
   xmlctx *xctx,
   xmlrange *range);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
range	IN	範囲オブジェクト

戻り値

(xmlerr) 数値のリターン・コード。

---

XmlDomRangeExtractContents()

範囲で選択された内容を抽出します。範囲で選択された内容を複製し、削除します。範囲の一貫性チェックを実行し、エラーがあればretvalをエラー・コードに設定します。

構文

xmlnode* XmlDomRangeExtractContents(
   xmlctx *xctx,
   xmlrange *range,
   xmlerr *xerr);

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

戻り値

(xmlnode *) 抽出された内容。

---

XmlDomRangeGetCollapsed()

範囲が縮小され、分離されていない場合はTRUEを、それ以外の場合はFALSEを戻します。

構文

boolean XmlDomRangeGetCollapsed(
   xmlctx *xctx,
   xmlrange *range,
   xmlerr *xerr);

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

戻り値

(boolean) 範囲が縮小されている場合はTRUE、縮小されていない場合はFALSE。

---

XmlDomRangeGetCommonAncestor()

範囲が分離されていない場合、範囲の2つの境界点で最も深い共通の祖先ノードを戻し、それ以外の場合はNULLを戻します。範囲は一貫した状態にあると仮定されます。

構文

xmlnode* XmlDomRangeGetCommonAncestor(
   xmlctx *xctx,
   xmlrange *range,
   xmlerr *xerr);

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

戻り値

(xmlnode *) 最も深い共通の祖先ノード（またはNULL）。

---

XmlDomRangeGetDetached()

範囲が分離されているかどうかを戻します。範囲が分離されていてNULL以外の場合は、TRUEを戻します。それ以外の場合は、FALSEを戻します。

構文

ub1 XmlDomRangeGetDetached(
   xmlctx *xctx,
   xmlrange *range);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
range	IN	範囲オブジェクト

戻り値

(ub1) 範囲が分離されている場合はTRUE、それ以外の場合はFALSE。

---

XmlDomRangeGetEndContainer()

範囲が分離されていない場合は、範囲終了コンテナ・ノードを戻し、それ以外の場合はNULLを戻します。

構文

xmlnode* XmlDomRangeGetEndContainer(
   xmlctx *xctx,
   xmlrange *range,
   xmlerr *xerr);

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

戻り値

(xmlnode *) 範囲終了コンテナ・ノード（またはNULL）。

---

XmlDomRangeGetEndOffset()

範囲が分離されていない場合、範囲終了オフセットを戻し、それ以外の場合は~(ub4)0（最大値ub4）を戻します。

構文

ub4 XmlDomRangeGetEndOffset(
   xmlctx *xctx,
   xmlrange *range,
   xmlerr *xerr);

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

戻り値

(ub4) 範囲終了オフセット（または最大ub4）。

---

XmlDomRangeGetStartContainer()

範囲が有効な状態で分離されていない場合は、範囲開始コンテナ・ノードを戻し、それ以外の場合はNULLを戻します。

構文

xmlnode* XmlDomRangeGetStartContainer(
   xmlctx *xctx,
   xmlrange *range,
   xmlerr *xerr);

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

戻り値

(xmlnode *) 範囲開始コンテナ・ノード。

---

XmlDomRangeGetStartOffset()

範囲が分離されていない場合、範囲開始オフセットを戻し、それ以外の場合は~(ub4)0（最大値ub4）を戻します。

構文

ub4 XmlDomRangeGetStartOffset(
   xmlctx *xctx,
   xmlrange *range,
   xmlerr *xerr);

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

戻り値

(ub4) 範囲開始オフセット（または最大ub4）。

---

XmlDomRangeIsConsistent()

範囲が一貫しているかどうかを戻します。範囲が一貫している場合はTRUEを戻します。両方のポイントは同じルート内にあり、スタート・ポイントはエンド・ポイントの前か同位置にあります。それ以外の場合は、FALSEを戻します。

構文

boolean XmlDomRangeIsConsistent(
   xmlctx *xctx,
   xmlrange *range,
   xmlerr *xerr);

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

戻り値

(ub1) 範囲が一貫している場合はTRUE、それ以外の場合はFALSE。

---

XmlDomRangeSelectNode()

このノードの親がコンテナ・ノードになり、その子の間で、オフセットがこのノードのオフセットと等しくなるように範囲のエンド・ポイントとスタート・ポイントを設定します。範囲は縮小されます。ノードはそのドキュメントの有効なノードであると仮定されます。範囲が分離されている場合、ノードは無視され、範囲が追加されます。

構文

xmlerr XmlDomRangeSelectNode(
   xmlctx *xctx,
   xmlrange *range,
   xmlnode *node);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
range	IN	範囲オブジェクト
node	IN	XMLノード

戻り値

(xmlerr) 数値のリターン・コード。

---

XmlDomRangeSelectNodeContents()

範囲スタート・ポイントをノード内容の先頭に、範囲エンド・ポイントをノード内容の末尾に設定します。ノードは有効なドキュメント・ノードであると仮定されます。範囲が分離されている場合、ノードは無視され、範囲が追加されます。

構文

xmlerr XmlDomRangeSelectNodeContents(
   xmlctx *xctx,
   xmlrange *range,
   xmlnode *node);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
range	IN	範囲オブジェクト
node	IN	XMLノード

戻り値

(xmlerr) 数値のリターン・コード。

---

XmlDomRangeSetEnd()

範囲のエンド・ポイントを設定します。現在のルート・コンテナ以外のルート・コンテナが範囲にある場合、範囲は新しい位置まで縮小されます。エンド・ポイントがスタート・ポイントの前に位置するように設定されている場合、範囲はその位置に縮小されます。このタイプが定義される説明に従って、xmlerr値を戻します。範囲のスタート・ポイントが有効なスタート・ポイントであると仮定します。

構文

xmlerr XmlDomRangeSetEnd(
   xmlctx *xctx,
   xmlrange *range,
   xmlnode *node,
   ub4 offset);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
range	IN	範囲オブジェクト
node	IN	XMLノード
offset	IN	終了オフセット

戻り値

(xmlerr) 数値のリターン・コード。

---

XmlDomRangeSetEndBefore()

範囲のエンド・ポイントをノードの前に設定します。現在のルート・コンテナ以外のルート・コンテナが範囲にある場合、範囲は新しい位置まで縮小されます。前のノードによりエンド・ポイントがスタート・ポイントの前に設定されている場合、範囲は新しい位置まで縮小されます。このタイプが定義される説明に従って、xmlerr値を戻します。範囲のスタート・ポイントが有効なスタート・ポイントであると仮定します。

構文

xmlerr XmlDomRangeSetEndBefore(
   xmlctx *xctx,
   xmlrange *range,
   xmlnode *node);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
range	IN	範囲オブジェクト
node	IN	XMLノード

戻り値

(xmlerr) 数値のリターン・コード。

---

XmlDomRangeSetStart()

範囲のスタート・ポイントを設定します。現在のルート・コンテナ以外のルート・コンテナが範囲にある場合、範囲は新しい位置まで縮小されます。スタート・ポイントがエンド・ポイントの後に位置するように設定されている場合、範囲はその位置まで縮小されます。このタイプが定義される説明に従って、xmlerr値を戻します。範囲のエンド・ポイントが有効なエンド・ポイントであると仮定します。

構文

xmlerr XmlDomRangeSetStart(
   xmlctx *xctx,
   xmlrange *range,
   xmlnode *node,
   ub4 offset);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
range	IN	範囲オブジェクト
node	IN	XMLノード
offset	IN	開始オフセット

戻り値

(xmlerr) 数値のリターン・コード。

---

XmlDomRangeSetStartAfter()

範囲のスタート・ポイントをノードの後に設定します。現在のルート・コンテナ以外のルート・コンテナが範囲にある場合、範囲は新しい位置まで縮小されます。前のノードによりスタート・ポイントがエンド・ポイントの後に設定されている場合、範囲は新しい位置まで縮小されます。範囲のエンド・ポイントが有効なエンド・ポイントであると仮定します。

構文

xmlerr XmlDomRangeSetStartAfter(
   xmlctx *xctx,
   xmlrange *range,
   xmlnode *node);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
range	IN	範囲オブジェクト
node	IN	XMLノード

戻り値

(xmlerr) 数値のリターン・コード。

---

XmlDomRangeSetStartBefore()

範囲のスタート・ポイントをノードの前に設定します。範囲に現在のルート・コンテナ以外のルート・コンテナがある場合、範囲は新しい位置（オフセットは0）まで縮小されます。前のノードによりスタート・ポイントがエンド・ポイントの後に設定されている場合、範囲は新しい位置まで縮小されます。範囲のエンド・ポイントが有効なエンド・ポイントであると仮定します。

構文

xmlerr XmlDomRangeSetStartBefore(
   xmlctx *xctx,
   xmlrange *range,
   xmlnode *node);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
range	IN	範囲オブジェクト
node	IN	XMLノード

戻り値

(xmlerr) 数値のリターン・コード。