11 C用のXML APIパッケージ

このXMLプロセッサ(またはパーサー)のC実装は、W3CのXML仕様(改訂REC-xml-19980210)に準拠しており、XMLデータを読み込むためにXMLプロセッサに必要な動作、およびアプリケーションに提供する必要がある情報を含んでいます。

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

• XMLインタフェース

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

---

XMLインタフェース

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

表11-1 XMLメソッドの概要

関数	概要
XmlAccess()	URLのアクセス・メソッド・コールバックを設定します。
XmlCreate()	XML Developer's Toolkitのxmlctxを作成します。
XmlCreateDTD()	DTDを作成します。
XmlCreateDocument()	ドキュメント(ノード)を作成します。
XmlDestroy()	xmlctxを破棄します。
XmlDiff()	2つのXMLドキュメントを比較します。
XmlFreeDocument()	ドキュメントを解放します(すべてのリソースを解放します)。
XmlGetEncoding()	XMLコンテキストで使用されているデータ・エンコーディングを戻します。
XmlHasFeature()	DOM機能が実装されているかどうかを判別します。
XmlIsSimple()	シングルバイト(単純な)キャラクタ・セット・フラグを戻します。
XmlIsUnicode()	XmlIsUnicode(単純な)キャラクタ・セット・フラグを戻します。
XmlLoadDom()	XML文書をロード(解析)してDOMを生成します。
XmlLoadSax()	XML文書をロード(解析)してSAXイベントを生成します。
XmlLoadSaxVA()	XML文書をロード(解析)してSAXイベント[varargs]を生成します。
XmlSaveDom()	XML文書を保存(シリアル化、フォーマット)します。
XmlVersion()	XDKのバージョン文字列を戻します。

---

XmlAccess()

特定のURLアクセス・メソッドのデータをロードするために使用するオープン/読込み/クローズ・コールバックを設定します。HTTP、FTPなどのための組込みデータ・ロード関数をオーバーライドするか、または新しい型(UNKNOWNなど)を処理するための関数を提供します。

構文

xmlerr XmlAccess(
   xmlctx *xctx, 
   xmlurlacc access, 
   void *userctx,
   XML_ACCESS_OPEN_F(
      (*openf),
      ctx,
      uri,
      parts,
      length,
      uh),
   XML_ACCESS_READ_F(
      (*readf),
      ctx,
      uh,
      data,
      nraw,
      eoi),
   XML_ACCESS_CLOSE_F(
      (*closef), 
      ctx,
      uh));

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
access	IN	URLアクセス・メソッド
userctx	IN	コールバックに渡されるユーザー定義のコンテキスト
openf	IN	アクセスをオープンするコールバック関数
readf	IN	アクセスを読み込むコールバック関数
closef	IN	アクセスをクローズするコールバック関数

戻り値

(xmlerr) 数値のエラー・コード。正常に終了した場合は、XMLERR_OK [0]を戻します。

関連項目: XmlLoadDom()、XmlLoadSax()

---

XmlCreate()

XML Developer's Toolkitのxmlctxを作成します。

構文

xmlctx *XmlCreate(
   xmlerr *err, 
   oratext *name,
   list);

