IEmptyVolumeCache
COM公式ドキュメント
ディスククリーンアップマネージャーがディスククリーンアップハンドラーと通信するために使用します。マネージャーがハンドラーに情報を要求したり、スキャンやパージの開始といったイベントを通知したりできるメソッドを公開します。
解説(Remarks)
このインターフェイスは、Windows 98 上で動作するディスククリーンアップハンドラーによって実装される必要があります。Windows 2000 上で動作するハンドラーは、あわせて IEmptyVolumeCache2 も公開する必要があります。
メソッド 5
vtbl = vtable インデックス(0始まり)。HSP等からCOMメソッドをインデックス指定で呼ぶ際に使用します。0〜2 は IUnknown。
指定されたレジストリキーの下に格納されている情報に基づいて、ディスククリーンアップハンドラーを初期化します。
| hkRegKey | HKEY | in | ハンドラーオブジェクトに関する情報を保持するレジストリキーへのハンドルです。 |
| pcwszVolume | LPWSTR | in | ボリュームのルートを表す、null 終端の Unicode 文字列へのポインターです。例: "C:"。 |
| ppwszDisplayName | LPWSTR* | out | ディスククリーンアップマネージャーのハンドラー一覧に表示される名前を格納する、null 終端の Unicode 文字列へのポインターです。値が割り当てられない場合は、レジストリの値が使用されます。 |
| ppwszDescription | LPWSTR* | out | このオブジェクトがディスククリーンアップマネージャーの利用可能なディスククリーンアップハンドラー一覧から選択されたときに表示される、null 終端の Unicode 文字列へのポインターです。値が割り当てられない場合は、レジストリの値が使用されます。 |
| pdwFlags | EMPTY_VOLUME_CACHE_FLAGS* | out | ハンドラーへ情報を渡し、またハンドラーからディスククリーンアップマネージャーへ情報を戻すために使用されるフラグです。 次のフラグをオブジェクトへ渡すことができます:EVCF_OUTOFDISKSPACEこのフラグが設定されている場合、ユーザーのドライブのディスク空き容量が不足しています。このフラグを受け取った場合、ハンドラーはパフォーマンスの低下を伴ってでも、積極的にディスク空き容量を解放するべきです。ただしハンドラーは、アプリケーションの失敗やユーザーのデータ損失を引き起こすようなファイルを削除してはなりません。 EVCF_SETTINGSMODEディスククリーンアップマネージャーがスケジュールに従って実行されている場合、このフラグが設定されます。ppwszDisplayName および ppwszDescription の各パラメーターに値を割り当てる必要があります。このフラグが設定されている場合、ディスククリーンアップマネージャーは IEmptyVolumeCache::GetSpaceUsed、IEmptyVolumeCache::Purge、IEmptyVolumeCache::ShowProperties を呼び出しません。IEmptyVolumeCache::Purge が呼び出されないため、クリーンアップは IEmptyVolumeCache::Initialize で処理する必要があります。ハンドラーは pcwszVolume パラメーターを無視し、どのドライブ上にあるかにかかわらず不要なファイルをすべてクリーンアップするべきです。ユーザーからのフィードバックを得る機会がないため、クリーンアップしても極めて安全なファイルのみを対象とするべきです。 次のフラグはハンドラーからディスククリーンアップマネージャーへ戻すことができます:EVCF_DONTSHOWIFZERO削除するファイルがない場合にこのフラグを設定します。IEmptyVolumeCache::GetSpaceUsed が呼び出されたときに pdwSpaceUsed パラメーターを 0 に設定すると、ディスククリーンアップマネージャーはそのハンドラーを一覧から除外します。 EVCF_ENABLEBYDEFAULTクリーンアップマネージャーの一覧で、そのハンドラーを既定でチェック状態にするにはこのフラグを設定します。ユーザーがハンドラーのチェックボックスをオフにしない限り、ディスククリーンアップユーティリティが実行されるたびにハンドラーが実行されます。チェックボックスがオフにされると、ユーザーが再度選択するまでハンドラーは実行されません。 EVCF_ENABLEBYDEFAULT_AUTOスケジュールされたクリーンアップ中にハンドラーを自動的に実行させるにはこのフラグを設定します。このフラグは、ファイルの削除が低リスクである場合にのみ設定するべきです。EVCF_ENABLEBYDEFAULT と同様に、ユーザーはディスククリーンアップマネージャーの一覧でハンドラーのチェックボックスをオフにすることで、そのハンドラーを実行しないよう選択できます。 EVCF_HASSETTINGSハンドラーが UI を表示できることを示すにはこのフラグを設定します。単純な UI の例としては、削除可能なファイルを表示し、ユーザーがどのファイルを削除するかを選択できるリストボックスがあります。ディスククリーンアップマネージャーは、クリーンアップハンドラーの説明の下にボタンを表示します。ユーザーはこのボタンをクリックして UI を要求します。既定のボタンのテキストは "設定" ですが、ハンドラーはレジストリキーに AdvancedButtonText 値を設定することで別のテキストを指定できます。 EVCF_REMOVEFROMLISTディスククリーンアップマネージャーの一覧からハンドラーを削除するにはこのフラグを設定します。すべてのレジストリ情報が削除され、キーとその値が復元されるまでハンドラーを再度実行することはできません。このフラグは主に一度限りのクリーンアップ操作に使用されます。 |
戻り値
型: HRESULT
このメソッドは次のいずれかの値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| 成功しました。 | |
| 削除するファイルがありません。 | |
| クリーンアップ操作が途中で終了しました。 | |
| クリーンアップ操作が失敗しました。 |
解説(Remarks)
このメソッドは Windows 98 のディスククリーンアップマネージャーによって使用されます。Windows 2000 では、IEmptyVolumeCache2 がエクスポートする InitializeEx メソッドが使用されます。
ppwszDisplayName および ppwszDescription を通じて返される文字列のメモリを割り当てるには、CoTaskMemAlloc を使用してください。ディスククリーンアップマネージャーは、不要になった時点でそのメモリを解放します。
ディスククリーンアップハンドラーが解放できるディスク領域の量を要求します。
| pdwlSpaceUsed | ULONGLONG* | out | ハンドラーが解放できるディスク領域の量(バイト単位)です。この値は、ディスククリーンアップマネージャーの一覧で、ハンドラーのチェックボックスの右側に表示されます。解放できるディスク領域の量が不明であることを示すには、このパラメーターを -1 に設定してください。その場合 "???MB" と表示されます。Initialize が呼び出されたときに EVCF_DONTSHOWIFZERO フラグを設定していた場合、pdwSpaceUsed を 0 に設定すると、ディスククリーンアップマネージャーにそのハンドラーを一覧から除外するよう通知します。 |
| picb | IEmptyVolumeCacheCallBack* | in | ディスククリーンアップマネージャーの IEmptyVolumeCacheCallback インターフェイスへのポインターです。このポインターを使用して、そのインターフェイスの ScanProgress メソッドを呼び出し、操作の進行状況を報告できます。 |
戻り値
型: HRESULT
このメソッドは次のいずれかの値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| 成功しました。 | |
| ハンドラーが解放可能なディスク領域の量を計算しようとした際にエラーが発生しました。 | |
| スキャン操作が途中で終了しました。この値は通常、ScanProgress の呼び出しが E_ABORT を返したときに返されます。この戻り値は、ユーザーがディスククリーンアップマネージャーの キャンセル ボタンをクリックして操作をキャンセルしたことを示します。 |
解説(Remarks)
このメソッドがディスククリーンアップマネージャーによって呼び出されると、ハンドラーは自身のファイルのスキャンを開始し、どのファイルを削除できるか、およびどれだけのディスク領域が解放されるかを判断するべきです。ハンドラーは、特にスキャンに時間がかかる場合は、IEmptyVolumeCache::ScanProgress を定期的に呼び出して、スキャンの進行状況をユーザーに知らせるべきです。このメソッドを頻繁に呼び出すことで、ハンドラーはユーザーが操作をキャンセルしたかどうかを判断することもできます。ScanProgress が E_ABORT を返した場合、ユーザーはスキャンをキャンセルしています。ハンドラーはただちにスキャンを停止し、E_ABORT を返すべきです。
pdwSpaceUsed パラメーターを -1 に設定するのは、最後の手段としてのみ行うべきです。どれだけの領域が解放されるかがわからなければ、ハンドラーはユーザーにとって限られた価値しか持ちません。
不要なファイルの削除を開始するようハンドラーに通知します。
| dwlSpaceToFree | ULONGLONG | in | ハンドラーが解放するべきディスク領域の量です。このパラメーターが -1 に設定されている場合、ハンドラーは自身のすべてのファイルを削除するべきです。 |
| picb | IEmptyVolumeCacheCallBack* | in | ディスククリーンアップマネージャーの IEmptyVolumeCacheCallBack インターフェイスへのポインターです。このポインターを使用して、そのインターフェイスの PurgeProgress メソッドを呼び出し、操作の進行状況を報告できます。 |
戻り値
型: HRESULT
このメソッドは次のいずれかの値を返すことがあります。
| 戻り値 | 説明 |
|---|---|
| 成功しました。 | |
| 操作が途中で終了しました。この値は通常、PurgeProgress が E_ABORT を返したときに返されます。これは通常、ユーザーがディスククリーンアップマネージャーの キャンセル ボタンをクリックして操作をキャンセルしたときに発生します。 |
解説(Remarks)
Windows 98 では、dwSpaceToFree パラメーターは常に、IEmptyVolumeCache::GetSpaceUsed が呼び出されたときにハンドラーが指定した値に設定されます。
一般に、ハンドラーは単純に保ち、この関数が呼び出されたときに自身のすべてのファイルを削除するべきです。ファイルの一部のみを削除することに大きなパフォーマンス上の利点がある場合、ハンドラーは ShowProperties メソッドを実装するべきです。このメソッドが呼び出されると、ユーザーが削除するファイルを選択できる UI が表示されます。
UI を表示するようハンドラーに通知します。
| hwnd | HWND | in | UI を表示する際に使用する親ウィンドウです。 |
戻り値
解説(Remarks)
ハンドラーは UI を表示できます。これは通常、どのファイルをどのようにクリーンアップするかをユーザーが選択できるようにするために使用されます。そのためには、Initialize が呼び出されたときに、ハンドラーが pdwFlags パラメーターに EVCF_HASSETTINGS フラグを設定します。するとディスククリーンアップマネージャーは 設定 ボタンを表示します。そのボタンがクリックされると、ディスククリーンアップマネージャーは ShowProperties を呼び出して、UI を表示するようハンドラーに通知します。
ディスククリーンアップマネージャーがシャットダウンしようとしていることをハンドラーに通知します。
| pdwFlags | EMPTY_VOLUME_CACHE_FLAGS* | out | ディスククリーンアップマネージャーへ情報を戻すために設定できるフラグです。次の値を取ることができます。 EVCF_REMOVEFROMLISTこのフラグが設定されている場合、ディスククリーンアップマネージャーはハンドラーのレジストリサブキーを削除します。 |
戻り値
解説(Remarks)
EVCF_REMOVEFROMLIST フラグが設定されている場合、レジストリエントリが再確立されない限り、ハンドラーは再度実行されません。このフラグは通常、一度だけ実行されるハンドラーに使用されます。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)
HSP用 COM定義
#usecom / #comfunc によるHSPのCOM呼び出し定義。数字は vtbl インデックス(0始まり)。クラスIDが無い場合 #usecom の末尾は "{}"、ある場合は "{CLSID}"。
#define global IID_IEmptyVolumeCache "{8FCE5227-04DA-11D1-A004-00805F8ABE06}" #usecom global IEmptyVolumeCache IID_IEmptyVolumeCache "{}" #comfunc global IEmptyVolumeCache_Initialize 3 sptr,wstr,var,var,var #comfunc global IEmptyVolumeCache_GetSpaceUsed 4 var,sptr #comfunc global IEmptyVolumeCache_Purge 5 int64,sptr #comfunc global IEmptyVolumeCache_ShowProperties 6 sptr #comfunc global IEmptyVolumeCache_Deactivate 7 var ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。#define global IID_IEmptyVolumeCache "{8FCE5227-04DA-11D1-A004-00805F8ABE06}" #usecom global IEmptyVolumeCache IID_IEmptyVolumeCache "{}" #comfunc global IEmptyVolumeCache_Initialize 3 sptr,wstr,sptr,sptr,sptr #comfunc global IEmptyVolumeCache_GetSpaceUsed 4 sptr,sptr #comfunc global IEmptyVolumeCache_Purge 5 int64,sptr #comfunc global IEmptyVolumeCache_ShowProperties 6 sptr #comfunc global IEmptyVolumeCache_Deactivate 7 sptr ; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。 ; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。 ; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。 ; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。