IFileOperationProgressSink

IFileOperation を呼び出す側が、そのインターフェイスを通じて実行している操作の詳細を監視するために使用する、高機能な通知システムを提供するメソッドを公開します。

実装するタイミング

アプリケーションは IFileOperationProgressSink を自身で実装する必要があります。Windows は既定の実装を提供しません。

使用するタイミング

IFileOperationProgressSink は、本質的に特定のイベントに対するハンドラーです。通常、その時点で処理されている具体的な処理に関する情報（ファイル名、コピー元とコピー先、コピー先での項目の新しい名前など）を表示するために使用されます。Post 系メソッドは操作の各部分の HRESULT を受け取るため、呼び出し側は処理が失敗した場合にどこで失敗したかを具体的に特定できます。IFileOperation のメソッドのパラメーター値は、適切な IFileOperationProgressSink のメソッドに渡されるため、それらのメソッドは同じ情報にアクセスできます。

IFileOperation の呼び出しに IFileOperationProgressSink の実装をアタッチするには、次の 2 つの方法があります。

• IFileOperation の呼び出しで実行されるすべての操作について通知を受け取るには、IFileOperation::Advise メソッドを使用します。
• 特定の操作の進行状況のみについて通知を受け取るには、IFileOperationProgressSink を次の個別の IFileOperation メソッドの 1 つ以上に渡します。
  • CopyItem
  • DeleteItem
  • MoveItem
  • NewItem
  • RenameItem

Advise を呼び出す場合、IFileOperationProgressSink を特定の IFileOperation メソッドに渡す必要はありません。そのようにすると IFileOperationProgressSink のメソッドが重複して呼び出され、通知も重複するためです。

選択したメソッドにのみ IFileOperationProgressSink を渡す場合、それらすべてに対して同じ IFileOperationProgressSink のインスタンスを使用できます。

例

次の例では、Advise メソッドを呼び出して、IFileOperation のインスタンスに IFileOperationProgressSink を渡します。

IFileOperation *pfo;
CoCreateInstance(CLSID_FileOperation, NULL, CLSCTX_ALL, IID_IFileOperation, (void **)&m_pFO)
HRESULT hr = SHCreateFileOperation(hwnd, 0, IID_PPV_ARGS(&pfo));
if (SUCCEEDED(hr))
{
    // Advise to get notifications
    DWORD dwCookie;
    hr = pfo->Advise(SAFECAST(this, IFileOperationProgressSink*), &dwCookie);
}

個々のファイル操作が実行される前に、呼び出し側が実装したアクションを実行します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

StartOperations は、PerformOperations の後に呼び出される IFileOperationProgressSink メソッドのうち、最初に呼び出されるものです。ファイル操作が開始される前に必要なセットアップや初期化を行うために使用できます。

IFileOperation の呼び出しによって実行される最後の操作が完了した後に、呼び出し側が実装したアクションを実行します。

型: HRESULT

使用されません。

各項目の名前変更処理が始まる前に、呼び出し側が実装したアクションを実行します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。エラー値の場合、名前変更操作および IFileOperation の呼び出しによって保留されている以降のすべての操作がキャンセルされます。

各項目の名前変更処理が完了した後に、呼び出し側が実装したアクションを実行します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。エラー値の場合、IFileOperation の呼び出しによって保留されている以降のすべての操作がキャンセルされます。

各項目の移動処理が始まる前に、呼び出し側が実装したアクションを実行します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。エラー値の場合、移動操作および IFileOperation の呼び出しによって保留されている以降のすべての操作がキャンセルされます。

各項目の移動処理が完了した後に、呼び出し側が実装したアクションを実行します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。エラー値の場合、IFileOperation の呼び出しによって保留されている以降のすべての操作がキャンセルされます。

各項目のコピー処理が始まる前に、呼び出し側が実装したアクションを実行します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。エラー値の場合、コピー操作および IFileOperation の呼び出しによって保留されている以降のすべての操作がキャンセルされます。