パラメータ	IN/OUT	説明
err	OUT	戻されたエラー・コード
access	IN	コンテキスト名(デバッグ目的)
list	IN	変数引数のNULLで終了するリスト。xmlctxのXDKおよびXMLTypeの両方に共通のプロパティは次のとおりです。 data_encodingは、DOMおよびSAXによってXMLデータの表示に使用されるデータ・エンコーディングです。デフォルトはUTF-8およびEBCDICプラットフォームのUTF-Eです。シングルバイト・エンコーディングの方がマルチバイト・エンコーディングよりも高速です。Unicode(UTF-16)は、より多くのメモリーを消費しますが、マルチバイトよりもパフォーマンスが優れています。 default_input_encodingは、デフォルトの入力エンコーディングです。入力ドキュメントのエンコーディングが他のメソッドによって自動的に判別できない場合、このエンコーディングがデフォルトになります。 error_languageは、エラー・メッセージの作成に使用される言語(およびオプションでエンコーディング)です。デフォルトはUTF-8エンコーディングを使用した「American」です。言語のみを指定する場合は、言語名("American")を指定します。エンコーディングも指定するには、ピリオドに続いてエンコーディングのOracle名称を追加します("American.WE8ISO8859P1")。 error_handlerは、関数ポインタです。XML_ERRMSG_Fを参照してください。デフォルトでは、エラー時にフォーマット済のメッセージがstderrに出力されます。エラー・ハンドラを指定すると、フォーマット済のメッセージは印刷されずにハンドラに渡されます。 error_contextは、エラー・ハンドラ用のユーザー定義コンテキストであり、エラー・ハンドラ関数に渡されるコンテキスト・ポインタです。ユーザーが定義します。ここでは指定するのみで、エラー発生時に渡されます。 input_encodingは、入力ドキュメントの強制入力エンコーディングの名前です。ドキュメントのXMLDeclをオーバーライドし、常に指定したエンコーディングで解析するために使用します。既存のBOMおよびXMLDeclは正確であるため、このプロパティは通常の場合は必ずしも必要ではありません。 mallocを使用しない場合、memory_allocは、低レベルのメモリー割当て関数です。これを使用する場合、対応する解放関数も指定する必要があります。XML_ALLOC_Fを参照してください。 freeを使用しない場合、memory_freeは、低レベルのメモリー解放関数です。memory_alloc関数に対応します。 memory_contextは、allocおよびfree関数に渡されるユーザー定義のメモリー・コンテキストです。定義および用途はユーザーが決定できます。ここでは単に設定し、コールバックに渡されます。 XDKの追加プロパティは次のとおりです。 input_buffer_sizeは、基本的なI/Oバッファ・サイズです。デフォルトは256K、範囲は4Kから4MBまでです。エンコーディングにより、これらのバッファが1つ、2つまたは3つ必要になります。サイズはバイト数ではなく文字数です。バッファがUnicodeデータを保持する場合、サイズは倍の大きさになります。 memory_block_sizeは、高レベルのメモリー・パッケージが低レベルのアロケータから要求するチャンク・サイズで、メモリー割当ての基本単位です。デフォルトは64K、範囲は16Kから256Kまでです。 これらのオプション・パラメータは、次のように使用してください。 xmlctx *XmlCreate( xmlerr *err, oratext *name, ("data_encoding", dataEncoding), ("default_data_encoding", defaultDataEncoding), ("error_language", errorLanguage), ("error_handler", errorHandler), ("error_context", errorContext) ("input_encoding", inputEncoding), ("memory_alloc", memAlloc), ("memory_free", memFree), ("memory_context", memContext), ("input_buffer_seize", inputBufSize), ("memory_block_size", memBlockSize) );

戻り値

(xmlctx *) 作成されたxmlctx。エラー発生時にはerrが設定された状態でNULLが戻されます。

関連項目: XmlDestroy()および第2章「C用のコールバックAPIパッケージ」のXML_ERRMSG_F()

---

XmlCreateDTD()

DTDを作成します。

構文

xmldocnode* XmlCreateDTD(
   xmlctx *xctx
   oratext *qname,
   oratext *pubid,
   oratext *sysid,
   xmlerr *err);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
qname	IN	修飾名
pubid	IN	外部サブセットの公開識別子
sysid	IN	外部サブセットのシステム識別子
err	OUT	戻されたエラー・コード

戻り値

(xmldtdnode *) 新しいDTDノード。

---

XmlCreateDocument()

最初のトップレベルのDOCUMENTノードおよびサポートするインフラストラクチャを作成します。修飾名を指定した場合、その名前の要素が作成され、ドキュメントのルート要素に設定されます。

構文

xmldocnode* XmlCreateDocument(
   xmlctx *xctx,
   oratext *uri,
   oratext *qname, 
   xmldtdnode *dtd,
   xmlerr *err);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
uri	IN	作成するルート要素の名前空間のURI、またはNULL
qname	IN	ルート要素の修飾名、または存在しない場合はNULL
dtd	IN	対応するDTDノード
err	OUT	戻されたエラー・コード

戻り値

(xmldocnode *) 新しいDocumentオブジェクト。

---

XmlDestroy()

XMLコンテキストを破棄します。

構文

void XmlDestroy(
   xmlctx *xctx);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト

関連項目: XmlCreate()

---

XmlDiff()

DOMツリー、ファイル、URI、orastreamなどとして指定された2つのXMLドキュメントを比較し、そのドキュメント・ノードを戻します。入力ドキュメントがDOMツリーとして指定されていない場合、それらのDOMツリーが作成されます。

入力がDOMの場合、そのメモリーはコールの完了時に解放されません。

両方のドキュメントのデータ(DOM)エンコーディングは、XMLコンテキストでのデータ・エンコーディングと同じである必要があります。差分のDOMは、XMLコンテキストによって指定されたデータ・エンコーディングで作成されます。

