Win32 API 日本語リファレンス
ホーム › UI.Shell › SHFILEOPSTRUCTW

SHFILEOPSTRUCTW

構造体
📘 Microsoft Learn (日本語) · English
サイズx64: 50 バイト / x86: 30 バイトパッキング1

サイズ=各フィールドのバイト数(x64/x86 で異なる場合は x64/x86 と併記)。x64/x86 列=フィールドのバイトオフセット(HSPで dupptr / lpoke / wpoke 等に使用)。

フィールド

フィールド型サイズx64x86説明
hwndHWND8/4+0+0ファイル操作の状態に関する情報を表示するダイアログ ボックスのウィンドウ ハンドルです。
wFuncDWORD4+8+4

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

FO_COPY

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

FO_DELETE

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

FO_MOVE

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

FO_RENAME

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

pFromLPWSTR8/4+12+8
注 この文字列は二重の NULL で終端されていなければなりません。
1 つ以上のコピー元ファイル名へのポインターです。予期しない結果を防ぐため、これらの名前は完全修飾パスで指定してください。

"*" などの標準的な MS-DOS のワイルドカード文字は、ファイル名の位置でのみ使用できます。文字列内のそれ以外の位置でワイルドカード文字を使用すると、予測できない結果を招きます。

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

pToLPWSTR8/4+20+12
注 この文字列は二重の NULL で終端されていなければなりません。
コピー先のファイル名またはディレクトリ名へのポインターです。使用しない場合、このパラメーターは NULL に設定しなければなりません。ワイルドカード文字は使用できません。使用すると予測できない結果を招きます。

pFrom と同様に、pTo メンバーも二重 NULL 終端の文字列であり、ほぼ同じ方法で扱われます。ただし、pTo は次の仕様を満たさなければなりません。

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

ファイル操作を制御するフラグです。このメンバーには、次のフラグの組み合わせを指定できます。

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 を部分的にオーバーライドします。

fAnyOperationsAbortedBOOL4+30+18関数が戻るとき、完了前に中止されたファイル操作がある場合、このメンバーには TRUE が格納されます。それ以外の場合は FALSE が格納されます。操作は、UI を通じてユーザーが手動で中止できるほか、FOF_NOERRORUI フラグまたは FOF_NOCONFIRMATION フラグが設定されている場合はシステムによって通知なしで中止されることもあります。
hNameMappingsvoid*8/4+34+22関数が戻るとき、このメンバーには、名前が変更されたファイルの変更前と変更後の名前を格納する名前マッピング オブジェクトへのハンドルが格納されます。このメンバーは、fFlags メンバーに FOF_WANTMAPPINGHANDLE フラグが含まれている場合にのみ使用されます。詳細については「解説」を参照してください。
lpszProgressTitleLPWSTR8/4+42+26

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

- fFlags.FOF_ALLOWUNDO

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

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

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

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

- fFlags.FOF_CONFIRMMOUSE

使用されません。

- fFlags.FOF_FILESONLY

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

- fFlags.FOF_MULTIDESTFILES

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

- fFlags.FOF_NOCONFIRMATION

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

- fFlags.FOF_NOCONFIRMMKDIR

操作に新しいディレクトリの作成が必要な場合でも、その作成をユーザーに確認しません。

- fFlags.FOF_NOCOPYSECURITYATTRIBS

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

- fFlags.FOF_NOERRORUI

エラーが発生しても、ユーザーにダイアログを表示しません。

- fFlags.FOF_NORECURSEREPARSE

使用されません。

- fFlags.FOF_NORECURSION

ローカル ディレクトリ内でのみ操作を実行します。既定の動作であるサブディレクトリへの再帰的な操作は行いません。

- fFlags.FOF_NO_CONNECTED_ELEMENTS

バージョン 5.0。 関連付けられたファイルをグループとして移動しません。指定されたファイルのみを移動します。

- fFlags.FOF_NO_UI

