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

SHFILEOPSTRUCTA

構造体
サイズ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 を使用してください。

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

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

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

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

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

  • ワイルドカード文字はサポートされません。
  • コピーおよび移動の操作では、存在しないコピー先ディレクトリを指定できます。その場合、システムはそのディレクトリの作成を試み、通常は新しいディレクトリを作成するかどうかをユーザーに確認するダイアログボックスを表示します。このダイアログボックスを表示せずにディレクトリを自動的に作成するには、fFlagsFOF_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

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

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 フラグが含まれている場合にのみ使用されます。詳細については「解説」を参照してください。
lpszProgressTitleLPSTR8/4+42+26進行状況のダイアログボックスのタイトルへのポインターです。これは NULL 終端文字列です。このメンバーは、fFlagsFOF_SIMPLEPROGRESS フラグが含まれている場合にのみ使用されます。

公式ドキュメント

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 アプリケーションの場合、hNameMappingsint と、それに続く ANSI 版 SHNAMEMAPPING 構造体の配列を指します。Unicode アプリケーションの場合、hNameMappingsint と、それに続く 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 ヘッダーは、UNICODE プリプロセッサ定数の定義に基づいてこの関数の ANSI 版と Unicode 版を自動的に選択するエイリアスとして SHFILEOPSTRUCT を定義します。エンコード中立のエイリアスの使用と、エンコード中立でないコードを混在させると、不一致が生じてコンパイルエラーや実行時エラーを引き起こすことがあります。詳細については Conventions for Function Prototypes を参照してください。

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

各言語での定義

#include <windows.h>

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

[StructLayout(LayoutKind.Sequential, Pack = 1, CharSet = CharSet.Unicode)]
public struct SHFILEOPSTRUCTA
{
    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 SHFILEOPSTRUCTA
    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 SHFILEOPSTRUCTA(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 SHFILEOPSTRUCTA {
    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 SHFILEOPSTRUCTA struct {
	hwnd uintptr
	wFunc uint32
	pFrom uintptr
	pTo uintptr
	fFlags uint16
	fAnyOperationsAborted int32
	hNameMappings uintptr
	lpszProgressTitle uintptr
}
type
  SHFILEOPSTRUCTA = packed record
    hwnd: Pointer;
    wFunc: DWORD;
    pFrom: Pointer;
    pTo: Pointer;
    fFlags: Word;
    fAnyOperationsAborted: BOOL;
    hNameMappings: Pointer;
    lpszProgressTitle: Pointer;
  end;
const SHFILEOPSTRUCTA = extern struct {
    hwnd: ?*anyopaque,
    wFunc: u32,
    pFrom: ?*anyopaque,
    pTo: ?*anyopaque,
    fFlags: u16,
    fAnyOperationsAborted: i32,
    hNameMappings: ?*anyopaque,
    lpszProgressTitle: ?*anyopaque,
};
type
  SHFILEOPSTRUCTA {.packed.} = object
    hwnd: pointer
    wFunc: uint32
    pFrom: pointer
    pTo: pointer
    fFlags: uint16
    fAnyOperationsAborted: int32
    hNameMappings: pointer
    lpszProgressTitle: pointer
align(1)
struct SHFILEOPSTRUCTA
{
    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 レイアウト)
; SHFILEOPSTRUCTA サイズ: 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 : CHAR* (+8, 4byte)  st.2 = 値  /  値 = st.2   (lpoke/lpeek も可)
; pTo : CHAR* (+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 : LPSTR (+26, 4byte)  lpoke st,26,値  /  値 = lpeek(st,26)
; ※4byte境界の整数は添字 st.N(N=オフセット/4)で読み書き可。それ以外は peek/poke 系を使用。
; HSP3.7/3.8 は構造体機能が無いため、4byte整数の配列変数で操作します。(x64 レイアウト)
; SHFILEOPSTRUCTA サイズ: 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 : CHAR* (+12, 8byte)  qpoke st,12,値 / qpeek(st,12)  ※IronHSPのみ。3.7/3.8は lpoke st,12,下位 : lpoke st,16,上位
; pTo : CHAR* (+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 : LPSTR (+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 SHFILEOPSTRUCTA, 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, SHFILEOPSTRUCTA        ; NSTRUCT 変数を確保
st->wFunc = 100
mes "wFunc=" + st->wFunc