IFileOperation

Shell アイテムをコピー、移動、名前変更、作成、削除するためのメソッド、および進行状況ダイアログとエラーダイアログを提供するためのメソッドを公開します。このインターフェースは SHFileOperation 関数を置き換えるものです。

Shell アイテムは、ファイルやフォルダーといったファイルシステムオブジェクトだけでなく、仮想オブジェクトも含め、名前空間内の任意のオブジェクトになり得ます。IFileOperation の各メソッドのトピックでは、"アイテム" という用語を、任意の名前空間オブジェクトを総称的に指すために使用します。

IFileOperation は、従来の SHFileOperation 関数と比べて多くの利点があります。

• 文字列パスではなく IShellItem を使用してアイテムを識別します。SHFileOperation では、パス文字列と宛先文字列を、標準的な単一の null 文字ではなく 2 つの null 文字で終端する必要がありました。単一の null 文字自体は、文字列内で複数のパスを区切るために使用されていたためです。IShellItem を通じてアイテムを識別する方が堅牢で、プログラミングエラーが起こりにくくなります。また、仮想フォルダーなどの非ファイルシステムアイテムにもアクセスできます。1 回の操作で複数のアイテムを、文字列としてではなく IShellItemArray、IDataObject、または IEnumShellItems を通じてアクセスするコレクションとして渡すことができます。
• FormatMessage のような API と組み合わせた HRESULT 値による、より正確なエラー報告。SHFileOperation からの戻りコードは、誤解を招いたり不正確であったりすることがありました。
• 拡張性。Component Object Model (COM) インターフェースとして、IFileOperation は、特定のニーズに合わせてサードパーティによってその機能を拡張できます。ただし、これは非常にまれなケースであるべきです。Windows は、ほとんどのユーザーのニーズを満たすはずの IFileOperation の既定の実装を提供しています。
• より優れた進行状況フィードバック。個々のアイテムに対する特定の操作が開始および終了したときの通知や全体的な進行状況を含む、詳細な操作の進行状況を、操作中に受け取ることができます。SHFileOperation も進行状況 UI を提供していましたが、それほど詳細ではありませんでした。
• より多くの機能。SHFileOperation が提供するコピー、削除、移動、名前変更の機能に加えて、IFileOperation ではプロパティ値の適用や新しいアイテムの作成が可能です。
• 操作に対するより多くの制御。SHFileOperation が認識する操作フラグに加えて、IFileOperation::SetOperationFlags では拡張された操作オプションを指定する新しいフラグが認識されます。
• 1 回の呼び出しで異なる操作を実行できます。たとえば、一連のファイルを移動し、別のファイルをコピーし、フォルダーの名前を変更し、さらに別のアイテムにプロパティを適用するといったことを、すべて 1 回の操作で行えます。SHFileOperation では、コピー、移動、名前変更、削除のいずれか 1 つの操作しか一度に実行できませんでした。

このインターフェースを使用してファイル操作を行うには、一連の呼び出しを行う必要があります。

1. 省略可能。Advise および Unadvise を通じて、進行状況および エラー通知のためのイベントシンクを設定します。
2. 必要に応じて以下を使用して操作の状態を設定します。
   • SetOperationFlags
   • SetOwnerWindow
   • SetProgressDialog
   • SetProgressMessage
   • SetProperties
3. 必要に応じて以下を使用して、どのアイテムに対してどの操作を実行するかを指定します。
   • ApplyPropertiesToItem
   • ApplyPropertiesToItems
   • CopyItem
   • CopyItems
   • DeleteItem
   • DeleteItems
   • MoveItem
   • MoveItems
   • NewItem
   • RenameItem
   • RenameItems
4. PerformOperations を呼び出して操作を実行します。

IFileOperation は、シングルスレッドアパートメント (STA) の状況でのみ適用できます。マルチスレッドアパートメント (MTA) の状況では使用できません。MTA の場合は、引き続き SHFileOperation を使用する必要があります。

IFileOperation の拡張を示す完全なサンプルは、Windows Software Development Kit (SDK) に含まれています。既定のインストールでは、%ProgramFiles%\Microsoft SDKs\Windows\v6.0\Samples\WinUI\Shell\AppPlatform\FileOperations にあります。

すべての操作に対して、ハンドラーが状態およびエラー情報を提供できるようにします。

型: HRESULT

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

