SFXElasticStreamWriter

可変長バッファを使用して書き込み用ストリームにアクセスするためのクラスです。

#include <SFXElasticStreamWriter.h.hpp>

class SFXElasticStreamWriter : public SFXOutputStream;

SFMTYPEDEFCLASS(SFXElasticStreamWriter)

継承図

協調図

解説

SFXElasticStreamWriter とは

SFXElasticStreamWriter クラスは、可変長バッファストリームにデータを書き込むときに内部的に利用されます。

size 引数(バッファサイズ)を指定せずにストレージクラスの GetStreamWriter 関数を呼び出して SFXBinaryStreamWriter / SFXAnsiStringStreamWriter / SFXWideStringStreamWriter ストリームを取得すると、ストリームバッファは可変長になります。

このとき、内部では、 SFXElasticStreamWriter::Attach 関数を使用して SFXBinaryStreamWriter / SFXAnsiStringStreamWriter / SFXWideStringStreamWriter ストリームに SFXElasticStreamWriter ストリームを結び付けます。この処理により、ストリームへのデータの書き込みは可変長バッファを使用して行われることになります。

バッファは書き込むデータのサイズまで自動的に拡張されます。

	注意
	可変長バッファを使用してストリームにデータを書き込む処理は実装済みなので、開発者が明示的に `SFXElasticStreamWriter` クラスを使用する必要はありません。

参照

メンバ

コンストラクタ/デストラクタ
SFXElasticStreamWriter( `Void` ) SFXElasticStreamWriter クラスのコンストラクタです。

パブリック関数
`Void`	Attach( `SFXOutputStreamPtr` stream ) このストリームに指定されたストリームを結び付けます。
`Void`	Cancel( `Void` ) ストリームへの書き込みをキャンセルします。
`SFXOutputStreamPtr`	Detach( `Void` ) このストリームに結び付けられているストリームを切り離します。
`SFCError`	Flush( `Void` ) ストリームのデータをストレージに書き込みます。
`SFCError`	Flush( `CallbackSPP` spp , `VoidPtr` reference ) ストリームのデータをストレージに書き込みます。
`UInt32`	GetWritableSize( `Void` ) ストリームに書き込み可能なデータサイズを取得します。[単位: バイト]
`Void`	Release( `Void` ) ストリームを解放します。
`SFCError`	ResetTrigger( `Void` ) トリガー(コールバック関数が呼ばれるタイミング)をリセットします。
`SFCError`	SetTrigger( `UInt32` size ) トリガー(コールバック関数が呼ばれるタイミング)を設定します。
`SFCError`	SetTrigger( `SFXBufferConstRef` buffer ) トリガー(コールバック関数が呼ばれるタイミング)を設定します。
`SFCError`	SetTrigger( `VoidConstPtr` buffer , `UInt32` size ) トリガー(コールバック関数が呼ばれるタイミング)を設定します。
`Bool`	Triggers( `Void` ) トリガーによりコールバック関数が呼び出されたか判定します。
`SFCError`	Write( `SFXBufferConstRef` buffer ) ストリームにデータを書き込みます。
`SFCError`	Write( `VoidConstPtr` buffer , `UInt32` size ) ストリームにデータを書き込みます。

型
CallbackSPP (SFXStream から継承) コールバック関数を表す型です。

SFXElasticStreamWriter::SFXElasticStreamWriter

SFXElasticStreamWriter クラスのコンストラクタです。

[ public, explicit ]
SFXElasticStreamWriter(Void);

解説

特に何も行いません。

SFXElasticStreamWriter::Attach

このストリームに指定されたストリームを結び付けます。

[ public ]
Void Attach(
    SFXOutputStreamPtr stream   // 設定するストリーム
);

解説

この関数は、このストリームに指定されたストリームを結び付けます。

この関数を呼び出す前にこのストリームに設定されていたストリームと可変長バッファは破棄されます。

参照

SFXElasticStreamWriter::Detach

SFXElasticStreamWriter::Cancel

ストリームへの書き込みをキャンセルします。

[ public, virtual ]
Void Cancel(Void);

解説

この関数は、このストリームからへの書き込みをキャンセルします。

具体的には、下記の処理を内部で行います。

