SFUStream

ストリームを表す抽象クラスです。

#include <SFUStream.hpp>

class SFUStream : public SFAException, public SFAStreamManipulator;

typedef SFUStream&          SFUStreamRef;
typedef SFUStream*          SFUStreamPtr;
typedef SFUStream**         SFUStreamHandle;
typedef const SFUStream     ConstSFUStream;
typedef const SFUStream&    ConstSFUStreamRef;
typedef const SFUStream*    ConstSFUStreamPtr;
typedef const SFUStream**   ConstSFUStreamHandle;

継承図

解説

SFUStream クラスは、ストリームを表す抽象クラスです。このクラスは、ストリームの基本機能を定義しています。

インサータ (<<) やエクストラクタ (>>) を使用してデータ型ごとの入出力を実装しています。
実際のデータ入出力を行う Put と Get を宣言しています。
シーク可能なストリームに対するインターフェイスとして、 Seek と Tell を宣言しています。
データの残り量を取得するための Available と、ストリームの終端に達したかどうかを判断する IsEOS を宣言しています。

Put、Get、Seek、Tell、Available、IsEOS は、純粋仮想関数として宣言されており、具体的なストリームを実装する派生クラスで定義されなければなりません。

派生クラス

SFUStream の派生クラスには、ファイル入出力を行う SFUFileStream、メモリの読み書きを行う SFUMemoryStream、 BREW の ISource インターフェイスからの読み取りを行う SFUSourceStream、 TCP/UDP ソケットの入出力を行う SFUNetworkStream が用意されています。

また、上記の６つの関数をオーバーライドすれば、開発者は独自にストリームを定義できます。

ストリームのエラー処理

ストリームの関数は、エラーが発生するとエラーコードを設定します。

表 13. ストリームで使用されるエラーコード

`SFERR_STREAM_NOT_OPEN`	ストリームがオープンされていません。
`SFERR_STREAM_ALREADY_OPEN`	ストリームがすでにオープンされています。
`SFERR_STREAM_READ_FAILED`	ストリームからデータを読み取れません。
`SFERR_STREAM_WRITE_FAILED`	ストリームにデータを書き込めません。
SFERR_STREAM_EOS	ストリームの終端に達しています。
SFERR_STREAM_BUFFER_FULL	バッファ (主に書き込みバッファ) がいっぱいです。
SFERR_STREAM_NO_DATA	バッファ (主に読み取りバッファ) にデータがありません。
SFERR_STREAM_CANNOT_BIND	バインドできません。

参照

SFUFileStream | SFUMemoryStream | SFUSourceStream | SFUNetworkStream

メンバ

コンストラクタ/デストラクタ
public	SFUStream	SFUStream クラスのコンストラクタです。
public	~SFUStream	SFUStream クラスのデストラクタです。

パブリック関数
public	Available	ストリームの読み取りの残りデータサイズを返します。
public	Exception (SFAException から継承)	エラーコードを取得/設定します。
public	Get	ストリームからデータを読み取ります。
public	IsEOS	読み込みポインタがストリームが終端に達しているかどうか判定します。
public	Put	ストリームにデータを書き込みます。
public	Seek	ストリームの読み込み／書き込みポインタを移動します。
public	Tell	現在の読み込み／書き込みポインタの位置を取得します。
public	operator<<	ストリームのインサータ (書き込み演算子) です。
public	operator>>	ストリームのエクストラクタ (読み取り演算子) です。

プロテクト関数
public	Exception (SFAException から継承)	エラーコードを取得/設定します。
protected	endianbig	読み込みモード／書き込みモードのエンディアンをビッグエンディアンに設定します。
protected	endianlittle	読み込みモード／書き込みモードのエンディアンをリトルエンディアンに設定します。
protected	multi	任意のサイズのデータを読み書きします。
protected	offset	ストリームの読み込み/書き込みポインタを指定された位置に移動します。
protected	seek	ストリームの読み込み/書き込みポインタを指定された位置に移動します。

型
	EndianEnum	ストリームのエンディアン変換を表す定数です。
	NO_ERROR (SFAException から継承)	エラーがないことを表す定数です。
	SeekEnum	ストリームのシークモードを表す定数です。

SFUStream::SFUStream

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

[ public ]
SFUStream(Void);

解説

データメンバの初期化を行います。読み込み/書き込みいずれもリトルエンディアンとして初期化されます。

