IActionProgress
COM公式ドキュメント
進捗を伴う処理が継承できる抽象基底クラスを表します。
解説(Remarks)
このクラスはインスタンス化できない抽象クラスです。派生クラスが進捗コールバックを実装するために利用できるフレームワークを提供します。このコールバックは、アプリケーションが処理の進捗を UI に報告するために使用できます。ここで言う「Actions(処理)」とは、ファイルのダウンロードやコピーなど、相当の時間がかかる可能性があり、その間に視覚的な進捗表示が適切となる操作を指します。
アプリケーションが通常このインターフェイスを実装することはありません。処理中にユーザーが操作する機能の多くは、IActionProgress を実装し進捗をダイアログ ボックスに表示する CProgressDialog クラス(CLSID_ProgressDialog)によって提供されます。ダイアログ ボックス以外の仕組みを必要とするソリューションの場合、IActionProgress を使用して基本的な進捗インジケーター機能を提供できます。
実装後、クラスは処理の開始時に IActionProgress::Begin を呼び出す必要があります。定期的に IActionProgress::UpdateProgress を呼び出して進捗情報で UI を更新し、詳細なテキスト情報は IActionProgress::UpdateText を呼び出して UI に伝える必要があります。キャンセル要求を処理するには IActionProgress::QueryCancel および IActionProgress::ResetCancel を呼び出す必要があります。処理が終了したら、IActionProgress::End を呼び出す必要があります。
メソッド 6
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
進捗をユーザーに表示する必要のある処理が開始されたときに呼び出されます。
| action | SPACTION | in | 実行される処理。指定可能な値の一覧については SPACTION を参照してください。 |
| flags | DWORD | in | 特定の UI 操作の有効化または無効化を要求する省略可能なフラグ。指定可能な値の一覧については SPBEGINF を参照してください。 |
戻り値
型: HRESULT
成功した場合は S_OK を、それ以外の場合はエラー値を返します。
解説(Remarks)
このメソッドは処理の開始時に呼び出す必要があります。action および flags の値は、ユーザーに表示する UI をどのように描画するか、または処理に関連する特定のユーザー操作をどのように解釈もしくはフィルタリングするかを決定するために使用できます。処理が完了したら、IActionProgress::End を呼び出す必要があります。
処理の進捗を UI に更新します。
| ulCompleted | ULONGLONG | in | 完了した処理の量。 |
| ulTotal | ULONGLONG | in | 処理の総量。 |
戻り値
型: HRESULT
成功した場合は S_OK を、それ以外の場合はエラー値を返します。
解説(Remarks)
このメソッドは処理の進捗を更新するために定期的に呼び出す必要があります。実装クラスはこれらの値を任意の方法で解釈できますが、意味のある進捗量を判断するには ulCompleted と ulTotal の値を相対的に解釈する必要があります。多くの場合、パーセンテージが求められます。その場合は ulCompleted の値を ulTotal で除算し、その結果に 100 を乗算します。
処理に関連付けられた説明テキストが変更される場合に呼び出されます。
| sptext | SPTEXT | in | 表示するテキストの種類を指定する値。指定可能な値については SPTEXT を参照してください。 |
| pszText | LPWSTR | in | 表示するワイド文字列へのポインター。 |
| fMayCompact | BOOL | in | 画面上の利用可能なスペースに収まるようにテキスト文字列を短縮することを許可するかどうかを指定する値。 |
戻り値
型: HRESULT
成功した場合は S_OK を、それ以外の場合はエラー値を返します。
解説(Remarks)
このメソッドを実装するクラスは、実行される処理と進捗をユーザーに表示する UI の文脈において、sptext および fMayCompact の値を解釈する必要があります。sptext の値は、変更可能なテキストの行を区別するために使用できます。多くの場合、fMayCompact の値は、画面スペースを節約するためにテキスト文字列を省略記号(...)で切り詰められるかどうかを指します。
処理がキャンセルされているかどうかに関する情報を提供します。
| pfCancelled | BOOL* | out | 処理がキャンセルされているかどうかを指定する BOOL 値への参照。 |
戻り値
型: HRESULT
成功した場合は S_OK を、それ以外の場合はエラー値を返します。
解説(Remarks)
処理がキャンセルされたかどうかをプロセスが知る必要がある場合に、このメソッドを呼び出します。このメソッドを実装するには、実装クラスが内部または外部のフラグを照会してこの情報を取得し、その結果を pfCancelled の値に格納する必要があります。
キャンセルの完了後に進捗ダイアログをリセットします。
戻り値
型: HRESULT
成功した場合は S_OK を、それ以外の場合はエラー値を返します。
解説(Remarks)
このメソッドは、キャンセルが完了したときに呼び出されます。大規模な計算やファイル操作を伴う処理のキャンセルでは、通常ユーザー入力を制限すべきです。呼び出し側のアプリケーションはこのメソッドを使用して、キャンセルが完了し UI がユーザーに制御を返すべきであることを進捗 UI に通知できます。
この進捗実装に関連付けられた処理が終了したことを示します。
戻り値
型: HRESULT
成功した場合は S_OK を、それ以外の場合はエラー値を返します。
解説(Remarks)
このメソッドは処理が完了したことを示し、実装クラスはクリーンアップを実行し、該当する場合は結果をユーザーに表示する必要があります。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IActionProgress "{49FF1173-EADC-446D-9285-156453A6431C}" #usecom global IActionProgress IID_IActionProgress "{}" #comfunc global IActionProgress_Begin 3 int,int #comfunc global IActionProgress_UpdateProgress 4 int64,int64 #comfunc global IActionProgress_UpdateText 5 int,wstr,int #comfunc global IActionProgress_QueryCancel 6 var #comfunc global IActionProgress_ResetCancel 7 #comfunc global IActionProgress_End 8 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。#define global IID_IActionProgress "{49FF1173-EADC-446D-9285-156453A6431C}" #usecom global IActionProgress IID_IActionProgress "{}" #comfunc global IActionProgress_Begin 3 int,int #comfunc global IActionProgress_UpdateProgress 4 int64,int64 #comfunc global IActionProgress_UpdateText 5 int,wstr,int #comfunc global IActionProgress_QueryCancel 6 sptr #comfunc global IActionProgress_ResetCancel 7 #comfunc global IActionProgress_End 8 ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。