IProgressNotify
COM公式ドキュメント
ダウンロード操作の進行状況の変化に関する通知を、アプリケーションやその他のオブジェクトが受け取れるようにします。
メソッド 1
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
登録されたオブジェクトおよびアプリケーションに、ダウンロード操作の進行状況を通知します。
| dwProgressCurrent | DWORD | in | 利用可能なデータ量。 |
| dwProgressMaximum | DWORD | in | ダウンロードするデータの総量。 |
| fAccurate | BOOL | in | dwProgressCurrent と dwProgressMaximum の値の正確性を示します。これらの値は信頼できる(TRUE)か、信頼できない(FALSE)かのいずれかです。FALSE の値は、データの実際の位置や、まだダウンロードされていないデータ量を判定するための制御構造が利用できないことを示します。 |
| fOwner | BOOL | in | この OnProgress 呼び出しが操作のブロック動作を制御できるかどうかを示します。TRUE の場合、呼び出し元は OnProgress の戻り値を使用して、操作をブロック(STG_S_BLOCK)、再試行(STG_S_RETRYNOW)、または監視(STG_S_MONITORING)できます。FALSE の場合、OnProgress の戻り値はブロック動作に影響しません。 |
戻り値
このメソッドは、標準の戻り値である E_FAIL、E_INVALIDARG、E_OUTOFMEMORY、E_UNEXPECTED を返すことができるほか、以下の値を返すことができます。
| 戻り値 | 説明 |
|---|---|
| 呼び出し元は操作を直ちに再試行します。(この値は、コールバックルーチン内でブロックを行うアプリケーションで最も有用です。) | |
| 呼び出し元はダウンロードをブロックし、追加のデータが利用可能かどうかを判定するために必要に応じて呼び出しを再試行します。これは、接続ポイントにシンクが登録されていない場合の既定の動作です。 | |
| コールバックの受信側は、同じストリームに進行状況通知シンクを登録している他のオブジェクトやアプリケーションのいずれかに、ダウンロード処理の制御権を譲ります。これは、通知シンクが統計情報の収集のみを目的としている場合に有用です。 | |
| 現在データが利用できません。呼び出し元は、任意の間隔をおいて再試行します。非同期ストレージを非ブロックモードで動作させる場合、通知シンクはこの値を返します。 |
解説(Remarks)
シンクは、特定のストレージの任意のサブストレージまたはサブストリームによって継承されることがあります。シンクが登録されていない場合、要求されたデータが利用可能になるか、ダウンローダーによってダウンロードがキャンセルされるまで、スレッドはブロックされます。
複数のオブジェクトまたはアプリケーションが単一のストリームに進行状況通知シンクを登録している場合、そのうちの1つだけがダウンロードの動作を制御できます。ダウンロードの所有権は、ストレージまたはストリームに最初に登録したシンク、あるいは親ストレージから継承された可能性のあるアドバイズシンク(ストレージが ASYNC_MODE_COMPATIBILITY で作成された場合)に与えられます。
いずれのシンクも、現在の呼び出し元となっている接続ポイントに STG_S_MONITORING を返すことで、次の接続ポイントに制御権を譲ることができます。ある接続ポイントが(STG_S_BLOCK または STG_S_RETRYNOW を受け取ることで)制御権を取得した後は、OnProgress を呼び出す以降のすべての接続ポイントは fOwner を FALSE に設定します。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IProgressNotify "{A9D758A0-4617-11CF-95FC-00AA00680DB4}"
#usecom global IProgressNotify IID_IProgressNotify "{}"
#comfunc global IProgressNotify_OnProgress 3 int,int,int,int
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。