構文

xmldocnode *XmlDiff(
   xmlctx *xctx, 
   xmlerr *err,
   ub4  flags,
   xmldfsrct firstSourceType,
   void *firstSource,
   void *firstSourceExtra,
   xmldfsrct secondSourceType,
   void *secondSource,
   void *secondSourceExtra,
   uword hashLevel);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
err	OUT	数値のエラー・コード。正常に終了した場合は、XMLERR_OK [0]を戻します。
flags	IN	比較オプション。デフォルトでは、グローバル・アルゴリズムとスナップショット・モデルが使用されます。 XMLDF_FL_DEFAULTS(=0)でデフォルトが選択されます。 XMLDF_FL_ALGORITHM_GLOBALは、グローバル・アルゴリズムです。INSERT、APPEND、DELETEおよびUPDATEを使用して最小diffを生成し、XMLDF_FL_ALGORITHM_LOCALよりも多くのメモリーと時間を必要とします。 XMLDF_FL_ALGORITHM_LOCALは、ローカル・アルゴリズムです。最小diffを生成しない場合がありますが、XMLDF_FL_ALGORITHM_GLOBALよりも高速で、使用領域は少なくなります。 XMLDF_FL_DISABLE_UPDATEは、グローバル・アルゴリズムによる更新操作を無効化します。 XMLDF_FL_OUTPUT_SNAPSHOTは、スナップショット・モデルを使用します。
firstSourceType	IN	1つ目のドキュメントのソース・タイプ。0の場合、DOMドキュメント・ノードとみなされます。
firstSource	IN	1つ目のドキュメント・ソースへのポインタ。
firstSourceExtra	IN	バッファ長ポインタのために使用される、1つ目のドキュメント・ソースへの追加ポインタ。
secondSourceType	IN	2つ目のドキュメントのソース・タイプ。0の場合、DOMドキュメント・ノードとみなされます。
secondSource	IN	2つ目のドキュメント・ソースへのポインタ。
secondSourceExtra	IN	バッファ長ポインタのために使用される、2つ目のドキュメント・ソースへの追加ポインタ。
hashLevel	IN	1-ベースの深さ(ルートからカウント)。サブツリーにはハッシングが使用されます。1以下の値は、ハッシングなしを示します。この値は、プログラムで指定される必要があります。 すべての要素ノードのハッシュ値は、そのノードをルートとするサブツリー全体に関連付けられます。差分の計算時には、ハッシュ・レベルの深さを超えたツリーへのドリルダウンは行われません。 XMLDF_FL_ALGORITHM_GLOBALによってハッシングが使用される場合、差分計算の時間は大幅に短縮されますが、差分の質が低下する場合があります。 XMLDF_FL_ALGORITHM_LOCALによる場合は、差分の質が向上します。

---

XmlFreeDocument()

XmlCreateDocumentまたはLoad関数によって作成されたドキュメントを破棄します。さらに、ドキュメントに関連付けられている、無効となったすべてのリソースを解放します。

構文

void XmlFreeDocument(
   xmlctx *xctx,
   xmldocnode *doc);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
doc	IN	解放するドキュメント

関連項目: XmlCreateDocument()、XmlLoadDom()

---

XmlGetEncoding()

XMLコンテキストで使用されているデータ・エンコーディングを戻します。通常、データ・エンコーディングはユーザーが選択するため、この関数は必要ありません。ただし、データ・エンコーディングが指定されておらず、デフォルトが使用されている場合、この関数を使用して、デフォルトのエンコーディング名を戻すことができます。

構文

oratext *XmlGetEncoding(
   xmlctx *xctx);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト

戻り値

(oratext *) データ・エンコーディングの名前。

関連項目: XmlIsSimple()、XmlIsUnicode()

---

XmlHasFeature()

DOM機能が実装されているかどうかを判別します。機能が指定バージョンで実装されている場合はTRUE、実装されていない場合はFALSEを戻します。

レベル1では、パッケージの正当な値は「HTML」および「XML」(大/小文字は区別されない)、バージョンは文字列「1.0」です。バージョンを指定しなかった場合は、この機能のどのバージョンが実装されていても、TRUEが戻されます。

• DOM 1.0の機能は「XML」および「HTML」です。

• DOM 2.0の機能は、「Core」、「XML」、「HTML」、「Views」、「StyleSheets」、「CSS」、「CSS2」、「Events」、「UIEvents」、「MouseEvents」、「MutationEvents」、「HTMLEvents」、「Range」、「Traversal」です。