SFUStream::~SFUStream

SFUStream クラスのデストラクタです。

[ public, virtual ]
~SFUStream(Void);

解説

一般に派生クラスでは、デストラクタで後処理を行います。

SFUStream::Available

ストリームの読み取りの残りデータサイズを返します。

[ public, pure-virtual ]
UInt32 Available(Void);

解説

この関数は純粋仮想関数です。派生クラスで実装されなければなりません。

参照

SFUStream::IsEOS

SFUStream::endianbig

読み込みモード／書き込みモードのエンディアンをビッグエンディアンに設定します。

[ protected ]
Void endianbig(
    ModeEnum mode   // 読み込みモード／書き込みモード
);

解説

ストリームの読み込みまたは書き込み時のエンディアンを、ビッグエンディアンに設定します。この関数は、通常マニピュレータ経由で使用します。下記の使用例を参照してください。

使用例

下記の例では、メモリストリームに対して、整数値をホストのエンディアン形式からビッグエンディアン形式に変換しながら出力しています。

SFUMemoryStream mstr;
mstr.Open(256);
mstr << endianbig << (UInt32) 0x12345678 << (SInt16) 0xABCD;

参照

SFUStream::endianlittle

SFUStream::endianlittle

読み込みモード／書き込みモードのエンディアンをリトルエンディアンに設定します。

[ protected ]
Void endianlittle(
    ModeEnum mode   // 読み込みモード／書き込みモード
);

解説

ストリームの読み込みまたは書き込み時のエンディアンを、リトルエンディアンに設定します。この関数は、通常マニピュレータ経由で使用します。下記の使用例を参照してください。

使用例

下記の例では、メモリストリームに対して、整数値をビッグエンディアン形式からホストのエンディアン形式に変換しながら読み込んでいます。

SFUMemoryStream mstr;
... メリストリームにデータを書き込む ...

UInt32 n;
SInt16 m;
mstr >> endianlittle >> n >> m;

参照

SFUStream::endianbig

SFUStream::Get

ストリームからデータを読み取ります。

[ public, pure-virtual ]
UInt32 Get(
    VoidPtr ptr   // 読み取ったデータを格納するポインタ
    UInt32 size   // 読み取るデータサイズ
);

解説

この関数は純粋仮想関数であり、派生クラスで実装されなければなりません。

実装の仕様は派生クラスに完全に依存しますが、次のような仕様を推奨します。

ptr が NULL で、size が 0 でない場合は、エラー値 SFERR_INVALID_PARAM を設定する。
読み取ることのできるデータが存在しないなどの理由でエラーが発生した場合は、エラー値に SFERR_STREAM_READ_FAILED を設定する。
指定されたサイズのデータを読み取ることができなかった場合は、ストリームポインタを一切進めない。
エラーが発生した場合は 0 を返す。
指定されたサイズのデータを読み取ることに成功した場合は、エラー値に SFERR_NO_ERROR を設定し、ストリームポインタをサイズ分だけ進め、指定のサイズを返す。

参照

SFUStream::Put

SFUStream::IsEOS

読み込みポインタがストリームが終端に達しているかどうか判定します。

[ public, pure-virtual ]
Bool IsEOS(Void);

解説

この関数は、純粋仮想関数です。派生クラスで実装する必要があります。

実装の仕様は派生クラスに完全に依存しますが、次のような仕様を推奨します。

ストリームがオープンされていない (初期化されていない) 場合は、TRUE を返す。
この関数は、エラー値を設定しない。

Available が 0 を返すからとって、この関数が TRUE となるとは限らないことに注意してください。たとえばネットワークストリームなど、どれだけのデータが取得できるかあらかじめ予測できないストリームの場合、 Avaiable が 0 を返しても、ネットワークの接続が切断されない限り IsEOS は TRUE にはなりません。

参照

SFUStream::Available

SFUStream::multi

任意のサイズのデータを読み書きします。

[ protected, virtual ]
Void multi(
    VoidPtr ptr     // 読み込み先のポインタ
    UInt32 size     // 読み込むサイズ
    ModeEnum mode   // 読み込みモードの指定
);

[ protected, virtual ]
Void multi(
    ConstVoidPtr ptr   // 書き込みデータのポインタ
    UInt32 size        // 書き込むサイズ
    ModeEnum mode      // 書き込みモードの指定
);

解説

この関数は、通常マニピュレータ経由で呼び出します。下記の使用例を参照してください。

