SFXSource

ISource インターフェースからデータを読み込むのためのストレージクラスです。

#include <SFXSource.h.hpp>

class SFXSource : public SFXStorage;

SFMTYPEDEFCLASS(SFXSource)

継承図

協調図

解説

SFXSource クラスは、 BREW API ISource インターフェースにアクセスするためのクラスです。

■ SFXSource クラスの使用手順

SFBSource インスタンス（ソース）を作成します。
SFXSource::OpenSFXSource::Open 関数を呼び出してソースを SFXSource ストレージに設定します。
SFXSource::GetStreamReader 関数を呼び出して読み込み用ストリームを取得し、 SFXSource ストレージからデータを読み込みます。
※ストリームを利用しない場合、 SFXSource::Read 関数を呼び出してデータを読み込みます。
SFXSource::Close 関数を呼び出して SFXSource ストレージを閉じます。

	制限事項
	データの読み込みだけがサポートされます。データの書き込みはサポートされません。また、読み込み位置の移動もサポートしません。

例 854. SFXSource クラスの使用方法

Void MyClass::UseSFXSource(Void)
{
    SFXSource source; 
    static ACharConst data[] = "test data"; // SFBSource ストレージから読み込むデータ
    SFXAnsiString string;           // SFBSource ストレージから読み込む変数
    SFXBinaryStreamReader reader;   // 読み込み用ストリーム
    SFBSourceUtilSmp util;
    SFBSourceSmp bs;

    // メモリブロックから SFBSource を作成する
    util = SFBSourceUtil::NewInstance();
    util->SourceFromMemory(data, sizeof(data), null, null, &bs);

    // SFXSource ストレージを設定する
    if (source.Open(bs) == SFERR_NO_ERROR) {

        // 読み込み用ストリームを取得する
        if (source.GetStreamReader(1024, &reader) == SFERR_NO_ERROR) {

            reader.Fetch();  // SFXSource ストレージからストリームバッファにデータを読み込む 
            reader >> string; // 読み込みストリームから string 変数にデータを読み込む

            // SFXSource ストレージから読み込んだ内容を表示する
            TRACE("size = %d", string.GetLength());   // 文字列の長さを表示する: "size = 9"
            TRACE("read = %s", string.GetCString());  // 文字列を表示する: "read = test data"   

            reader.Release();  // 読み込みストリームを解放する
        }

        // SFXSource ストレージを閉じる
        source.Close();  
    }
    return;
}

参照

メンバ

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

パブリック関数
`SFCError`	AsSFBAStream( `SFBAStreamSmpPtr` result ) SFBAStream インスタンスに変換します。
`SFCError`	AsSFBSource( `SFBSourceSmpPtr` result ) SFBSource インスタンスを取得します。
`Void`	Cancel( `Void` ) Read のスケジュールをキャンセルします。
`Void`	Close( `Void` ) ソースを閉じます。
`SFBSourceSmpConstRef`	GetSFBSource( `Void` ) 内部で使用している SFBSource インスタンスを取得します。
`SFCError`	GetStreamReader( `UInt32` size , `SFXStreamReaderPtr` result ) 読み込み用ストリームを取得します。
`SFCError`	GetStreamReader( `SFXStreamReaderPtr` result ) 読み込み用ストリームを取得します。
`SFCError`	GetStreamWriter( `UInt32` size , `SFXStreamWriterPtr` result ) 【現在、この関数は使えません。】
`SFCError`	GetStreamWriter( `SFXStreamWriterPtr` result ) 【現在、この関数は使えません。】
`SFCError`	Open( `SFXStorageConstRef` storage ) ストレージ、ストリーム、またはソースを設定します。
`SFCError`	Open( `SFBSourceSmpConstRef` source ) ストレージ、ストリーム、またはソースを設定します。
`SFCError`	Open( `SFBAStreamSmpConstRef` stream ) ストレージ、ストリーム、またはソースを設定します。
`SFCError`	Read( `VoidPtr` buffer , `UInt32Ptr` size ) Read（ストリームを使用しないソースからのデータ読み込み）を行います。
`SFCError`	ScheduleRead( `CallbackSPP` spp , `VoidPtr` reference ) Read（ストリームを使用しないソースからのデータ読み込み）をスケジュールします。
`SFCError`	ScheduleWrite( `CallbackSPP` spp , `VoidPtr` reference ) 【現在、この関数は使えません。】
`SFCError`	Write( `VoidConstPtr` buffer , `UInt32Ptr` size ) 【現在、この関数は使えません。】

