SHFILEOPSTRUCTA 構造体 (shellapi.h)

  • [アーティクル]

SHFileOperation 関数がファイル操作の実行に使用する情報を格納します。

メモ Windows Vista では、この関数よりも IFileOperation インターフェイスを使用することをお勧めします。
 

構文

typedef struct _SHFILEOPSTRUCTA {
  HWND         hwnd;
  UINT         wFunc;
  PCZZSTR      pFrom;
  PCZZSTR      pTo;
  FILEOP_FLAGS fFlags;
  BOOL         fAnyOperationsAborted;
  LPVOID       hNameMappings;
  PCSTR        lpszProgressTitle;
} SHFILEOPSTRUCTA, *LPSHFILEOPSTRUCTA;

メンバー

hwnd

型: HWND

ファイル操作の状態に関する情報を表示するダイアログ ボックスのウィンドウ ハンドル。

wFunc

型: UINT

実行する操作を示す 値。 次のいずれかの値です。

FO_COPY

pFrom メンバーで指定されたファイルを、pTo メンバーで指定された場所にコピーします。

FO_DELETE

pFrom で指定されたファイルを削除します。

FO_MOVE

pFrom で指定されたファイルを pTo で指定された場所に移動します。

FO_RENAME

pFrom で指定されたファイルの名前を変更します。 このフラグを使用して、1 つの関数呼び出しで複数のファイルの名前を変更することはできません。 代わりに FO_MOVE を使用してください。

pFrom

種類: PCZZTSTR

メモ この文字列は、double-null で終わる必要があります。
 
1 つ以上のソース ファイル名へのポインター。 これらの名前は、予期しない結果を防ぐために完全修飾パスにする必要があります。

"*" などの標準 MS-DOS ワイルドカード文字は、ファイル名の位置 でのみ 使用できます。 文字列内の別の場所でワイルドカード文字を使用すると、予期しない結果が発生します。

このメンバーは単一の null で終わる文字列として宣言されていますが、実際には複数の null で区切られたファイル名を保持できるバッファーです。 各ファイル名は、1 つの NULL 文字で終わる。 最後のファイル名は、バッファーの末尾を示す 2 つの NULL 文字 ("\0\0") で終了します。

pTo

種類: PCZZTSTR

メモ この文字列は、double-null で終わる必要があります。
 
コピー先のファイルまたはディレクトリ名へのポインター。 このパラメーターを使用しない場合は 、NULL に設定する必要があります。 ワイルドカード文字は使用できません。 これらの使用は、予期しない結果につながります。

pFrom と同様に、pTo メンバーも二重 null で終わる文字列であり、ほとんど同じ方法で処理されます。 ただし、 pTo は 次の仕様を満たしている必要があります。

  • ワイルドカード文字はサポートされていません。
  • コピー操作と移動操作では、存在しない宛先ディレクトリを指定できます。 このような場合、システムはそれらを作成しようと試み、通常は新しいディレクトリを作成するかどうかをユーザーに確認するダイアログ ボックスを表示します。 このダイアログ ボックスを非表示にし、ディレクトリをサイレントに作成するには、fFlags で FOF_NOCONFIRMMKDIR フラグを設定します。
  • コピー操作と移動操作の場合、 fFlags メンバーが FOF_MULTIDESTFILESを指定している場合、バッファーには複数のコピー先ファイル名を含めることができます。
  • pFrom の場合と同じ方法で、複数の名前を pTo 文字列にパックします。
  • 完全修飾パスを使用します。 相対パスの使用は禁止されていませんが、予期しない結果になることがあります。

fFlags

種類: FILEOP_FLAGS

ファイル操作を制御するフラグ。 このメンバーは、次のフラグの組み合わせを受け取ることができます。

FOF_ALLOWUNDO

可能であれば、元に戻す情報を保持します。

Windows Vista より前のバージョンでは、元の操作を実行したのと同じプロセスからのみ操作を元に戻すことができます。

Windows Vista 以降のシステムでは、元に戻すのスコープはユーザー セッションです。 ユーザー セッションで実行されているプロセスは、別の操作を元に戻すことができます。 元に戻す状態は Explorer.exe プロセスに保持され、そのプロセスが実行されている限り、元に戻す関数を調整できます。