いくつかの個別のメソッドには、ここで設定したものとは重複する独自の進行状況シンクを宣言する機能があります。これらは、特定の操作についてのみ進行状況とエラー情報を受け取りたい場合に使用します。

IFileOperation::Advise を通じて以前に確立されたアドバイザリ接続を終了します。

型: HRESULT

ここに記載されている値以外の値は失敗を示します。

戻りコード	説明
S_OK	接続が正常に終了しました。
CONNECT_E_NOCONNECTION	dwCookie の値が有効な接続を表していません。

現在の操作のパラメーターを設定します。

型: HRESULT

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

コピー、削除、名前変更など、実行される操作のパラメーターを定義するために、IFileOperation::PerformOperations を呼び出す前にこれらのフラグを設定します。

実装されていません。(IFileOperation.SetProgressMessage)

型: HRESULT

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

操作の進行状況を表示するために使用されるダイアログボックスを指定します。

型: HRESULT

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

アイテムに設定するプロパティと値のセットを宣言します。

型: HRESULT

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

このメソッドは新しいプロパティ値を設定するのではなく、単にそれらを宣言するだけです。1 つのアイテムまたはアイテムのグループにプロパティ値を設定するには、少なくとも以下に詳述する一連の呼び出しを行う必要があります。

1. IFileOperation::SetProperties を呼び出して、設定する特定のプロパティとその新しい値を宣言します。
2. IFileOperation::ApplyPropertiesToItem または IFileOperation::ApplyPropertiesToItems を呼び出して、プロパティを設定するアイテムを宣言します。
3. IFileOperation::PerformOperations を呼び出して、アイテムにプロパティを適用します。

進行状況ウィンドウおよびダイアログウィンドウの親ウィンドウまたはオーナーウィンドウを設定します。

型: HRESULT

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

プロパティ値を設定する単一のアイテムを宣言します。

型: HRESULT

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

このメソッドはアイテムにプロパティを適用するのではなく、単にアイテムを宣言するだけです。アイテムにプロパティ値を設定するには、少なくとも以下に詳述する一連の呼び出しを行う必要があります。

1. IFileOperation::SetProperties を呼び出して、設定する特定のプロパティとその新しい値を宣言します。
2. IFileOperation::ApplyPropertiesToItem を呼び出して、プロパティを設定するアイテムを宣言します。
3. IFileOperation::PerformOperations を呼び出して、アイテムにプロパティを適用します。

共通のプロパティ値のセットを適用するアイテムのセットを宣言します。

型: HRESULT

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

このメソッドはアイテムにプロパティを適用するのではなく、単にアイテムを宣言するだけです。アイテムのグループにプロパティ値を設定するには、少なくとも以下に詳述する一連の呼び出しを行う必要があります。

1. IFileOperation::SetProperties を呼び出して、設定する特定のプロパティとその新しい値を宣言します。
2. IFileOperation::ApplyPropertiesToItems を呼び出して、プロパティ値を設定するアイテムを宣言します。
3. IFileOperation::PerformOperations を呼び出して、アイテムにプロパティを適用します。

新しい表示名を付与する単一のアイテムを宣言します。

型: HRESULT

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

このメソッドはアイテムの名前を変更するのではなく、単に名前を変更するアイテムを宣言するだけです。オブジェクトの名前を変更するには、少なくとも以下に詳述する一連の呼び出しを行う必要があります。

1. IFileOperation::RenameItem を呼び出して新しい名前を宣言します。
2. IFileOperation::PerformOperations を呼び出して名前変更操作を開始します。

新しい表示名を付与するアイテムのセットを宣言します。すべてのアイテムに同じ名前が付けられます。

型: HRESULT

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

pUnkItems のコレクション内の複数のアイテムが同じフォルダー内にある場合、名前が変更されたファイルはそれらを区別するために括弧付きの番号が付加されます。たとえば、newfile(1).txt、newfile(2).txt、newfile(3).txt のようになります。

このメソッドはアイテムの名前を変更するのではなく、単に名前を変更するアイテムを宣言するだけです。オブジェクトのグループの名前を変更するには、少なくとも以下に詳述する一連の呼び出しを行う必要があります。

1. IFileOperation::RenameItems を呼び出して、ソースのファイルまたはフォルダーと新しい名前を宣言します。
2. IFileOperation::PerformOperations を呼び出して名前変更操作を開始します。

指定された宛先へ移動する単一のアイテムを宣言します。

型: HRESULT

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