型
CallbackSPP (SFXStorage から継承) ストレージクラスで使用するコールバック関数の型です。

SFXSource::SFXSource

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

[ public, explicit ]
SFXSource(Void);

解説

このコンストラクタは、何も行いません。

SFXSource::~SFXSource

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

[ public, virtual ]
virtual ~SFXSource(Void);

解説

このデストラクタは、 SFXSource::Close 関数を呼び出します。

	注意
	登録されていたコールバックはキャンセルされます。

参照

SFXSource::Close

SFXSource::AsSFBAStream

SFBAStream インスタンスに変換します。

[ public, virtual, const ]
SFCError AsSFBAStream(
    SFBAStreamSmpPtr result   // SFBAStream インスタンスへのポインタ
);

引数

result: SFBAStream インスタンスへのポインタを指定します。

戻り値

成功したとき: SFERR_NO_ERROR
このストレージが閉じているとき: SFERR_INVALID_STATE
result 引数が null のとき: SFERR_INVALID_PARAM

解説

この関数は、このストレージが内部で管理する SFBSource インスタンスを SFBAStream インスタンスに変換します。

result 引数には、変換結果である SFBAStream インスタンスへのポインタが返ります。

	注意
	この関数は、内部で BREW API の `BREW API ISOURCEUTIL_AStreamFromSource` 関数を呼び出します。

	注意
	この関数により、このストレージを `SFBAStream` インスタンスとして扱えます。

参照

SFBSource | SFBAStream | BREW API ISOURCEUTIL_AStreamFromSource

SFXSource::AsSFBSource

SFBSource インスタンスを取得します。

[ public, virtual, const ]
SFCError AsSFBSource(
    SFBSourceSmpPtr result   // SFBSource インスタンスへのポインタ
);

引数

result: SFBSource インスタンスへのポインタを指定します。

戻り値

成功したとき: SFERR_NO_ERROR
このストレージが閉じているとき: SFERR_INVALID_STATE
result 引数が null のとき: SFERR_INVALID_PARAM

解説

この関数は、このストレージが内部で管理する SFBSource インスタンスを取得します。

result 引数には、変換結果である SFBSource インスタンスへのポインタが返ります。

	注意
	この関数により、このストレージを `SFBSource` インスタンスとして扱えます。

参照

SFBSource

SFXSource::Cancel

Read のスケジュールをキャンセルします。

[ public, virtual ]
Void Cancel(Void);

解説

この関数は、 SFXSource::ScheduleRead 関数による Read（ストリームを使用しないソースからのデータ読み込み）のスケジュールをキャンセルします。

具体的には、コールバック関数の登録をキャンセルします。

	注意
	この関数は、`SFXSource::Close` 関数から呼び出されます。

参照

SFXSource::ScheduleRead | SFXSource::Close

SFXSource::Close

ソースを閉じます。

[ public ]
Void Close(Void);

解説

この関数は、このソースを閉じます（このソースを終了します）。

具体的には、 SFXSource::Cancel 関数を呼び出して Read（ストリームを使用しないソースからのデータ読み込み）のスケジュールをキャンセルし、内部で管理している SFBSource インスタンスを解放します。

	注意
	登録されていたコールバックはキャンセルされます。

	注意
	この関数は、`SFXSource::~SFXSource` デストラクタから呼び出されます。

	Tip
	サスペンド時は、この関数を呼び出してリソースを解放します。