ソース ファイル パラメーターに完全修飾パスとファイル名が含まれていない場合、このフラグは無視されます。

FOF_CONFIRMMOUSE

使用されていません。

FOF_FILESONLY

ワイルドカード ファイル名 (.) が指定されている場合は、(フォルダーではなく) ファイルに対してのみ操作を実行します。

FOF_MULTIDESTFILES

pTo メンバーは、すべてのソース ファイルを格納する 1 つのディレクトリではなく、複数のコピー先ファイル (pFrom 内のソース ファイルごとに 1 つ) を指定します。

FOF_NOCONFIRMATION

表示されるすべてのダイアログ ボックス に対して、[はい ] を [すべて] に応答します。

FOF_NOCONFIRMMKDIR

操作で作成する必要がある場合は、新しいディレクトリの作成を確認するようにユーザーに依頼しないでください。

FOF_NO_CONNECTED_ELEMENTS

バージョン 5.0。 接続されているファイルをグループとして移動しないでください。 指定したファイルのみを移動します。

FOF_NOCOPYSECURITYATTRIBS

バージョン 4.71。 ファイルのセキュリティ属性をコピーしないでください。 コピー先ファイルは、新しいフォルダーのセキュリティ属性を受け取ります。

FOF_NOERRORUI

エラーが発生した場合は、ユーザーにダイアログを表示しません。

FOF_NORECURSEREPARSE

使用されていません。

FOF_NORECURSION

ローカル ディレクトリでのみ操作を実行します。 サブディレクトリに対して再帰的に操作しないでください。これは既定の動作です。

FOF_NO_UI

Windows Vista。 ユーザーに UI を表示せずに、操作をサイレントに実行します。 これは、FOF_SILENT |FOF_NOCONFIRMATION |FOF_NOERRORUI |FOF_NOCONFIRMMKDIR。

FOF_RENAMEONCOLLISION

移動操作、コピー操作、または名前変更操作で操作するファイルを、ターゲット名のファイルが既に宛先に存在する場合に指定します。

FOF_SILENT

[進行状況] ダイアログ ボックスは表示されません。

FOF_SIMPLEPROGRESS

進行状況ダイアログ ボックスを表示しますが、操作中の個々のファイル名は表示されません。

FOF_WANTMAPPINGHANDLE

FOF_RENAMEONCOLLISIONを指定し、ファイルの名前が変更された場合は、古い名前と新しい名前を含む名前マッピング オブジェクトを hNameMappings メンバーに割り当てます。 このオブジェクトは、不要になったとき に SHFreeNameMappings を使用して解放する必要があります。

FOF_WANTNUKEWARNING

バージョン 5.0。 ファイルがリサイクルされるのではなく、削除操作中に完全に破棄されている場合は、警告を送信します。 このフラグは、 FOF_NOCONFIRMATIONを部分的にオーバーライドします。

fAnyOperationsAborted

種類: BOOL

関数が戻ると、ファイル操作が完了する前に中止された場合、このメンバーには TRUE が含まれます。それ以外の場合は FALSE。 操作は、UI を介してユーザーが手動で中止することも、FOF_NOERRORUIまたはFOF_NOCONFIRMATIONフラグが設定されている場合はシステムによって自動的に中止することもできます。

hNameMappings

種類: LPVOID

関数が戻ると、このメンバーには、名前が変更されたファイルの古い名前と新しい名前を含む名前マッピング オブジェクトへのハンドルが含まれます。 このメンバーは、 fFlags メンバーに FOF_WANTMAPPINGHANDLE フラグが含まれている場合にのみ使用されます。 詳細については、「解説」を参照してください。

lpszProgressTitle

種類: PCTSTR

進行状況ダイアログ ボックスのタイトルへのポインター。 これは null で終わる文字列です。 このメンバーは、 fFlags に FOF_SIMPLEPROGRESS フラグが含まれている場合にのみ使用されます。

解説

大事な ソース パスと宛先パスが double-null で終了していることを確認する必要があります。 通常の文字列は、単一の null 文字で終わります。 その値をソース メンバーまたは変換先メンバーで渡した場合、関数は文字列の末尾に達したときに認識されず、ランダムな二重 null 値になるまでメモリ内で読み取りを続行します。 これにより、少なくともバッファー オーバーランが発生し、無関係なデータが意図せずに削除される可能性があります。
 
// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";

// RIGHT
LPTSTR pszSource = L"C:\\Windows\\*\0";

2 つの終端 null 文字を考慮するには、MAX_PATHを保持するのに十分な大きさのバッファー (通常は 1 つの終端 null 文字を含む) と 1 を作成してください。

パスは常に完全なパスである必要があるため、過剰に言い過ぎることはできません。 pFrom または pTo メンバーが修飾されていない名前の場合、現在のディレクトリは、GetCurrentDirectory 関数と SetCurrentDirectory 関数によって管理されるグローバルな現在のドライブとディレクトリ設定から取得されます。

完全なパスを指定しない場合、次の事実が関連します。

  • ファイル名の前にパスがない場合、このファイルが現在のディレクトリのルートに存在することを SHFileOperation に示すわけではありません。
  • PATH 環境変数は、有効なパスを決定するために SHFileOperation によって使用されません。
  • SHFileOperation は、実行時に現在のディレクトリであるディレクトリを使用するために依存できません。 現在のディレクトリと見なされるディレクトリはプロセス全体であり、操作の実行中に別のスレッドから変更できます。 その場合、 SHFileOperation の結果は予測できません。

pFrom が完全なパスのないファイル名に設定されている場合、FO_DELETEを使用してファイルを削除しても、FOF_ALLOWUNDO フラグが設定されていてもごみ箱に移動されません。 ファイルをごみ箱に削除するには、完全なパスを指定する必要があります。

SHFileOperation は、"\?" というプレフィックスが付いたパスで失敗します。

この構造体には、ANSI バージョン (SHFILEOPSTRUCTA) と Unicode バージョン (SHFILEOPSTRUCTW) の 2 つのバージョンがあります。 Unicode バージョンは ANSI バージョンと同じですが、ANSI 文字列 (LPCSTR) の代わりにワイド文字列 (LPCWSTR) が使用される点が除きます。 Windows 98 以前では、ANSI バージョンのみがサポートされています。 Microsoft Windows NT 4.0 以降では、この構造体の ANSI バージョンと Unicode バージョンの両方がサポートされています。 SHFILEOPSTRUCTW と SHFILEOPTSTRUCTA を直接使用しないでください。適切な構造体は、アプリケーションが ANSI または Unicode 用にコンパイルされているかどうかに応じて、プリコンパイラーによって SHFILEOPSTRUCT として再定義されます。

SHNAMEMAPPING には、ANSI と Unicode のバージョンが似ています。 ANSI アプリケーションの場合、 hNameMappings は int を指し、その後に ANSI SHNAMEMAPPING 構造体の配列が続きます。 Unicode アプリケーションの場合、 hNameMappings は int を指し、その後に Unicode SHNAMEMAPPING 構造体の配列が続きます。 ただし、Microsoft Windows NT 4.0 以降では、SHFileOperation は常に、SHNAMEMAPPING 構造体の Unicode セットへのハンドルを返します。 アプリケーションをすべてのバージョンの Windows で機能させる場合は、アプリケーションで条件付きコードを使用して名前マッピングを処理する必要があります。 次に例を示します。

x = SHFileOperation(&shop);

if (fWin9x) 
    HandleAnsiNameMappings(shop.hNameMappings);
else 
    HandleUnicodeNameMappings(shop.hNameMappings);

hNameMappings は、その宣言に示されているように、メンバーが UINT 値の後に SHNAMEMAPPING 構造体の配列へのポインターが続く構造体へのポインターとして扱います。

struct HANDLETOMAPPINGS 
{
    UINT              uNumberOfMappings;  // Number of mappings in the array.
    LPSHNAMEMAPPING   lpSHNameMapping;    // Pointer to the array of mappings.
};

UINT 値は、配列内の SHNAMEMAPPING 構造体の数を示します。 各 SHNAMEMAPPING 構造体には、名前が変更されたファイルの古いパスと新しいパスが含まれています。

メモ ハンドルは SHFreeNameMappings を使用して解放する必要があります。
 

注意

shellapi.h ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして SHFILEOPSTRUCT を定義します。 encoding-neutral エイリアスの使用を encoding-neutral ではないコードと混在すると、コンパイル エラーまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

   
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
Header shellapi.h