各項目のコピー処理が完了した後に、呼び出し側が実装したアクションを実行します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。エラー値の場合、IFileOperation の呼び出しによって保留されている以降のすべての操作がキャンセルされます。

各項目の削除処理が始まる前に、呼び出し側が実装したアクションを実行します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。エラー値の場合、削除操作および IFileOperation の呼び出しによって保留されている以降のすべての操作がキャンセルされます。

各項目の削除処理が完了した後に、呼び出し側が実装したアクションを実行します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。エラー値の場合、IFileOperation の呼び出しによって保留されている以降のすべての操作がキャンセルされます。

新しい項目を作成する処理が始まる前に、呼び出し側が実装したアクションを実行します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。エラー値の場合、この操作および IFileOperation の呼び出しによって保留されている以降のすべての操作がキャンセルされます。

新しい項目が作成された後に、呼び出し側が実装したアクションを実行します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。エラー値の場合、IFileOperation の呼び出しによって保留されている以降のすべての操作がキャンセルされます。

現在完了している作業量を、総作業量との関係で見積もった値を提供します。

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

iWorkTotal と iWorkSoFar の値は、実行すべき作業量とその完了度を表す「ポイント」または見積もりです。特定の単位で指定されるものではありませんが、処理全体にかかる時間におおよそ比例するようにします。たとえば、1 つの小さなファイルのコピーを 2 ポイント、大きなファイルを 10 ポイントと見なすことができます。5 つの小さなファイルと 1 つの大きなファイルをコピーする操作を実行しているプロセスが、小さなファイルのうち 4 つを完了した場合、iWorkSoFar は 8 ポイント（4 × 2 = 8）、iWorkTotal は 20 ポイント（5 × 2 + 10 = 20）となり、見積もりは 20 ポイント中 8 ポイント（つまり 40%）完了となります。

サポートされていません。(IFileOperationProgressSink.ResetTimer)

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

このメソッドは E_NOTIMPL ではなく S_OK を返す必要があります。

サポートされていません。(IFileOperationProgressSink.PauseTimer)

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

このメソッドは E_NOTIMPL ではなく S_OK を返す必要があります。

サポートされていません。(IFileOperationProgressSink.ResumeTimer)

型: HRESULT

このメソッドが成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

このメソッドは E_NOTIMPL ではなく S_OK を返す必要があります。

#define global IID_IFileOperationProgressSink "{04B0F1A7-9490-44BC-96E1-4296A31252E2}"
#usecom global IFileOperationProgressSink IID_IFileOperationProgressSink "{}"
#comfunc global IFileOperationProgressSink_StartOperations   3
#comfunc global IFileOperationProgressSink_FinishOperations  4 int
#comfunc global IFileOperationProgressSink_PreRenameItem     5 int,sptr,wstr
#comfunc global IFileOperationProgressSink_PostRenameItem    6 int,sptr,wstr,int,sptr
#comfunc global IFileOperationProgressSink_PreMoveItem       7 int,sptr,sptr,wstr
#comfunc global IFileOperationProgressSink_PostMoveItem      8 int,sptr,sptr,wstr,int,sptr
#comfunc global IFileOperationProgressSink_PreCopyItem       9 int,sptr,sptr,wstr
#comfunc global IFileOperationProgressSink_PostCopyItem      10 int,sptr,sptr,wstr,int,sptr
#comfunc global IFileOperationProgressSink_PreDeleteItem     11 int,sptr
#comfunc global IFileOperationProgressSink_PostDeleteItem    12 int,sptr,int,sptr
#comfunc global IFileOperationProgressSink_PreNewItem        13 int,sptr,wstr
#comfunc global IFileOperationProgressSink_PostNewItem       14 int,sptr,wstr,wstr,int,int,sptr
#comfunc global IFileOperationProgressSink_UpdateProgress    15 int,int
#comfunc global IFileOperationProgressSink_ResetTimer        16
#comfunc global IFileOperationProgressSink_PauseTimer        17
#comfunc global IFileOperationProgressSink_ResumeTimer       18
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。