2 C用のコールバックAPIパッケージ

このパッケージでは、XMLコールバックの関数(または関数ポインタ)を宣言するマクロを定義します。コールバックはエラー・メッセージ処理、メモリーの割当てと解放およびストリーム操作に使用されます。

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

• コールバック・メソッド

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

---

コールバック・メソッド

表2-1にコールバック・インタフェースで使用できるメソッドの概要を示します。

表2-1 コールバック・メソッドの概要

関数	概要
XML_ACCESS_CLOSE_F()	ユーザー定義のアクセス・メソッド・クローズ・コールバック
XML_ACCESS_OPEN_F()	ユーザー定義のアクセス・メソッド・オープン・コールバック
XML_ACCESS_READ_F()	ユーザー定義のアクセス・メソッド読込みコールバック
XML_ALLOC_F()	低レベルのメモリー割当て
XML_ERRMSG_F()	エラー・メッセージ処理
XML_FREE_F()	低レベルのメモリー解放
XML_STREAM_CLOSE_F()	ユーザー定義のストリーム・クローズ・コールバック
XML_STREAM_OPEN_F()	ユーザー定義のストリーム・オープン・コールバック
XML_STREAM_READ_F()	ユーザー定義のストリーム読込みコールバック
XML_STREAM_WRITE_F()	ユーザー定義のストリーム書込みコールバック

---

XML_ACCESS_CLOSE_F()

このマクロはURLへのアクセスに使用する、クローズ関数コールバックのプロトタイプを定義します。

構文

#define XML_ACCESS_CLOSE_F(func, ctx, uh)
xmlerr func(
   void *ctx,
    xmlurlhdl *uh);

パラメータ	IN/OUT	説明
ctx	IN	ユーザー定義のコンテキスト
uh	IN	URLハンドル

戻り値

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

関連項目: XML_ACCESS_OPEN_F()、XML_ACCESS_READ_F()

---

XML_ACCESS_OPEN_F()

このマクロはURLへのアクセスに使用する、オープン関数コールバックのプロトタイプを定義します。

構文

#define XML_ACCESS_OPEN_F(func, ctx, uri, parts, length, uh)
xmlerr func(
   void *ctx,
   oratext *uri, 
   xmlurlpart *parts,
   ubig_ora *length, 
   xmlurlhdl *uh);

パラメータ	IN/OUT	説明
ctx	IN	ユーザー定義のコンテキスト
uri	IN	オープンされるURI
parts	IN	コンポーネントに分割されたURI
length	OUT	入力データの長さがわかっている場合は合計の長さ、わからない場合は0
uh	IN	URLハンドル

戻り値

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

関連項目: XML_ACCESS_CLOSE_F()、XML_ACCESS_READ_F()

---

XML_ACCESS_READ_F()

このマクロはURLへのアクセスに使用する、読込み関数コールバックのプロトタイプを定義します。

構文

#define XML_ACCESS_READ_F(func, ctx, uh, data, nraw, eoi)
xmlerr func(
   void *ctx, 
   xmlurlhdl *uh, 
   oratext **data, 
   ubig_ora *nraw,
   ub1 *eoi);

パラメータ	IN/OUT	説明
ctx	IN	ユーザー定義のコンテキスト
uh	IN	URLハンドル
data	IN/OUT	受信者のデータ・バッファ。データの先頭にリセット
nraw	OUT	読み込まれる実際のデータ・バイト数
eoi	OUT	情報の終わりへのシグナル、最後のチャンク

戻り値

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

関連項目: XML_ACCESS_OPEN_F()、XML_ACCESS_CLOSE_F()

---

XML_ALLOC_F()

このマクロはユーザーが指定する低レベル・メモリーalloc関数のプロトタイプを定義します。アロケータが指定されない場合、mallocが使用されます。この関数によるメモリーがゼロにならないようにしてください。XML_FREE_F()に対応します。

構文

#define XML_ALLOC_F(func, mctx, size)
void *func(
   void *mctx,
   size_t size);

パラメータ	IN/OUT	説明
mctx	IN	低レベルのメモリー・コンテキスト
size	IN	割り当てられるバイト数

戻り値

(void *) 割り当てられたメモリー数。

関連項目: XML_FREE_F()

---

XML_ERRMSG_F()

このマクロはエラー・メッセージ処理関数のプロトタイプを定義します。XML初期化の際にエラー・メッセージ・コールバックが割り当てられない場合、エラーはstderrに出力されます。ハンドラが指定されている場合、stderrへの出力のかわりにハンドラが呼び出されます。