構文

boolean XmlHasFeature(
   xmlctx *xctx,
   oratext *feature,
   oratext *version);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
feature	IN	テストする機能のパッケージ名
version	IN	テストするパッケージ名のバージョン番号

戻り値

(boolean) 機能が実装されているかどうか。

---

XmlIsSimple()

コンテキストのデータ・エンコーディングが「シンプル」かどうか、すなわちASCIIやEBCDICのように各文字がシングルバイトであるかどうかを示すフラグを戻します。

構文

boolean XmlIsSimple(
   xmlctx *xctx);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト

戻り値

(boolean) データ・エンコーディングが「シンプル」の場合はTRUE、それ以外はFALSE。

関連項目: XmlGetEncoding()、XmlIsUnicode()

---

XmlIsUnicode()

コンテキストのデータ・エンコーディングが、1文字に2バイトを使用するUnicode、UTF-16かどうかを示すフラグを戻します。

構文

boolean XmlIsUnicode(
   xmlctx *xctx);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト

戻り値

(boolean) データ・エンコーディングがUnicodeの場合はTRUE、そうでない場合はFALSE。

関連項目: XmlGetEncoding()、XmlIsSimple()

---

XmlLoadDom()

入力ソースからXML文書をロード(解析)してDOMを生成します。正常に終了した場合はルート・ドキュメント・ノード、エラーが発生した場合は(errを設定した状態で)NULLを戻します。

この関数は、2つの固定引数のxmlctxとエラー・リターン・コード、0個以上の(プロパティ, 値)ペア、およびNULLを取ります。

SOURCE: 入力ソースは、次のいずれかの相互に排他的なプロパティの1つによって設定されます(1つを選択します)。

• ("uri", ドキュメントのURI) [コンパイラのエンコーディング]

• ("file", ドキュメントのファイルシステム・パス) [コンパイラのエンコーディング]

• ("buffer", バッファのアドレス, "buffer_length", バッファ内のバイト数)

• ("stream", ストリーム・オブジェクトのアドレス, "stream_context", ストリーム・オブジェクトのコンテキストへのポインタ)

• ("stdio", FILEストリーム)

PROPERTIES: 追加プロパティは次のとおりです。

• ("dtd", DTDノード) ドキュメントのDTD

• ("base_uri", ドキュメントのベースURI) URI以外のソースからロードされたドキュメントの場合に、有効なベースURIを設定します。ドキュメントのベースURIは、相対URIのinclude、importなどの解決に必要です。

• ("input_encoding", エンコーディング名) 強制入力エンコーディング[名前]

• ("default_input_encoding", encoding_name) ドキュメントが自己記述的でない場合(BOM、プロトコル・ヘッダー、XMLDeclなどがない場合)に使用するデフォルトの入力エンコーディング

• ("schema_location", string) ドキュメントのスキーマのschemaLocation。ドキュメントをデータベースにロードする際に最適のレイアウトを判別するために使用されます。

• ("validate", ブール値) TRUEの場合、DTD検証を有効にします。デフォルトで、整形式のみ確認されます。スキーマの検証は別に扱われます。

• ("discard_whitespace", ブール値) TRUEの場合、入力ドキュメントの要素間の書式化用の空白(改行およびインデント)は削除されます。デフォルトでは、すべての入力文字が保持されます。

• ("dtd_only", ブール値) TRUEの場合、完全なドキュメントではなく、外部DTDを解析します。

• ("stop_on_warning", ブール値) TRUEの場合、警告はエラーと同様に扱われ、解析、検証などが即時停止されます。デフォルトでは、警告が発行されても処理は継続されます。

• ("warn_duplicate_entity", ブール値) TRUEの場合、エンティティが複数回宣言されると、警告が発行されます。デフォルトでは、最初の宣言が受け入れられ、その後の宣言は暗黙的に無視されます。

• ("no_expand_char_ref", ブール値) TRUEの場合、文字参照はDOMデータ内で展開されません。通常、文字参照は表現する文字によって置換されます。ただし、ドキュメントが保存されると、それらの文字エンティティは再表示されません。ロードおよび保存の過程でこれらを保持するには、展開しないようにします。

• ("no_check_chars", ブール値) TRUEの場合、XML [2] Char productionのテストを省略し、すべての入力文字が有効として受け入れられます。

構文

xmldocnode *XmlLoadDom(
   xmlctx *xctx, 
   xmlerr *err, 
   list);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
