SHFILEOPSTRUCTA 结构 （shellapi.h）

包含 SHFileOperation 函数用于执行文件操作的信息。

Note As of Windows Vista， the use of the IFileOperation interface is recommended over this function.

 

语法

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中指定的文件。 不能使用此标志通过单个函数调用重命名多个文件。 请改用 FO_MOVE。

pFrom

类型：PCZZTSTR

注意 此字符串必须以双 null 结尾。

 

指向一个或多个源文件名称的指针。 这些名称应是完全限定的路径，以防止意外的结果。

标准 MS-DOS 通配符（如“*”）仅允许在文件名位置 。 在字符串中的其他位置使用通配符将导致不可预知的结果。

尽管此成员声明为单个以 null 结尾的字符串，但它实际上是一个可以保存多个以 null 分隔的文件名的缓冲区。 每个文件名都由单个 NULL 字符终止。 最后一个文件名以双 NULL 字符（“\0\0”）终止，以指示缓冲区的末尾。

pTo

类型：PCZZTSTR

注意 此字符串必须以双 null 结尾。

 

指向目标文件或目录名称的指针。 如果未使用此参数，则必须将其设置为 NULL。 不允许使用通配符。 他们的使用将导致不可预知的结果。

与 pFrom一样，pTo 成员也是双 null 终止字符串，处理方式大致相同。 但是，pTo 必须满足以下规范：

• 不支持通配符。
• 复制和移动操作可以指定不存在的目标目录。 在这些情况下，系统会尝试创建它们，并且通常会显示一个对话框，询问用户是否要创建新目录。 若要取消此对话框并让目录以无提示方式创建，请在 fFlags中设置 FOF_NOCONFIRMMKDIR 标志。
• 对于复制和移动操作，如果 fFlags 成员指定 FOF_MULTIDESTFILES，则缓冲区可以包含多个目标文件名。
• 将多个名称打包到 pTo 字符串中，就像 pFrom一样。
• 使用完全限定的路径。 不允许使用相对路径，但可能会产生不可预知的结果。

fFlags

类型：FILEOP_FLAGS

控制文件操作的标志。 此成员可以采用以下标志的组合。

FOF_ALLOWUNDO

如果可能，请保留撤消信息。

在 Windows Vista 之前，只能从执行原始操作的同一进程中撤消操作。

在 Windows Vista 及更高版本中，撤消的范围是用户会话。 在用户会话中运行的任何进程都可以撤消另一个操作。 撤消状态保存在 Explorer.exe 进程中，只要该进程正在运行，就可以协调撤消函数。

如果源文件参数不包含完全限定的路径和文件名，则忽略此标志。

FOF_CONFIRMMOUSE

未使用。

FOF_FILESONLY

如果指定通配符文件名（.），则仅对文件（而不是文件夹）执行操作。

FOF_MULTIDESTFILES

pTo 成员指定多个目标文件（pFrom中的每个源文件一个），而不是要存储所有源文件的一个目录。

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。 如果设置了FOF_NOERRORUI或FOF_NOCONFIRMATION标志，则可以通过 UI 手动中止操作，或者系统可以以无提示方式中止该操作。

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";

若要考虑两个终止 null 字符，请确保创建足够大的缓冲区来容纳MAX_PATH（通常包括单个终止 null 字符）加 1。

不能夸大其词，即路径应始终是完整路径。 如果 pFrom 或 pTo 成员是非限定名称，则当前目录将从由 GetCurrentDirectory 和 SetCurrentDirectory 函数管理的全局当前驱动器和目录设置中获取。

如果未提供完整路径，以下事实将变得相关：

• 文件名之前缺少路径并不指示 SHFileOperation 此文件驻留在当前目录的根目录中。
• SHFileOperation 不使用 PATH 环境变量来确定有效的路径。
• SHFileOperation 不能依赖它开始执行时使用当前目录的目录。 被视为当前目录的目录是进程范围的，可以在执行操作时从另一个线程更改该目录。 如果发生这种情况，则 SHFileOperation 的结果将不可预知。

如果 pFrom 设置为文件名而不使用完整路径，则删除包含 FO_DELETE 的文件不会将其移动到回收站，即使设置了 FOF_ALLOWUNDO 标志。 必须提供完整路径才能将文件删除到回收站。

SHFileOperation 在前缀为“\？”的任何路径上都失败。

此结构有两个版本：ANSI 版本（SHFILEOPSTRUCTA）和 Unicode 版本（SHFILEOPSTRUCTW）。 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始终 将句柄返回到 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 结构都包含其中一个重命名文件的旧路径和新路径。

注释 必须释放句柄 SHFreeNameMappings。

 

注意

shellapi.h 标头将 SHFILEOPSTRUCT 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非中性编码别名与非非编码的代码混合使用可能会导致编译或运行时错误不匹配。 有关详细信息，请参阅函数原型的 约定。

要求

要求	价值
最低支持的客户端	Windows XP [仅限桌面应用]
支持的最低服务器	Windows 2000 Server [仅限桌面应用]
标头	shellapi.h