XML C用のOrastream APIパッケージ

5 XML C用のOrastream APIパッケージ

Orastream APIは、XML文書での64Kを超えるテキスト・ノードおよびバイナリ・ノードの処理をサポートします。

Orastreamで使用されるデータ型は「Cのデータ型」に記載されています。oracheck、oraerr、oraprop_id、oramemctx、oraprop、oraprop_t、oraprop_v、orastreamおよびorastreamhdlが含まれます。

Orastreamインタフェースのエラー・コードを表5-1に示します。

表5-1 XML C実装のOrastreamエラー・コード

エラー・コード	説明
`ORASTREAM_ERR_NULL_POINTER`	Nullポインタが検出されました。
`ORASTREAM_ERR_BAD_STREAM`	無効なストリーム・オブジェクト。
`ORASTREAM_ERR_WRONG_DIRECTION`	ストリーム・オブジェクトは反対のI/O方向に定義されています。
`ORASTREAM_ERR_UNKNOWN_PROPERTY`	不明な作成プロパティ。
`ORASTREAM_ERR_NO_DIRECTION`	ストリームのI/O方向が定義されていません。
`ORASTREAM_ERR_BI_DIRECTION`	ストリームの方向は、両方のI/O方向を使用していると間違って定義されています。
`ORASTREAM_ERR_NOT_OPEN`	ストリームはオープンしていません。
`ORASTREAM_ERR_WRONG_MODE`	ストリームは反対のchar/byteモードに定義されています。
`ORASTREAM_ERR_CANT_OPEN`	ストリームをオープンできません。
`ORASTREAM_ERR_CANT_CLOSE`	ストリームをクローズできません。

次の表に示すOrastreamメソッドは、データのピース単位の移動に使用する一方向のストリームをサポートします。ストリームの方向およびモードは、OraStreamInit()メソッドでストリームを初期化するパラメータによって決定されます。

表5-2 XML C実装のOraStreamメソッドの概要

関数	概要
OraStreamClose()	ストリームをクローズします。
OraStreamHandle()	ストリームにハンドルを戻します。
OraStreamInit()	ストリームを初期化します。
OraStreamIsOpen()	ストリームがオープンしているかどうかを判断します。
OraStreamOpen()	ストリームをオープンします。
OraStreamRead()	ストリームからバイトを読み込みます。
OraStreamReadable()	ストリームが読取り可能かどうかを判断します。
OraStreamReadChar()	ストリームから文字を読み込みます。
OraStreamSid()	ストリームのSIDを設定します。
OraStreamTerm()	ストリームを破棄します。
OraStreamWrite()	ストリームにバイトを書き込みます。
OraStreamWritable()	ストリームが書込み可能かどうかを判断します。
OraStreamWriteChar()	ストリームに文字を書き込みます。

5.1 OraStreamClose()

orastreamオブジェクトをクローズします。

この関数を使用し、ストリームの「クローズ」コールバック関数をコールして、特定のストリームをクローズします。

成功した場合はORAERR_OKを戻し、失敗した場合はエラー・コードを戻します。

構文

oraerr OraStreamClose(
  orastream *stream);

パラメータ	In/Out	説明
stream	IN	クローズされるストリーム

5.2 OraStreamHandle()

orastreamオブジェクトのハンドルを戻します。

ハンドルには、汎用ポインタとファイル記述子が含まれます。

構文

orastreamhdl *OraStreamHandle(
  orastream *stream);

パラメータ	In/Out	説明
stream	IN	ハンドルが戻されるストリーム

5.3 OraStreamInit()

orastreamオブジェクトを作成して初期化します。

構文

orastream *OraStreamInit(
  void *sctx,
  void *sid,
  oraerr *err,
  list);

パラメータ	In/Out	説明
sctx	IN	入力コンテキスト。`NULL`の場合もあります
sid	IN	ユーザー定義のストリーム・コンテキスト識別子
err	OUT	エラー(存在する場合)。成功した場合は`ORAERR_OK`、失敗した場合はエラー・コード。
list	IN	新しい`orastream`オブジェクトのプロパティを指定する引数の名前/値ペアの`NULL`で終了するリスト。それらは次のとおりです。 `open`プロパティ名はオープン関数のためのもので、その値が続きます。 ORASTREAM_OPEN_F((), sctx, sid, hdl, length) `close`プロパティ名はクローズ関数のためのもので、その値が続きます。 ORASTREAM_CLOSE_F((), sctx, sid, hdl) `read`プロパティ名は、ストリームからバッファにバイト・データを読み込むためのものです。`nread`は実際に読み込まれたバイト数を戻します。 ORASTREAM_READ_F((), sctx, sid, hdl, dest, size, start, nread, eoi) `write`プロパティ名は、バッファからストリームにバイト・データを書き込むためのものです。`written`は実際に書き込まれたバイト数を戻します。 ORASTREAM_WRITE_F((), sctx, sid, hdl, src, size, written) `read_char`プロパティ名は、ストリームからバッファに文字データを読み込むためのものです。`nread`は実際に読み込まれた文字数を戻します。 ORASTREAM_READ_F((), sctx, sid, hdl, dest, size, start, nread, eoi) `write_char`プロパティ名は、バッファからストリームに文字データを書き込むためのものです。`written`は実際に書き込まれた文字数を戻します。 ORASTREAM_WRITE_F((), sctx, sid, hdl, src, size, written)