このメソッドはアイテムを移動するのではなく、単に移動するアイテムを宣言するだけです。オブジェクトを移動するには、少なくとも以下に詳述する一連の呼び出しを行う必要があります。

1. IFileOperation::MoveItem を呼び出して、ソースアイテム、宛先フォルダー、宛先名を宣言します。
2. IFileOperation::PerformOperations を呼び出して移動操作を開始します。

指定された宛先へ移動するアイテムのセットを宣言します。

型: HRESULT

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

このメソッドはアイテムを移動するのではなく、単に移動するアイテムを宣言するだけです。アイテムのグループを移動するには、少なくとも以下に詳述する一連の呼び出しを行う必要があります。

1. IFileOperation::MoveItems を呼び出して、ソースのファイルまたはフォルダーと宛先フォルダーを宣言します。
2. IFileOperation::PerformOperations を呼び出して移動操作を開始します。

指定された宛先へコピーする単一のアイテムを宣言します。

型: HRESULT

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

このメソッドはアイテムをコピーするのではなく、単にコピーするアイテムを宣言するだけです。オブジェクトをコピーするには、少なくとも以下に詳述する一連の呼び出しを行う必要があります。

1. IFileOperation::CopyItem を呼び出して、ソースアイテム、宛先フォルダー、宛先名を宣言します。
2. IFileOperation::PerformOperations を呼び出してコピー操作を開始します。

例

次のサンプルコードは、このメソッドの実装例を示しています。

HRESULT CopyItem(__in PCWSTR pszSrcItem, __in PCWSTR pszDest, PCWSTR pszNewName)
{
    //
    // Initialize COM as STA.
    //
    HRESULT hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED | COINIT_DISABLE_OLE1DDE); 
    if (SUCCEEDED(hr))
    {
        IFileOperation *pfo;
  
        //
        // Create the IFileOperation interface 
        //
        hr = CoCreateInstance(CLSID_FileOperation, 
                              NULL, 
                              CLSCTX_ALL, 
                              IID_PPV_ARGS(&pfo));
        if (SUCCEEDED(hr))
        {
            //
            // Set the operation flags. Turn off all UI from being shown to the
            // user during the operation. This includes error, confirmation,
            // and progress dialogs.
            //
            hr = pfo->SetOperationFlags(FOF_NO_UI);
            if (SUCCEEDED(hr))
            {
                //
                // Create an IShellItem from the supplied source path.
                //
                IShellItem *psiFrom = NULL;
                hr = SHCreateItemFromParsingName(pszSrcItem, 
                                                 NULL, 
                                                 IID_PPV_ARGS(&psiFrom));
                if (SUCCEEDED(hr))
                {
                    IShellItem *psiTo = NULL;
  
                    if (NULL != pszDest)
                    {
                        //
                        // Create an IShellItem from the supplied 
                        // destination path.
                        //
                        hr = SHCreateItemFromParsingName(pszDest, 
                                                         NULL, 
                                                         IID_PPV_ARGS(&psiTo));
                    }
                    
                    if (SUCCEEDED(hr))
                    {
                        //
                        // Add the operation
                        //
                        hr = pfo->CopyItem(psiFrom, psiTo, pszNewName, NULL);

                        if (NULL != psiTo)
                        {
                            psiTo->Release();
                        }
                    }
                    
                    psiFrom->Release();
                }
                
                if (SUCCEEDED(hr))
                {
                    //
                    // Perform the operation to copy the file.
                    //
                    hr = pfo->PerformOperations();
                }        
            }
            
            //
            // Release the IFileOperation interface.
            //
            pfo->Release();
        }
  
        CoUninitialize();
    }
    return hr;
}

指定された宛先へコピーするアイテムのセットを宣言します。

型: HRESULT

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

このメソッドはアイテムをコピーするのではなく、単にコピーするアイテムを宣言するだけです。アイテムのグループをコピーするには、少なくとも以下に詳述する一連の呼び出しを行う必要があります。

1. IFileOperation::CopyItems を呼び出して、ソースアイテムと宛先フォルダーを宣言します。
2. IFileOperation::PerformOperations を呼び出してコピー操作を開始します。

削除する単一のアイテムを宣言します。

型: HRESULT

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

このメソッドはアイテムを削除するのではなく、単に削除するアイテムを宣言するだけです。アイテムを削除するには、少なくとも以下に詳述する一連の呼び出しを行う必要があります。

