SHFILEOPSTRUCTA 構造体 (shellapi.h)

[アーティクル]
07/16/2024

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 メンバーも double-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 フラグが含まれている場合にのみ使用されます。

備考

重要な ソースパスと宛先パスがダブル 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 バージョンと同じですが、ワイド文字列 (LPCWSTR) が ANSI 文字列 (LPCSTR) の代わりに使用される点が異なります。 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 構造体には、名前が変更されたファイルの 1 つの古いパスと新しいパスが含まれています。

注意ハンドルは、SHFreeNameMappingsで解放する必要があります。

手記

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

必要条件

要件	価値
サポートされる最小クライアント	Windows XP [デスクトップアプリのみ]
サポートされる最小サーバー	Windows 2000 Server [デスクトップアプリのみ]
ヘッダー	shellapi.h

次の方法で共有