参照

SFXSource::Cancel | SFXSource::~SFXSource | SFXSource::OpenSFXSource::Open | SFBSource

SFXSource::GetSFBSource

内部で使用している SFBSource インスタンスを取得します。

[ public, const ]
SFBSourceSmpConstRef GetSFBSource(Void);

SFXSource::GetStreamReader

読み込み用ストリームを取得します。

[ public, virtual ]
SFCError GetStreamReader(
    UInt32 size                 // バッファサイズ
    SFXStreamReaderPtr result   // 読み込み用ストリームへのポインタ
);

[ public, virtual ]
SFCError GetStreamReader(
    SFXStreamReaderPtr result   // 読み込み用ストリームへのポインタ
);

戻り値

成功したとき: SFERR_NO_ERROR
result 引数が null のとき: SFERR_INVALID_PARAM
SFXSource::OpenSFXSource::Open 関数を使用してソースを登録していないとき: SFERR_INVALID_STATE
メモリ不足のとき: SFERR_NO_MEMORY

解説

この関数は、読み込み用ストリームを取得します。

size 引数を指定する場合、ストリームバッファは指定したサイズで固定です。指定しない場合は、ストリームバッファは可変長になり、内部的に SFXElasticStreamReader クラスが利用されます。

	Tip
	読み込み用ストリームは、読み込むデータの種類に応じて `SFXBinaryStreamReader`、 `SFXAnsiStringStreamReader`、または `SFXWideStringStreamReader` クラスを使い分けます。

	注意
	この関数を呼び出す前に、 `SFXSource::OpenSFXSource::Open` 関数を使用してソースを登録する必要があります。

参照

SFXSource::GetStreamWriter | SFXBinaryStreamReader | SFXAnsiStringStreamReader | SFXWideStringStreamReader | ストリームバッファ

SFXSource::GetStreamWriter

【現在、この関数は使えません。】

[ public, virtual ]
SFCError GetStreamWriter(
    UInt32 size                 // サイズ
    SFXStreamWriterPtr result   // 書き込み用ストリームへのポインタ
);

[ public, virtual ]
SFCError GetStreamWriter(
    SFXStreamWriterPtr result   // 書き込み用ストリームへのポインタ
);

戻り値

SFERR_UNSUPPORTED

解説

【現在、この関数は使えません。】

参照

SFXSource::GetStreamReader

SFXSource::Open

ストレージ、ストリーム、またはソースを設定します。

SFXSource::Open

[ public ]
SFCError Open(
    SFXStorageConstRef storage   // ストレージ
);

[ public ]
SFCError Open(
    SFBSourceSmpConstRef source   // ソース
);

[ public ]
SFCError Open(
    SFBAStreamSmpConstRef stream   // ストリーム
);

戻り値

成功したとき: SFERR_NO_ERROR
ストレージ、ストリーム、またはソースが既に設定されているとき: SFERR_INVALID_STATE
引数が null のとき: SFERR_INVALID_PARAM

解説

この関数は、ストレージ、ストリーム、またはソースをこの SFXSource ストレージに設定します。

この関数を実行した後、 SFXSource::GetStreamReader 関数または SFXSource::Read 関数を使用してデータを読み込むことが可能です。

	注意
	ストレージとストリームは、内部的にそれぞれ AsSFBSource 関数と `SFBSourceUtil::SourceFromAStream` 関数によりソースに変換されて設定されます。

参照

SFXSource::Close | SFXSource::GetStreamReader | SFXSource::Read | SFBSourceUtil::SourceFromAStream BREW API ISOURCEUTIL_SourceFromAStream

SFXSource::Read

Read（ストリームを使用しないソースからのデータ読み込み）を行います。