使用例

下記の例では、ストリームから 128 バイトのデータを読み込んでいます。

BytePtr ptr = new Byte[128];
stream >> multi(ptr, 128);

参照

SFUStream::Get | SFUStream::Put

SFUStream::offset

ストリームの読み込み/書き込みポインタを指定された位置に移動します。

[ protected, virtual ]
Void offset(
    SInt32 offset   // 現在位置からのオフセット
    ModeEnum mode   // 読み込み／書き込みモード指定
);

解説

この関数は Seek を呼び出すことで、ストリームの読み込み／書き込みポインタを移動します。この関数は、通常マニピュレータ経由で呼び出します。下記の使用例を参照してください。

使用例

下記の例では、現在のストリーム位置を 4 バイト戻ってから、 4 バイト整数を書き込んでいます。

UInt32 n = 123;
stream << offset(-4) << n;

参照

SFUStream::seek

SFUStream::Put

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

[ public, pure-virtual ]
UInt32 Put(
    ConstVoidPtr ptr   // 書き込むデータのポインタ
    UInt32 size        // 書き込むデータのサイズ
);

解説

この関数は純粋仮想関数であり、派生クラスで実装されなければなりません。

実装の仕様は派生クラスに完全に依存しますが、次のような仕様を推奨します。

ptr が NULL で、size が 0 でない場合は、エラー値 SFERR_INVALID_PARAM を設定する。
書き込むためのメモリが足りない場合は、エラー値 SFERR_NO_MEMORY を設定します。
その他の理由で書き込みに失敗した場合は、エラー値 SFERR_WRITE_FAILED を設定する。
指定されたサイズをすべて書き込めない場合はエラーになる。
関数が失敗した場合は、書き込みポインタは進まず、0 を返す。
関数が成功した場合、エラー値 SFERR_NO_ERROR を設定し、書き込みポインタは size だけ進み、size を返す。

使用例

下記の例では、ランダムなデータを 32 バイト書き込んでいます。

BytePtr data = new Byte[32];
GETRAND(data, 32);
stream.Put(data, 32);

参照

SFUStream::Get

SFUStream::seek

ストリームの読み込み/書き込みポインタを指定された位置に移動します。

[ protected, virtual ]
Void seek(
    SInt32 offset   // 先頭からのオフセット
    ModeEnum mode   // 読み込み／書き込みモード指定
);

解説

使用例

下記の例では、現在のストリーム位置を先頭に移動します。

UInt32 n = 123;
stream << seek(0) << n;

参照

SFUStream::offset

SFUStream::Seek

ストリームの読み込み／書き込みポインタを移動します。

[ public, pure-virtual ]
UInt32 Seek(
    SInt32 offset   // オフセット
    SeekEnum dir    // シークモード
    ModeEnum mode   // 読み込み／書き込みモード
);

引数

offset

移動量を表すオフセット値です。負の値も指定できます。

dir

以下のいずれかの値を指定します。

SEEK_START (ストリームの開始位置からの移動)

SEEK_CURRENT (ストリームの現在位置からの移動)

SEEK_END (ストリームの終端位置からの移動)

mode

以下のいずれかの値を指定します。

MODE_READ (読み込みモード)

MODE_WRITE (書き込みモード)

解説

この関数は純粋仮想関数であり、派生クラスで実装されなければなりません。

実装の仕様は派生クラスに完全に依存しますが、次のような仕様を推奨します。

指定されたモードでストリームがオープン (初期化) されていない場合は、エラー値 SFERR_STREAM_NOT_OPEN を設定します。
無効な位置や無効なモードが指定された場合はエラー値 SFERR_INVALID_PARAM を設定します。
範囲外の値が指定された場合はエラー値 SFERR_FAILED を設定します。
失敗した場合は、UInt32(-1) を返します。
成功した場合はエラー値 SFERR_NO_ERROR を設定します。

参照

SFUStream::Tell

SFUStream::Tell

現在の読み込み／書き込みポインタの位置を取得します。

[ public, pure-virtual ]
UInt32 Tell(
    ModeEnum mode   // 読み込み／書き込みモード
);

解説

この関数は純粋仮想関数であり、派生クラスで実装されなければなりません。

実装の仕様は派生クラスに完全に依存しますが、次のような仕様を推奨します。