err	OUT	戻されたエラー・コード
list	IN	変数引数のNULLで終了するリスト

戻り値

(xmldocnode *) 成功時はドキュメント・ノードが戻されます。失敗時には、errが設定された状態でNULLが戻されます。

関連項目: XmlSaveDom()

---

XmlLoadSax()

入力ソースからXML文書をロード(解析)し、SAXイベントのセットを(ユーザー・コールバックとして)生成します。入力ソースおよびプロパティの基本セットは、XmlLoadDomと同じです。

構文

xmlerr XmlLoadSax(
   xmlctx *xctx,
   xmlsaxcb *saxcb,
   void *saxctx, 
   list);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
saxcb	IN	SAXコールバック構造
saxctx	IN	SAXコールバックに渡されるコンテキスト
list	IN	変数引数のNULLで終了するリスト

戻り値

(xmlerr) 数値のエラー・コード。正常に終了した場合は、XMLERR_OK [0]を戻します。

---

XmlLoadSaxVA()

入力ソースからXML文書をロード(解析)し、SAXイベントのセットを(ユーザー・コールバックとして)生成します。入力ソースおよびプロパティの基本セットは、XmlLoadDomと同じです。

構文

xmlerr XmlLoadSaxVA(
   xmlctx *xctx, 
   xmlsaxcb *saxcb, 
   void *saxctx, 
   va_list va);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
saxcb	IN	SAXコールバック構造
saxctx	IN	SAXコールバックに渡されるコンテキスト
va	IN	変数引数のNULLで終了するリスト

戻り値

(xmlerr) 数値のエラー・コード。正常に終了した場合は、XMLERR_OK [0]を戻します。

---

XmlSaveDom()

ドキュメントまたはサブツリーを指定された宛先にシリアル化し、書き込まれたバイト数を戻します。宛先が指定されていない場合、フォーマット後のサイズのみ戻し、出力は戻しません。

出力エンコーディングが指定されている場合、ドキュメントは出力時に再エンコードされます。そうでない場合、既存のエンコーディングのままです。

最上位はインデントされたステップ×レベルの空白、次のレベルはステップ×(レベル+1)の空白で、以下同様です。

バッファに保存する際、バッファがオーバーフローすると0(ゼロ)が戻され、エラーがXMLERR_SAVE_OVERFLOWに設定されます。

DESTINATION: 出力先は、相互に排他的な次のいずれかのプロパティによって設定されます(1つを選択します)。

• ("uri", ドキュメントのURI) POST、PUT? [コンパイラのエンコーディング]

• ("file", ドキュメントのファイルシステム・パス) [コンパイラのエンコーディング]

• ("buffer", バッファのアドレス, "buffer_length", バッファ内のバイト数)

• ("stream", ストリーム・オブジェクトのアドレス, "stream_context", ストリーム・オブジェクトのコンテキストへのポインタ)

PROPERTIES: 追加プロパティは次のとおりです。

• ("output_encoding", エンコーディング名) ドキュメントの最終エンコーディングの名前。指定された場合を除き、xmlctxと同じエンコーディングが使用されます。

• ("indent_step", 符号なし) 出力の各レベルをインデントする空白数。デフォルトは4です。0(ゼロ)はインデントなしを示します。

• ("indent_level", 符号なし) 最初のインデント・レベル。デフォルトは0(ゼロ)で、インデントなし、左揃えを示します。

• ("xmldecl", ブール値) 出力ドキュメントにXMLDeclを含めます。通常、XMLDeclは、完全なドキュメントの出力です(ルート・ノードはDOC)。

• ("bom", ブール値) 出力ドキュメントにBOMを入力します。通常、BOMは特定のエンコーディング(UTF-16)にのみ必要で、他のエンコーディング(UTF-8)の場合はオプションです。オプションでBOMを出力します。

• ("prune", ブール値) 出力をUNIXの'find'コマンドのようにプルーニングします。子には派生せず、指定された1つのノードのみ出力します。

構文

ubig_ora XmlSaveDom(
   xmlctx *xctx,
   xmlerr *err,
   xmlnode *root,
   list);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
err	OUT	失敗した場合、エラー・コード
root	IN	保存するルート・ノードまたはサブツリー
list	IN	変数引数のNULLで終了するリスト

戻り値

(ubig_ora) 出力先に書き込まれたバイト数。

関連項目: XmlLoadDom()

---

XmlVersion()

XDKのバージョン文字列を戻します。

構文

oratext *XmlVersion();

戻り値

(oratext *) バージョン文字列。