1. IFileOperation::DeleteItem を呼び出して、削除するファイルまたはフォルダーを宣言します。
2. IFileOperation::PerformOperations を呼び出して削除操作を開始します。

削除するアイテムのセットを宣言します。

型: HRESULT

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

このメソッドはアイテムを削除するのではなく、単に削除するアイテムを宣言するだけです。アイテムのグループを削除するには、少なくとも以下に詳述する一連の呼び出しを行う必要があります。

1. IFileOperation::DeleteItems を呼び出して、削除するファイルまたはフォルダーを宣言します。
2. IFileOperation::PerformOperations を呼び出して削除操作を開始します。

指定された場所に作成する新しいアイテムを宣言します。

型: HRESULT

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

このメソッドは新しいアイテムを作成するのではなく、単に作成するアイテムを宣言するだけです。新しいアイテムを作成するには、少なくとも以下に詳述する一連の呼び出しを行う必要があります。

1. IFileOperation::NewItem を呼び出して、新しいファイルまたはフォルダーの詳細を宣言します。
2. IFileOperation::PerformOperations を呼び出して新しいアイテムを作成します。

選択されたすべての操作を実行します。

型: HRESULT

成功した場合は S_OK を、それ以外の場合はエラー値を返します。操作がユーザーによってキャンセルされた場合でも、このメソッドは成功コードを返すことがあることに注意してください。この場合に該当するかどうかを判定するには GetAnyOperationsAborted メソッドを使用してください。

このメソッドは、それぞれの個別のメソッドを呼び出すことで以前に指定されたアクションを実行するために最後に呼び出されます。たとえば、RenameItem はアイテムの名前を変更するのではなく、単にパラメーターを設定するだけです。実際の名前変更は、PerformOperations を呼び出したときに行われます。

IFileOperation::PerformOperations の呼び出しによって開始されたファイル操作が、完了する前に停止されたかどうかを示す値を取得します。操作は、ユーザーの操作によって、またはシステムによって暗黙的に停止される可能性があります。

型: HRESULT

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

このメソッドは IFileOperation::PerformOperations が返った後に呼び出してください。

IFileOperation::PerformOperations が成功コードと失敗コードのどちらを返したかにかかわらず、IFileOperation::GetAnyOperationsAborted を呼び出す必要があります。操作がユーザーまたはシステムによって停止された場合でも、成功コードが返されることがあります。

このメソッドは、従来の関数 SHFileOperation で使用される SHFILEOPSTRUCT 構造体の fAnyOperationsAborted メンバーと同じ機能を提供します。

#define global IID_IFileOperation "{947AAB5F-0A5C-4C13-B4D6-4BF7836FC9F8}"
#usecom global IFileOperation IID_IFileOperation "{3AD05575-8857-4850-9277-11B85BDB8E09}"
#comfunc global IFileOperation_Advise                   3 sptr,var
#comfunc global IFileOperation_Unadvise                 4 int
#comfunc global IFileOperation_SetOperationFlags        5 int
#comfunc global IFileOperation_SetProgressMessage       6 wstr
#comfunc global IFileOperation_SetProgressDialog        7 sptr
#comfunc global IFileOperation_SetProperties            8 sptr
#comfunc global IFileOperation_SetOwnerWindow           9 sptr
#comfunc global IFileOperation_ApplyPropertiesToItem    10 sptr
#comfunc global IFileOperation_ApplyPropertiesToItems   11 sptr
#comfunc global IFileOperation_RenameItem               12 sptr,wstr,sptr
#comfunc global IFileOperation_RenameItems              13 sptr,wstr
#comfunc global IFileOperation_MoveItem                 14 sptr,sptr,wstr,sptr
#comfunc global IFileOperation_MoveItems                15 sptr,sptr
#comfunc global IFileOperation_CopyItem                 16 sptr,sptr,wstr,sptr
#comfunc global IFileOperation_CopyItems                17 sptr,sptr
#comfunc global IFileOperation_DeleteItem               18 sptr,sptr
#comfunc global IFileOperation_DeleteItems              19 sptr
#comfunc global IFileOperation_NewItem                  20 sptr,int,wstr,wstr,sptr
#comfunc global IFileOperation_PerformOperations        21
#comfunc global IFileOperation_GetAnyOperationsAborted  22 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※#usecom 末尾は CoCreateInstance 用のクラスID(コクラスCLSID, SDKから自動取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※ハンドル/void*等の不透明ポインタは IronHSP では intptr 指定が可能。