無効なモードが指定された場合は、エラー値 SFERR_INVALID_PARAM を設定します。
ストリームがオープン (初期化) されていない場合は、エラー値 SFERR_STREAM_NOT_OPEN を設定します。
関数が失敗した場合は、UInt32(-1) を返します。
関数が成功した場合は、エラー値 SFERR_NO_ERROR を設定します。

参照

SFUStream::Seek

SFUStream::EndianEnum

ストリームのエンディアン変換を表す定数です。

enum EndianEnum {
    ENDIAN_BIG = 0,
    ENDIAN_LITTLE
};

参照

SFUStream::endianbig | SFUStream::endianlittle

SFUStream::SeekEnum

ストリームのシークモードを表す定数です。

enum SeekEnum {
    SEEK_START   = _SEEK_START,
    SEEK_CURRENT = _SEEK_CURRENT,
    SEEK_END     = _SEEK_END
};

解説

SFUStream のシークモード定数は、 BREW API のシークモード定数へのエイリアスです。

参照

SFUStream::Seek

SFUStream::operator>>

ストリームのエクストラクタ (読み取り演算子) です。

[ public ]
SFUStreamRef operator>>(
    SFUAnsiStringRef str   
);

[ public ]
SFUStreamRef operator>>(
    SFUWideStringRef str   
);

[ public ]
SFUStreamRef operator>>(
    ACharRef ch   
);

[ public ]
SFUStreamRef operator>>(
    UInt08Ref num   
);

[ public ]
SFUStreamRef operator>>(
    SInt08Ref num   
);

[ public ]
SFUStreamRef operator>>(
    UInt16Ref num   
);

[ public ]
SFUStreamRef operator>>(
    SInt16Ref num   
);

[ public ]
SFUStreamRef operator>>(
    UInt32Ref num   
);

[ public ]
SFUStreamRef operator>>(
    SInt32Ref num   
);

[ public ]
SFUStreamRef operator>>(
    ZeroManipSPP manip   
);

[ public ]
SFUStreamRef operator>>(
    BaseManipRef manip   
);

[ public ]
SFUStreamRef operator>>(
    SingleManipRef manip   
);

解説

エクストラクタは各種のデータ型に対して、内部で Get を呼び出すことで、ストリームから読み取りを行います。

数値型を引数にとるエクストラクタは、ストリームのエンディアン変換モードに従って、 Get を呼び出してからエンディアン変換を行います。

文字列型を引数にとるエクストラクタは、ヌル文字が出現するまで文字を読み取り、結果の文字列を返します。ヌル文字が現れることなくストリーム終端に達した場合は、ストリーム終端までの文字列を返します。

マニピュレータを引数にとるエクストラクタは、そのマニピュレータを実装している関数を呼び出します。

参照

SFUStream::operator<<

SFUStream::operator<<

ストリームのインサータ (書き込み演算子) です。

[ public ]
SFUStreamRef operator<<(
    AChar ch   
);

[ public ]
SFUStreamRef operator<<(
    ConstACharPtr    
);

[ public ]
SFUStreamRef operator<<(
    ConstWCharPtr    
);

[ public ]
SFUStreamRef operator<<(
    UInt08 num   
);

[ public ]
SFUStreamRef operator<<(
    SInt08 num   
);

[ public ]
SFUStreamRef operator<<(
    UInt16 num   
);

[ public ]
SFUStreamRef operator<<(
    SInt16 num   
);

[ public ]
SFUStreamRef operator<<(
    UInt32 num   
);

[ public ]
SFUStreamRef operator<<(
    SInt32 num   
);

[ public ]
SFUStreamRef operator<<(
    ZeroManipSPP manip   
);

[ public ]
SFUStreamRef operator<<(
    BaseManipRef manip   
);

[ public ]
SFUStreamRef operator<<(
    ConstManipRef manip   
);

[ public ]
SFUStreamRef operator<<(
    SingleManipRef manip   
);

解説

インサータは各種のデータ型に対して、内部で Put を呼び出すことで、ストリームへの書き込みを行います。

数値型を引数にとるインサータは、ストリームのエンディアン変換モードに従って、エンディアン変換を行ってから Put を呼び出します。

文字列型を引数にとるインサータは、文字列の終端までの文字に対して Put を呼び出します。しかし、文字列終端のヌル文字は出力しません。

マニピュレータを引数にとるインサータは、そのマニピュレータを実装している関数を呼び出します。

参照

SFUStream::operator>>