このストリームに関連付けられたストレージの Cancel 関数を呼び出します。

ファイルの場合は SFXFile::Cancel 関数を、 TCP ソケットの場合は SFXTCPSocket::Cancel 関数を呼び出します。
SFXElasticStreamWriter::Flush 関数による、このストリームについてのコールバック関数の登録をキャンセルします。

	注意
	この関数は、内部的に `SFXElasticStreamWriter::Release` 関数から呼び出されます。

参照

SFXElasticStreamWriter::Flush | SFXFile::Cancel | SFXTCPSocket::Cancel

SFXElasticStreamWriter::Detach

このストリームに結び付けられているストリームを切り離します。

[ public ]
SFXOutputStreamPtr Detach(Void);

戻り値

このストリームに結び付けられていたストリーム

解説

この関数を呼び出した後、このストリームは設定されていない状態になります。また、可変長バッファは破棄されます。

参照

SFXElasticStreamWriter::Attach

SFXElasticStreamWriter::Flush

ストリームのデータをストレージに書き込みます。

[ public, virtual ]
SFCError Flush(Void);

[ public, virtual ]
SFCError Flush(
    CallbackSPP spp     // コールバック関数
    VoidPtr reference   // コールバック関数に渡すデータ（参照値）
);

戻り値

成功したとき: SFERR_NO_ERROR
ストリームが設定されていない、または既にこの関数を呼び出してコールバックを待っているとき: SFERR_INVALID_STATE
失敗したとき: SFERR_FAILED または AEEError.h で定義されるエラー値

解説

この関数は、ストリームバッファ内のデータをストリームに関連付けられたストレージに書き込みます。

この関数には、コールバック関数を登録するタイプと登録しないタイプがあります。利用可能なタイプはストレージの種類に依存します。

例えば、SFXTCPSocket クラスから得られるストリームでは、コールバック関数を登録するタイプだけが利用可能です。一方、SFXFile クラスから得られるストリームでは、両方のタイプが使用できます。

コールバック関数を登録しないタイプの場合、この関数を呼び出すと、内部バッファのデータはすぐにストレージに書き込まれます。

	Tip
	`SFXElasticStreamWriter::Write` 関数を呼び出すことにより、ストリームバッファにデータを書き込みます。

参照

SFXElasticStreamWriter::Write | SFXElasticStreamWriter::SetTrigger | ストリームバッファ | ストレージ

SFXElasticStreamWriter::GetWritableSize

ストリームに書き込み可能なデータサイズを取得します。[単位: バイト]

[ public, const ]
UInt32 GetWritableSize(Void);

戻り値

ストリームが設定されているとき: 0xFFFFFFFF
そうでないとき: 0

解説

この関数は、ストリームバッファに書き込み可能なデータサイズを取得します。[単位: バイト]

SFXElasticStreamWriter クラスは可変長バッファストリームなので、メモリが許す限り、SFXElasticStreamWriter::Write 関数を呼び出してストリームバッファにデータを書き込めます。

ストレージクラスの GetStreamReader 関数によりストリームが設定されていれば 0xFFFFFFFF を返します。設定されていない場合は 0 を返します。

	注意
	メモリの制約があるので、実際には 0xFFFFFFFF よりも小さな値になります。

参照

SFXElasticStreamWriter::Write | SFXElasticStreamWriter::Flush | ストリームバッファ | 可変長バッファストリーム | ストレージ

SFXElasticStreamWriter::Release

ストリームを解放します。

[ public ]
Void Release(Void);

解説

この関数は、このストリームへの書き込みをキャンセルし、ストリームを解放します。

注意

	注意
この関数は、ストリームのデストラクタから呼び出されます。また、`SFXElasticStreamWriter::Cancel` 関数を呼び出して、このストリームからの書き込みをキャンセルします。

この関数は、ストリームのデストラクタから呼び出されます。

また、SFXElasticStreamWriter::Cancel 関数を呼び出して、このストリームからの書き込みをキャンセルします。

参照

SFXElasticStreamWriter::Cancel

SFXElasticStreamWriter::ResetTrigger

トリガー(コールバック関数が呼ばれるタイミング)をリセットします。

[ public, virtual ]
SFCError ResetTrigger(Void);

戻り値