Windows Vista。ユーザーに UI を表示せず、通知なしで操作を実行します。これは FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_NOCONFIRMMKDIR と同等です。

- fFlags.FOF_RENAMEONCOLLISION

移動、コピー、または名前変更の操作で、コピー先に同じ名前のファイルが既に存在する場合、操作対象のファイルに新しい名前を付けます。

- fFlags.FOF_SILENT

進行状況ダイアログ ボックスを表示しません。

- fFlags.FOF_SIMPLEPROGRESS

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

- fFlags.FOF_WANTMAPPINGHANDLE

FOF_RENAMEONCOLLISION が指定されていて、いずれかのファイルの名前が変更された場合に、変更前と変更後の名前を格納する名前マッピング オブジェクトを hNameMappings メンバーに割り当てます。このオブジェクトは、不要になったら SHFreeNameMappings を使用して解放しなければなりません。

- fFlags.FOF_WANTNUKEWARNING

バージョン 5.0。 削除操作でファイルがごみ箱に移動されずに完全に破棄される場合に、警告を送信します。このフラグは FOF_NOCONFIRMATION を部分的にオーバーライドします。

- wFunc.FO_COPY

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

- wFunc.FO_DELETE

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

- wFunc.FO_MOVE

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

- wFunc.FO_RENAME

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

公式ドキュメント

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

注 Windows Vista 以降では、この関数よりも IFileOperation インターフェイスの使用が推奨されます。

解説(Remarks)

重要 コピー元とコピー先のパスが二重の NULL で終端されていることを必ず確認してください。通常の文字列は NULL 文字 1 つだけで終わります。その値をコピー元またはコピー先のメンバーに渡すと、関数は文字列の終わりに達したことを認識できず、ランダムな二重 NULL 値に到達するまでメモリを読み続けます。これは少なくともバッファー オーバーランを引き起こし、場合によっては無関係なデータを意図せず削除することにもつながります。 
// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";

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

2 つの終端 NULL 文字を考慮して、MAX_PATH (通常は終端 NULL 文字 1 つを含みます) に 1 を加えた大きさのバッファーを作成してください。

パスには常にフル パスを使用すべきであることは、いくら強調してもしすぎることはありません。pFrom メンバーまたは pTo メンバーが修飾されていない名前である場合、カレント ディレクトリは、GetCurrentDirectory 関数および SetCurrentDirectory 関数で管理されるグローバルなカレント ドライブおよびディレクトリの設定から取得されます。

フル パスを指定しない場合、次の点が問題になります。

pFrom にフル パスを含まないファイル名が設定されている場合、FOF_ALLOWUNDO フラグが設定されていても、FO_DELETE によるファイルの削除ではファイルはごみ箱に移動されません。ファイルをごみ箱へ削除するには、フル パスを指定しなければなりません。

SHFileOperation は、"\?" が前に付いたパスに対しては失敗します。

この構造体には ANSI 版 (SHFILEOPSTRUCTA) と Unicode 版 (SHFILEOPSTRUCTW) の 2 つのバージョンがあります。Unicode 版は、ANSI 文字列 (LPCSTR) の代わりにワイド文字列 (LPCWSTR) が使用される点を除き、ANSI 版と同一です。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 は常に Unicode の SHNAMEMAPPING 構造体のセットへのハンドルを返します。すべてのバージョンの 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 ヘッダーは SHFILEOPSTRUCT を、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版または Unicode 版を自動的に選択するエイリアスとして定義します。エンコード中立のエイリアスの使用と、エンコード中立でないコードとを混在させると、不一致が生じてコンパイル エラーや実行時エラーの原因になることがあります。詳細については、関数プロトタイプの規則 を参照してください。

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp) · 原文ソース (GitHub)

各言語での定義

#include <windows.h>