構文

#define XML_ERRMSG_F(func, ectx, msg, err)
void func(
   void *ectx,
   oratext *msg,
   xmlerr err);

パラメータ	IN/OUT	説明
ectx	IN	エラー・メッセージ・コンテキスト
msg	IN	エラー・メッセージのテキスト
err	IN	数値のエラー・コード

関連項目: 第11章「C用のXML APIパッケージ」のXmlCreate()

---

XML_FREE_F()

このマクロはユーザーが指定する低レベル・メモリー解放関数のプロトタイプを定義します。アロケータが指定されない場合、free()が使用されます。XML_ALLOC_F()に対応します。

構文

#define XML_FREE_F(func, mctx, ptr)
void func(
   void *mctx,
   void *ptr);

パラメータ	IN/OUT	説明
mctx	IN	低レベルのメモリー・コンテキスト
ptr	IN	解放されるメモリー

---

XML_STREAM_CLOSE_F()

このマクロはオープン・ソースをクローズし、そのリソースを解放するためにコールされるクローズ関数コールバックのプロトタイプを定義します。

構文

#define XML_STREAM_CLOSE_F(func, xctx, sctx)
void func(
   xmlctx *xctx,
   void *sctx);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
sctx	IN	ユーザー定義のストリーム・コンテキスト

関連項目: XML_STREAM_OPEN_F()、XML_STREAM_READ_F()、XML_STREAM_WRITE_F()

---

XML_STREAM_OPEN_F()

このマクロは、入力ソースをオープンするために1回コールされる、オープン関数コールバックのプロトタイプを定義します。この関数は、成功するとXMLERR_OKを戻します。

構文

#define XML_STREAM_OPEN_F(func, xctx, sctx, path, parts, length)
xmlerr func(
   xmlctx *xctx,
   void *sctx,
   oratext *path,
   void *parts,
   ubig_ora *length);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
sctx	IN	ユーザー定義のストリーム・コンテキスト
path	IN	オープンするURIへのフルパス
parts	IN	コンポーネントに分割されたURI(不透明ポインタ)
length	(OUT)	入力データの長さがわかっている場合は合計の長さ、わからない場合は0

戻り値

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

関連項目: XML_STREAM_CLOSE_F()、XML_STREAM_READ_F()、XML_STREAM_WRITE_F()

---

XML_STREAM_READ_F()

このマクロは、オープン・ソースのデータをバッファに読み込むためにコールされ、読み込まれるバイト数(エラー時は0)を戻す、読込み関数コールバックのプロトタイプを定義します。　　eoiフラグは、これがデータの最終ブロックかどうかを判断します。

EOIでは、クローズ関数が自動的にコールされます。

構文

#define XML_STREAM_READ_F(func, xctx, sctx, path, dest, size, nraw, eoi)
xmlerr func(
   xmlctx *xctx,
   void *sctx,
   oratext *path,
   oratext *dest,
   size_t size,
   sbig_ora *nraw,
   boolean *eoi);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
sctx	IN	ユーザー定義のストリーム・コンテキスト
path	IN	(エラー・メッセージの)オープン・ソースのフルURI
dest	(OUT)	データの読込み先の宛先バッファ
size	IN	宛先バッファのサイズ
nraw	(OUT)	読み込まれるバイト数
eoi	(OUT)	情報の終わりへのシグナル、最後のチャンク

戻り値

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

関連項目: XML_STREAM_OPEN_F()、XML_STREAM_CLOSE_F()、XML_STREAM_WRITE_F()

---

XML_STREAM_WRITE_F()

このマクロはユーザー定義のストリームにデータを書き込むためにコールされる、書込み関数コールバックのプロトタイプを定義します。

構文

#define XML_STREAM_WRITE_F(func, xctx, sctx, path, src, size)
xmlerr func(
   xmlctx *xctx,
   void *sctx,
   oratext *path,
   oratext *src,
   size_t size);

パラメータ	IN/OUT	説明
xctx	IN	XMLコンテキスト
sctx	IN	ユーザー定義のストリーム・コンテキスト
path	IN	(エラー・メッセージの)オープン・ソースのフルURI
src	IN	データを読み込むソース・バッファ
size	IN	ソースのサイズ(バイト)

戻り値

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

関連項目: XML_STREAM_OPEN_F()、XML_STREAM_CLOSE_F()、XML_STREAM_READ_F()