5.4 OraStreamIsOpen()

orastreamがオープンしているかどうかを判断します。TRUEまたはFALSEを返します。

読込みおよび書込み操作を実行するには、ストリームがオープンしている必要があります。

構文

boolean OraStreamIsOpen(
  orastream *stream);

パラメータ	In/Out	説明
stream	IN	読込みまたは書込みのためにオープンする必要のあるストリーム。

5.5 OraStreamOpen()

orastreamオブジェクトをオープンします。

この関数は、ストリームの「オープン」コールバック関数をコールしてストリームをオープンします。

成功した場合はORAERR_OKを戻し、失敗した場合はエラー・コードを戻します。

構文

oraerr OraStreamOpen(
  orastream *stream,
  ubig_ora *length)

パラメータ	In/Out	説明
stream	IN	オープンしているストリーム
length	OUT	オプションのパラメータ。使用されません

5.6 OraStreamRead()

orastreamオブジェクトからbyteを読み込みます。

この関数を使用して、ストリームから指定されたバッファにデータを読み込みます。また、ストリームの終わりに達すると、eoiパラメータにTRUEを戻します。

成功した場合はORAERR_OKを戻し、失敗した場合はエラー・コードを戻します。

構文

oraerr OraStreamRead(
  orastream *stream,
  oratext *dest,
  ubig_ora size,
  oratext **start,
  ubig_ora *nread,
  ub1 *eoi);

パラメータ	In/Out	説明
stream	IN	読み込まれるストリーム
dest	IN	宛先バッファ
size	IN	読み込まれるデータのサイズ
start	OUT	読み込まれるデータの先頭へのポインタ
nread	OUT	ストリームから実際に読み込まれたバイト数
eoi	OUT	ストリームの終わりに達すると`TRUE`を戻し、それ以外の場合は`FALSE`を戻します

5.7 OraStreamReadable()

既存のorastreamオブジェクトが読込み可能かどうかを判断します。

TRUEまたはFALSEを返します。

構文

boolean OraStreamReadable(
  orastream *stream);

パラメータ	In/Out	説明
stream	IN	読込み可能かどうかを確認するストリーム

5.8 OraStreamReadChar()

orastreamオブジェクトからcharを読み込みます。

成功した場合はORAERR_OKを戻し、失敗した場合はエラー・コードを戻します。

構文

oraerr OraStreamReadChar(
  orastream *stream,
  oratext *dest, 
  ubig_ora size,
  oratext **start, 
  ubig_ora *nread, 
  ub1 *eoi);

パラメータ	In/Out	説明
stream	IN	読み込まれるストリーム
dest	IN	宛先バッファ
size	IN	読み込まれるデータのサイズ
start	OUT	読み込まれるデータの先頭へのポインタ
nread	OUT	ストリームから実際に読み込まれた文字数
eoi	OUT	ストリームの終わりに達すると`TRUE`を戻し、それ以外の場合は`FALSE`を戻します

5.9 OraStreamSid()

既存のorastreamオブジェクトにSIDを割り当てます。OUTパラメータosidを使用してSIDを戻します。

成功した場合はORAERR_OKを戻し、失敗した場合はエラー・コードを戻します。

構文

oraerr OraStreamSid(
  orastream *stream,
  void *sid,
  void **osid);

パラメータ	In/Out	説明
stream	IN	SIDが変更されるストリーム
sid	IN	新しいSID
osid	OUT	ストリームの前のSID

5.10 OraStreamTerm()

orastreamオブジェクトを破棄して、対応するメモリーを解放します。

成功した場合はORAERR_OKを戻し、失敗した場合はエラー・コードを戻します。

構文

oraerr OraStreamTerm(
  orastream *stream);

パラメータ	In/Out	説明
stream	IN	破棄するストリーム

5.11 OraStreamWrite()

orastreamオブジェクトにbyteを書き込みます。

実際に読み込まれたバイト数は、OUTパラメータnwroteによって格納されます。

成功した場合はORAERR_OKを戻し、失敗した場合はエラー・コードを戻します。

構文

oraerr OraStreamWrite(
  orastream *stream, 
  oratext *src, 
  ubig_ora size,
  ubig_ora *nwrote);

パラメータ	In/Out	説明
stream	IN	データが書き込まれるストリーム
src	IN	データの書込み元バッファ
size	IN	書き込まれるデータのサイズ
nwrote	OUT	ストリームに書き込まれるバイト数

5.12 OraStreamWritable()

既存のorastreamオブジェクトが書込み可能かどうかを判断します。

TRUEまたはFALSEを返します。

構文

boolean OraStreamWritable(
  orastream *stream);

パラメータ	In/Out	説明
stream	IN	書込み可能かどうかを判断するストリーム。

5.13 OraStreamWriteChar()

orastreamオブジェクトにcharを書き込みます。

実際に書き込まれた文字数は、OUTパラメータnwroteによって格納されます。

成功した場合はORAERR_OKを戻し、失敗した場合はエラー・コードを戻します。

構文

oraerr OraStreamWriteChar(
  orastream *stream, 
  oratext *src, 
  ubig_ora size,
  ubig_ora *nwrote);

パラメータ	In/Out	説明
stream	IN	データが書き込まれるストリーム
src	IN	データの書込み元バッファ
size	IN	書き込まれるデータのサイズ
nwrote	OUT	ストリームに書き込まれる文字数