// SHFILEOPSTRUCTW  (x64 50 / x86 30 バイト)
#pragma pack(push, 1)
typedef struct SHFILEOPSTRUCTW {
    HWND hwnd;
    DWORD wFunc;
    LPWSTR pFrom;
    LPWSTR pTo;
    WORD fFlags;
    BOOL fAnyOperationsAborted;
    void* hNameMappings;
    LPWSTR lpszProgressTitle;
} SHFILEOPSTRUCTW;
#pragma pack(pop)
using System;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential, Pack = 1, CharSet = CharSet.Unicode)]
public struct SHFILEOPSTRUCTW
{
    public IntPtr hwnd;
    public uint wFunc;
    public IntPtr pFrom;
    public IntPtr pTo;
    public ushort fFlags;
    [MarshalAs(UnmanagedType.Bool)] public bool fAnyOperationsAborted;
    public IntPtr hNameMappings;
    public IntPtr lpszProgressTitle;
}
Imports System.Runtime.InteropServices

<StructLayout(LayoutKind.Sequential, Pack:=1, CharSet:=CharSet.Unicode)>
Public Structure SHFILEOPSTRUCTW
    Public hwnd As IntPtr
    Public wFunc As UInteger
    Public pFrom As IntPtr
    Public pTo As IntPtr
    Public fFlags As UShort
    <MarshalAs(UnmanagedType.Bool)> Public fAnyOperationsAborted As Boolean
    Public hNameMappings As IntPtr
    Public lpszProgressTitle As IntPtr
End Structure
import ctypes
from ctypes import wintypes

class SHFILEOPSTRUCTW(ctypes.Structure):
    _pack_ = 1
    _fields_ = [
        ("hwnd", ctypes.c_void_p),
        ("wFunc", wintypes.DWORD),
        ("pFrom", ctypes.c_void_p),
        ("pTo", ctypes.c_void_p),
        ("fFlags", ctypes.c_ushort),
        ("fAnyOperationsAborted", wintypes.BOOL),
        ("hNameMappings", ctypes.c_void_p),
        ("lpszProgressTitle", ctypes.c_void_p),
    ]
#[repr(C, packed(1))]
pub struct SHFILEOPSTRUCTW {
    pub hwnd: *mut core::ffi::c_void,
    pub wFunc: u32,
    pub pFrom: *mut core::ffi::c_void,
    pub pTo: *mut core::ffi::c_void,
    pub fFlags: u16,
    pub fAnyOperationsAborted: i32,
    pub hNameMappings: *mut core::ffi::c_void,
    pub lpszProgressTitle: *mut core::ffi::c_void,
}
import "golang.org/x/sys/windows"

type SHFILEOPSTRUCTW struct {
	hwnd uintptr
	wFunc uint32
	pFrom uintptr
	pTo uintptr
	fFlags uint16
	fAnyOperationsAborted int32
	hNameMappings uintptr
	lpszProgressTitle uintptr
}
type
  SHFILEOPSTRUCTW = packed record
    hwnd: Pointer;
    wFunc: DWORD;
    pFrom: Pointer;
    pTo: Pointer;
    fFlags: Word;
    fAnyOperationsAborted: BOOL;
    hNameMappings: Pointer;
    lpszProgressTitle: Pointer;
  end;
const SHFILEOPSTRUCTW = extern struct {
    hwnd: ?*anyopaque,
    wFunc: u32,
    pFrom: ?*anyopaque,
    pTo: ?*anyopaque,
    fFlags: u16,
    fAnyOperationsAborted: i32,
    hNameMappings: ?*anyopaque,
    lpszProgressTitle: ?*anyopaque,
};
type
  SHFILEOPSTRUCTW {.packed.} = object
    hwnd: pointer
    wFunc: uint32
    pFrom: pointer
    pTo: pointer
    fFlags: uint16
    fAnyOperationsAborted: int32
    hNameMappings: pointer
    lpszProgressTitle: pointer