[ public, virtual ]
SFCError Read(
    VoidPtr buffer   // データを読み込むバッファ
    UInt32Ptr size   // 呼び出す前: データを読み込むバッファのサイズ。戻り値: 実際に読み込んだデータのサイズ
);

引数

buffer: データを読み込むバッファを指定します。
size: この関数を呼び出す時は、データを読み込むバッファのサイズを指定します。この関数が戻ると、実際にバッファに読み込んだデータのサイズが格納されています。

戻り値

成功したとき: SFERR_NO_ERROR
ソースが登録されていないとき: SFERR_INVALID_STATE
size 引数が null のとき: SFERR_INVALID_PARAM
再試行が必要なとき: ISOURCE_WAIT(-2)
エラーを検出したとき: ISOURCE_ERROR(-1)

解説

この関数は、Read（ストリームを使用しないソースからのデータ読み込み）を行います。

ソースからすべてのデータが読み込まれた場合、この関数は SFERR_NO_ERROR を返し、かつ、 size 引数のポインタが指す場所に 0 が戻ります。

※ この関数が ISOURCE_WAIT を返す場合、 SFXSource::ScheduleRead 関数でコールバック関数を登録し、コールバック関数の中で再度この関数を呼び出して Read を行う必要があります。

	注意
	この関数は、内部で `SFBSource::Read` 関数を呼び出します。

	前提条件
	この関数を呼び出す前に、 `SFXSource::OpenSFXSource::Open` 関数を呼び出してソースを登録する必要があります。

参照

SFXSource::OpenSFXSource::Open | SFXSource::ScheduleRead | SFBSource::Read | BREW API ISOURCE_Read

SFXSource::ScheduleRead

Read（ストリームを使用しないソースからのデータ読み込み）をスケジュールします。

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

戻り値

成功したとき: SFERR_NO_ERROR
ソースが開いていないとき、または「Read スケジュール中の状態」のとき: SFERR_INVALID_STATE

解説

この関数は、 Read（ストリームを使用しないソースからのデータ読み込み）をスケジュールします。

具体的には、 SFXSource::Read 関数による Read を行うコールバック関数を登録します。登録されたコールバック関数は、Read が可能になると BREW AEE により呼び出されます。

コールバック関数が呼び出されるまでは、「Read スケジュール中の状態」になります。コールバック関数が呼び出されると、この関数を呼び出す直前の状態(ソースが開いている状態)に戻ります。

コールバック関数が呼び出される前に、 SFXSource::Cancel 関数を呼び出すと、 Read（ストリームを使用しないソースからのデータ読み込み）のスケジュールはキャンセルされ、この関数を呼び出す直前の状態(ソースが開いている状態)に戻ります。

なお、この関数の戻り値がエラー（SFERR_NO_ERROR 以外の値）の場合、コールバック関数は呼び出されません。

※ SFXSource::Read 関数の戻り値が ISOURCE_WAIT である場合、この関数を使用してコールバック関数を登録し、再び Read（ストリームを使用しないソースからのデータ読み込み）を試みます。

	注意
	この関数は、内部で `SFBSource::Readable` 関数を呼び出します。

前提条件

	前提条件
この関数を呼び出す前に、このソースは `SFXSource::OpenSFXSource::Open` 関数を呼び出して開いている必要があります。また、既に Read がスケジュールされている場合は、SFERR_INVALID_STATE エラーが返ります。

この関数を呼び出す前に、このソースは SFXSource::OpenSFXSource::Open 関数を呼び出して開いている必要があります。

また、既に Read がスケジュールされている場合は、SFERR_INVALID_STATE エラーが返ります。

参照

SFXSource::ScheduleWrite

【現在、この関数は使えません。】

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

戻り値

SFERR_UNSUPPORTED

解説

【現在、この関数は使えません。】

参照

SFXStorage::CallbackSPP

SFXSource::Write

【現在、この関数は使えません。】

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

戻り値

SFERR_UNSUPPORTED

解説

【現在、この関数は使えません。】