IFillLockBytes
COM公式ドキュメント
IFillLockBytes インターフェイスを使用すると、ダウンロード用コードが構造化ストレージのバイト配列に対して非同期でデータを書き込めるようになります。
メソッド 4
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
FillAppend メソッドは、バイト配列の末尾に新しいバイトのブロックを書き込みます。
| pv | void* | in | 既存のバイト配列の末尾に追加するデータへのポインター。この操作でメモリリークやバッファオーバーランが発生する危険はありません。 |
| cb | DWORD | in | pv のサイズ(バイト単位)。 |
| pcbWritten | DWORD* | out | 正常に書き込まれたバイト数。 |
戻り値
この関数は、標準の戻り値 E_OUTOFMEMORY、E_UNEXPECTED、E_INVALIDARG、および E_FAIL をサポートします。
解説(Remarks)
FillAppend メソッドは、受信した順にバイト配列の末尾へバイトを書き込むシーケンシャルダウンロードに使用します。このメソッドは現在のバイト配列(たとえば lockbytes オブジェクト)のサイズを取得し、新しいデータブロックを配列の末尾に書き込みます。ダウンローダーは、各データブロックが利用可能になるたびにこのメソッドを呼び出してバイト配列に書き込みます。以降、複合ファイルの実装が ILockBytes::ReadAt を呼び出すと、利用可能なデータがあればそれを返し、現在データが利用できない場合は E_PENDING を返します。
FillAt メソッドは、バイト配列内の指定した位置に新しいデータブロックを書き込みます。
| ulOffset | ULONGLONG | in | バイト配列の先頭要素からのオフセット(バイト数で表します)。 |
| pv | void* | in | uIOffset で指定された位置に書き込むデータへのポインター。 |
| cb | DWORD | in | pv のサイズ(バイト単位)。 |
| pcbWritten | DWORD* | out | 正常に書き込まれたバイト数。 |
戻り値
この関数は、標準の戻り値 E_OUTOFMEMORY、E_UNEXPECTED、E_INVALIDARG、および E_FAIL に加えて、以下をサポートします。
| 戻り値 | 説明 |
|---|---|
| E_NOTIMPL | バイト配列が FillAt メソッドをサポートしていません。 |
解説(Remarks)
FillAt メソッドは、非シーケンシャルダウンロード(たとえば HTTP のバイトレンジ要求)に使用します。非シーケンシャルダウンロードでは、呼び出し元がバイト配列内で各種データブロックを書き込む範囲を指定します。以降、複合ファイルの実装が ILockBytes::ReadAt を呼び出すと、その要求はバイト配列ラッパーオブジェクト自身の ILockBytes 実装によって基になるバイト配列へ渡されます。このメソッドは現在実装されておらず、E_NOTIMPL を返します。
SetFillSize メソッドは、バイト配列の想定サイズを設定します。
| ulSize | ULONGLONG | in | 以降の IFillLockBytes::FillAppend の呼び出しで埋められるバイト配列オブジェクトのサイズ(バイト単位)。 |
戻り値
この関数は、標準の戻り値 E_OUTOFMEMORY、E_UNEXPECTED、E_INVALIDARG、および E_FAIL をサポートします。
解説(Remarks)
SetFillSize が呼び出されていない場合、 IFillLockBytes::FillAppend または IFillLockBytes::FillAt でまだ書き込まれていないデータへアクセスしようとする ILockBytes::ReadAt の呼び出しは、新しいエラーメッセージ E_PENDING を返します。 SetFillSize が呼び出された後は、 SetFillSize で設定された現在のサイズを超えるデータへアクセスしようとする ReadAt の呼び出しは、E_PENDING ではなく E_FAIL を返します。
Terminate メソッドは、ダウンロードが成功または失敗のいずれかで終了したことをバイト配列に通知します。
| bCanceled | BOOL | in | ダウンロードが完了しました。TRUE の場合、ダウンロードは失敗して終了しました。FALSE の場合、ダウンロードは正常に終了しました。 |
戻り値
この関数は、標準の戻り値 E_OUTOFMEMORY、E_UNEXPECTED、E_INVALIDARG、および E_FAIL をサポートします。
解説(Remarks)
このメソッドが呼び出された後は、バイト配列は E_PENDING を返さなくなります。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IFillLockBytes "{99CAF010-415E-11CF-8814-00AA00B569F5}" #usecom global IFillLockBytes IID_IFillLockBytes "{}" #comfunc global IFillLockBytes_FillAppend 3 sptr,int,var #comfunc global IFillLockBytes_FillAt 4 int64,sptr,int,var #comfunc global IFillLockBytes_SetFillSize 5 int64 #comfunc global IFillLockBytes_Terminate 6 int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IFillLockBytes "{99CAF010-415E-11CF-8814-00AA00B569F5}" #usecom global IFillLockBytes IID_IFillLockBytes "{}" #comfunc global IFillLockBytes_FillAppend 3 sptr,int,sptr #comfunc global IFillLockBytes_FillAt 4 int64,sptr,int,sptr #comfunc global IFillLockBytes_SetFillSize 5 int64 #comfunc global IFillLockBytes_Terminate 6 int ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。