成功したとき: SFERR_NO_ERROR
ストリームが設定されていない、または既に SFXElasticStreamWriter::Flush 関数を呼び出してコールバックを待っているとき: SFERR_INVALID_STATE

解説

この関数は、 SFXElasticStreamWriter::SetTrigger 関数で設定したトリガー(コールバック関数が呼ばれるタイミング)をリセットします。

参照

SFXElasticStreamWriter::SetTrigger | SFXElasticStreamWriter::Triggers | SFXElasticStreamWriter::Flush

SFXElasticStreamWriter::SetTrigger

トリガー(コールバック関数が呼ばれるタイミング)を設定します。

[ public, virtual ]
SFCError SetTrigger(
    UInt32 size   // トリガーとなるサイズ
);

[ public, virtual ]
SFCError SetTrigger(
    SFXBufferConstRef buffer   // トリガーとなるデータ
);

[ public, virtual ]
SFCError SetTrigger(
    VoidConstPtr buffer   // トリガーとなるデータ
    UInt32 size           // トリガーとなるデータのサイズ
);

戻り値

成功したとき: SFERR_NO_ERROR
ストリームが設定されていない、または SFXElasticStreamWriter::Flush 関数によりコールバック関数が登録された状態であるとき: SFERR_INVALID_STATE
メモリ不足のとき: SFERR_NO_MEMORY

解説

SFXElasticStreamWriter::Flush 関数で登録されたコールバック関数は、ストリームバッファ内のデータをこのストリームに設定されたストレージに書き込んだときに呼び出されます。

この関数は、これ以外のタイミングでコールバック関数を呼び出すためのトリガーを設定します。

size 引数だけを指定した場合は、そのサイズのデータを書き込む毎にコールバック関数が呼び出されます。

buffer 引数を指定した場合は、それと同じデータを書き込む毎にコールバック関数が呼び出されます。

使用例

改行文字を書き込む毎にコールバック関数を呼び出す方法は、以下の通りです。

SetTrigger("\r\n", 2);

参照

SFXElasticStreamWriter::ResetTrigger | SFXElasticStreamWriter::Triggers | SFXElasticStreamWriter::Flush

SFXElasticStreamWriter::Triggers

トリガーによりコールバック関数が呼び出されたか判定します。

[ public, virtual, const ]
Bool Triggers(Void);

戻り値

SFXElasticStreamWriter::SetTrigger 関数で設定したトリガーによって、コールバック関数が呼び出されたとき: true
そうでないとき: false

解説

この関数は、 SFXElasticStreamWriter::SetTrigger 関数で設定したトリガーによって、コールバック関数が呼び出されたか判定します。

	Tip
	`SFXElasticStreamWriter::Flush` 関数で登録したコールバック関数の中で使います。

参照

SFXElasticStreamWriter::SetTrigger | SFXElasticStreamWriter::ResetTrigger | SFXElasticStreamWriter::Flush

SFXElasticStreamWriter::Write

ストリームにデータを書き込みます。

[ public, virtual ]
SFCError Write(
    SFXBufferConstRef buffer   // 書き込むバッファ
);

[ public, virtual ]
SFCError Write(
    VoidConstPtr buffer   // 書き込むバッファ
    UInt32 size           // 書き込むデータのサイズ
);

戻り値

成功したとき: SFERR_NO_ERROR
ストリームが設定されていないとき: SFERR_INVALID_STATE
buffer 引数が null、size 引数が 0 以下、またはメモリ不足で書き込めないとき: SFERR_FAILED

解説

この関数は、 buffer 引数のデータをストリームバッファに書き込みます。

SFXElasticStreamWriter クラスは可変長バッファストリームなので、メモリが許す限り引数のデータをストリームバッファに書き込めます。

	注意
	buffer 引数が null、size 引数が 0 以下、またはメモリ不足のときは、 SFERR_FAILED を返します。

	Tip
	`SFXElasticStreamWriter::Flush` 関数を呼び出すことにより、ストリームバッファ内のデータはストリームに関連付けられたストレージに書き込まれ、ストリームバッファは空になります。

参照

SFXElasticStreamWriter::GetWritableSize | SFXElasticStreamWriter::Flush | ストリームバッファ | 可変長バッファストリーム | ストレージ