11 XML C用のXML APIパッケージ
このXMLプロセッサ(またはパーサー)のC実装は、W3CのXML仕様(改訂REC-xml-19980210)に準拠しており、XMLデータを読み込むためにXMLプロセッサに必要な動作、およびアプリケーションに提供する必要がある情報を含んでいます。
次の表にXML C APIのXML
パッケージで使用できるメソッドの概要を示します。
表11-1 XML C実装のXMLメソッドの概要
関数 | 概要 |
---|---|
URLのアクセス・メソッド・コールバックを設定します。 |
|
XML Developer's Toolkitの |
|
DTDを作成します。 |
|
ドキュメント(ノード)を作成します。 |
|
|
|
2つのXMLドキュメントを比較します。 |
|
ドキュメントを解放します(すべてのリソースを解放します)。 |
|
XMLコンテキストで使用されているデータ・エンコーディングを戻します。 |
|
DOM機能が実装されているかどうかを判別します。 |
|
シングルバイト(単純な)キャラクタ・セット・フラグを戻します。 |
|
|
|
XML文書をロード(解析)してDOMを生成します。 |
|
XML文書をロード(解析)してSAXイベントを生成します。 |
|
XML文書をロード(解析)してSAXイベント[ |
|
XML文書を保存(シリアル化、フォーマット)します。 |
|
XDKのバージョン文字列を戻します。 |
11.1 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]を戻します。
関連項目:
11.2 XmlCreate()
XML Developer's Toolkitのxmlctx
を作成します。
構文
xmlctx *XmlCreate(
xmlerr *err,
oratext *name,
list);
パラメータ | In/Out | 説明 |
---|---|---|
err |
OUT |
戻されたエラー・コード |
access |
IN |
コンテキスト名(デバッグ目的) |
list |
IN |
変数引数の
XDKの追加プロパティは次のとおりです。
これらのオプション・パラメータは、次のように使用してください。 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
が戻されます。
11.3 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ノード。
11.4 XmlCreateDocument()
最初のトップレベルのDOCUMENT
ノードおよびサポートするインフラストラクチャを作成します。修飾名を指定した場合、その名前の要素が作成され、ドキュメントのルート要素に設定されます。
構文
xmldocnode* XmlCreateDocument( xmlctx *xctx, oratext *uri, oratext *qname, xmldtdnode *dtd, xmlerr *err);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
uri |
IN |
作成するルート要素の名前空間のURI、または |
qname |
IN |
ルート要素の修飾名、または存在しない場合は |
dtd |
IN |
対応するDTDノード |
err |
OUT |
戻されたエラー・コード |
戻り値
(xmldocnode *)
新しいDocument
オブジェクト。
11.5 XmlDestroy()
XMLコンテキストを破棄します。
構文
void XmlDestroy( xmlctx *xctx);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
関連項目:
11.6 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 |
数値のエラー・コード。正常に終了した場合は、 |
flags |
IN |
比較オプション。デフォルトでは、グローバル・アルゴリズムとスナップショット・モデルが使用されます。
|
firstSourceType |
IN |
1つ目のドキュメントのソース・タイプ。 |
firstSource |
IN |
1つ目のドキュメント・ソースへのポインタ。 |
firstSourceExtra |
IN |
バッファ長ポインタのために使用される、1つ目のドキュメント・ソースへの追加ポインタ。 |
secondSourceType |
IN |
2つ目のドキュメントのソース・タイプ。 |
secondSource |
IN |
2つ目のドキュメント・ソースへのポインタ。 |
secondSourceExtra |
IN |
バッファ長ポインタのために使用される、2つ目のドキュメント・ソースへの追加ポインタ。 |
hashLevel |
IN |
すべての要素ノードのハッシュ値は、そのノードをルートとするサブツリー全体に関連付けられます。差分の計算時には、ハッシュ・レベルの深さを超えたツリーへのドリルダウンは行われません。
|
11.7 XmlFreeDocument()
XmlCreateDocument
またはLoad関数によって作成されたドキュメントを破棄します。さらに、ドキュメントに関連付けられている、無効となったすべてのリソースを解放します。
構文
void XmlFreeDocument( xmlctx *xctx, xmldocnode *doc);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
doc |
IN |
解放するドキュメント |
11.8 XmlGetEncoding()
XMLコンテキストで使用されているデータ・エンコーディングを戻します。通常、データ・エンコーディングはユーザーが選択するため、この関数は必要ありません。ただし、データ・エンコーディングが指定されておらず、デフォルトが使用されている場合、この関数を使用して、デフォルトのエンコーディング名を戻すことができます。
構文
oratext *XmlGetEncoding( xmlctx *xctx);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
戻り値
(oratext *)
データ・エンコーディングの名前。
関連項目:
11.9 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)
機能が実装されているかどうか。
11.10 XmlIsSimple()
コンテキストのデータ・エンコーディングが「シンプル」かどうか、すなわちASCIIやEBCDICのように各文字がシングルバイトであるかどうかを示すフラグを戻します。
構文
boolean XmlIsSimple( xmlctx *xctx);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
戻り値
(boolean)
データ・エンコーディングが「シンプル」の場合はTRUE
、それ以外はFALSE
。
11.11 XmlIsUnicode()
コンテキストのデータ・エンコーディングが、1文字に2バイトを使用するUnicode、UTF-16かどうかを示すフラグを戻します。
構文
boolean XmlIsUnicode( xmlctx *xctx);
パラメータ | In/Out | 説明 |
---|---|---|
xctx |
IN |
XMLコンテキスト |
戻り値
(boolean)
データ・エンコーディングがUnicodeの場合はTRUE
、そうでない場合はFALSE
。
11.12 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 |
変数引数の |
戻り値
(xmldocnode *)
成功時はドキュメント・ノードが戻されます。失敗時には、errが設定された状態でNULL
が戻されます。
関連項目:
11.13 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 |
変数引数の |
戻り値
(xmlerr)
数値のエラー・コード。正常に終了した場合は、XMLERR_OK [0]
を戻します。
11.14 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 |
変数引数の |
戻り値
(xmlerr)
数値のエラー・コード。正常に終了した場合は、XMLERR_OK [0]を戻します。
11.15 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 |
変数引数の |
戻り値
(ubig_ora)
出力先に書き込まれたバイト数。
関連項目: