ISequentialStream

ISequentialStream インターフェイスは、ストリームオブジェクトへの簡略化されたシーケンシャルアクセスをサポートします。IStream インターフェイスは、Read メソッドと Write メソッドを ISequentialStream から継承します。

現在のシークポインターの位置から、ストリームオブジェクトから指定したバイト数をメモリに読み込みます。

このメソッドは、次のいずれかの値を返すことがあります。

Return code	Description
S_OK	要求されたすべてのデータがストリームオブジェクトから正常に読み込まれました。cb で要求されたバイト数と、pcbRead で返されるバイト数が一致します。
S_FALSE	pcbRead で返される値が、cb で要求されたバイト数より小さくなっています。これはストリームの終端に達したことを示します。読み込まれたバイト数は、pv バッファーがどれだけ埋められたかを示します。
E_PENDING	非同期ストレージのみ: 読み込むデータの一部またはすべてが現在利用できません。
STG_E_ACCESSDENIED	呼び出し元がこのストリームオブジェクトを読み込むために必要な権限を持っていません。
STG_E_INVALIDPOINTER	ポインター値のいずれかが無効です。
STG_E_REVERTED	トランザクションツリー内の上位の revert 操作によって、オブジェクトが無効化されました。

このメソッドは、このストリームオブジェクトからメモリにバイトを読み込みます。ストリームオブジェクトは STGM_READ モードで開かれている必要があります。このメソッドは、実際に読み込まれたバイト数だけシークポインターを調整します。

実際に読み込まれたバイト数は、pcbRead パラメーターでも返されます。

呼び出し元への注意

読み込み操作中にエラーが発生した場合や、ストリームの終端に達した場合、実際に読み込まれるバイト数は要求したバイト数より少なくなることがあります。返されたバイト数は、常に要求したバイト数と比較する必要があります。返されたバイト数が要求したバイト数より少ない場合、通常は Read メソッドがストリームの終端を超えて読み込もうとしたことを意味します。

アプリケーションは、ストリーム終端の読み込み操作について、返されるエラーと S_OK の戻り値の両方を処理する必要があります。

現在のシークポインターの位置から、ストリームオブジェクトに指定したバイト数を書き込みます。

このメソッドは、次のいずれかの値を返すことがあります。

Return code	Description
S_OK	データがストリームオブジェクトに正常に書き込まれました。
E_PENDING	非同期ストレージのみ: 書き込むデータの一部またはすべてが現在利用できません。
STG_E_MEDIUMFULL	ストレージデバイスに空き領域がないため、書き込み操作が失敗しました。
STG_E_ACCESSDENIED	呼び出し元がこのストリームオブジェクトへの書き込みに必要な権限を持っていません。
STG_E_CANTSAVE	不適切なアクセスや領域不足以外の理由により、データを書き込むことができません。
STG_E_INVALIDPOINTER	ポインター値のいずれかが無効です。cb が 0 の場合でも、pv パラメーターには有効なポインターを指定する必要があります。
STG_E_REVERTED	トランザクションツリー内の上位の revert 操作によって、オブジェクトが無効化されました。
STG_E_WRITEFAULT	ディスクエラーにより書き込み操作が失敗しました。この値は、シンプルモード(STGM_SIMPLE フラグを使用)で開かれたストリームへの書き込みを試みた場合にも返されます。

ISequentialStream::Write は、指定したデータをストリームオブジェクトに書き込みます。シークポインターは、実際に書き込まれたバイト数だけ調整されます。実際に書き込まれたバイト数は、pcbWritten パラメーターで返されます。バイト数が 0 の場合、書き込み操作は何も行いません。

シークポインターが現在ストリームの終端を超えており、バイト数が 0 以外の場合、このメソッドはストリームのサイズをシークポインターまで拡張し、指定したバイトをシークポインターの位置から書き込みます。ストリームに書き込まれる埋め込みバイトは、特定の値には初期化されません。これは、MS-DOS FAT ファイルシステムにおけるファイル終端の動作と同じです。

バイト数が 0 で、シークポインターがストリームの終端を超えている場合、このメソッドはストリームをシークポインターまで拡張するための埋め込みバイトを作成しません。この場合、ストリームのサイズを拡張して埋め込みバイトを書き込むには、 IStream::SetSize メソッドを呼び出す必要があります。

pcbWritten パラメーターは、エラーが発生した場合でも値を持つことがあります。

COM が提供する実装では、ストリームオブジェクトはスパースではありません。埋め込みバイトは最終的にディスク上に割り当てられ、ストリームに割り当てられます。

#define global IID_ISequentialStream "{0C733A30-2A1C-11CE-ADE5-00AA0044773D}"
#usecom global ISequentialStream IID_ISequentialStream "{}"
#comfunc global ISequentialStream_Read   3 sptr,int,var
#comfunc global ISequentialStream_Write  4 sptr,int,var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。