align(1)
struct SHFILEOPSTRUCTW
{
    void* hwnd;
    uint wFunc;
    void* pFrom;
    void* pTo;
    ushort fFlags;
    int fAnyOperationsAborted;
    void* hNameMappings;
    void* lpszProgressTitle;
}

HSP用 定義

HSP3.7/3.8 は構造体機能が無いため4byte整数配列(dim)+peek/poke で操作(32/64bitでサイズ・位置が異なる場合はタブで分割)。IronHSP は NSTRUCT(#defstruct/stdim/->)で32/64bit共通。

; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x86 レイアウト)
; SHFILEOPSTRUCTW サイズ: 30 バイト(x86)
dim st, 8    ; 4byte整数×8(構造体サイズ 30 / 4 切り上げ)
; hwnd : HWND (+0, 4byte)  st.0 = 値  /  値 = st.0   (lpoke/lpeek も可)
; wFunc : DWORD (+4, 4byte)  st.1 = 値  /  値 = st.1   (lpoke/lpeek も可)
; pFrom : LPWSTR (+8, 4byte)  st.2 = 値  /  値 = st.2   (lpoke/lpeek も可)
; pTo : LPWSTR (+12, 4byte)  st.3 = 値  /  値 = st.3   (lpoke/lpeek も可)
; fFlags : WORD (+16, 2byte)  wpoke st,16,値  /  値 = wpeek(st,16)
; fAnyOperationsAborted : BOOL (+18, 4byte)  lpoke st,18,値  /  値 = lpeek(st,18)
; hNameMappings : void* (+22, 4byte)  lpoke st,22,値  /  値 = lpeek(st,22)
; lpszProgressTitle : LPWSTR (+26, 4byte)  lpoke st,26,値  /  値 = lpeek(st,26)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; SHFILEOPSTRUCTW サイズ: 50 バイト(x64)
dim st, 13    ; 4byte整数×13(構造体サイズ 50 / 4 切り上げ)
; hwnd : HWND (+0, 8byte)  qpoke st,0,値 / qpeek(st,0)  ※IronHSPのみ。3.7/3.8は lpoke st,0,下位 : lpoke st,4,上位
; wFunc : DWORD (+8, 4byte)  st.2 = 値  /  値 = st.2   (lpoke/lpeek も可)
; pFrom : LPWSTR (+12, 8byte)  qpoke st,12,値 / qpeek(st,12)  ※IronHSPのみ。3.7/3.8は lpoke st,12,下位 : lpoke st,16,上位
; pTo : LPWSTR (+20, 8byte)  qpoke st,20,値 / qpeek(st,20)  ※IronHSPのみ。3.7/3.8は lpoke st,20,下位 : lpoke st,24,上位
; fFlags : WORD (+28, 2byte)  wpoke st,28,値  /  値 = wpeek(st,28)
; fAnyOperationsAborted : BOOL (+30, 4byte)  lpoke st,30,値  /  値 = lpeek(st,30)
; hNameMappings : void* (+34, 8byte)  qpoke st,34,値 / qpeek(st,34)  ※IronHSPのみ。3.7/3.8は lpoke st,34,下位 : lpoke st,38,上位
; lpszProgressTitle : LPWSTR (+42, 8byte)  qpoke st,42,値 / qpeek(st,42)  ※IronHSPのみ。3.7/3.8は lpoke st,42,下位 : lpoke st,46,上位
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; IronHSP は NSTRUCT(構造体)をサポート。32bit/64bit どちらでも同じコードで動作します。
#defstruct global SHFILEOPSTRUCTW, pack=1
    #field intptr hwnd
    #field int wFunc
    #field intptr pFrom
    #field intptr pTo
    #field short fFlags
    #field bool fAnyOperationsAborted
    #field intptr hNameMappings
    #field intptr lpszProgressTitle
#endstruct

stdim st, SHFILEOPSTRUCTW        ; NSTRUCT 変数を確保
st->wFunc = 100
mes "wFunc=" + st->wFunc