shFileOperationW 函数 (shellapi.h)
复制、移动、重命名或删除文件系统对象。 此函数已在 Windows Vista 中替换为 IFileOperation。
语法
int SHFileOperationW(
[in, out] LPSHFILEOPSTRUCTW lpFileOp
);
参数
[in, out] lpFileOp
类型： LPSHFILEOPSTRUCT
指向 SHFILEOPSTRUCT 结构的指针，该结构包含此函数执行指定操作所需的信息。 此参数必须包含非 NULL 的有效值。 你负责验证值。 如果不进行验证，将遇到意外结果。
返回值
类型： int
如果成功，则返回零;否则为非零。 应用程序通常只应检查为零或非零。
最好检查 SHFILEOPSTRUCT 的 fAnyOperationsAborted 成员的值。 如果用户取消操作，SHFileOperation 可以返回 0 表示成功。 如果不检查 fAnyOperationsAborted 以及返回值，则无法知道该函数完成了你要求它的完整任务，并且你可能会在错误的假设下继续。
不要将此函数的返回值与 GetLastError 一起使用。
为了检查非零值以进行故障排除，它们主要映射到 Winerror.h 中定义的值。 但是，其多个可能的返回值都基于 Win32 之前的错误代码，在某些情况下，这些错误代码与后面的 Winerror.h 值重叠，而不匹配其含义。 此处详细介绍了这些特定值， 对于这些特定值，应仅 通过 Winerror.h 代码接受这些含义。 但是，这些值随以下警告一起提供：
- 这些是 Win32 之前的错误代码，在任何公共头文件中不再受支持或定义。 若要使用它们，必须自行定义它们或将其与数值进行比较。
- 这些错误代码可能会更改，并且历来都是如此。
- 这些值仅作为调试的帮助提供。 不应将其视为确定性。
| 错误代码 | 值 | 含义 |
|---|---|---|
| DE_SAMEFILE | 0x71 | 源文件和目标文件是同一个文件。 |
| DE_MANYSRC1DEST | 0x72 | 源缓冲区中指定了多个文件路径，但只有一个目标文件路径。 |
| DE_DIFFDIR | 0x73 | 指定了重命名操作，但目标路径是不同的目录。 请改用移动操作。 |
| DE_ROOTDIR | 0x74 | 源是根目录，无法移动或重命名。 |
| DE_OPCANCELLED | 0x75 | 操作已被用户取消，或者，如果向 SHFileOperation 提供了相应的标志，则以无提示方式取消操作。 |
| DE_DESTSUBTREE | 0x76 | 目标是源的子树。 |
| DE_ACCESSDENIEDSRC | 0x78 | 安全设置拒绝访问源。 |
| DE_PATHTOODEEP | 0x79 | 源或目标路径超出或将超过 MAX_PATH。 |
| DE_MANYDEST | 0x7A | 该操作涉及多个目标路径，在移动操作中可能会失败。 |
| DE_INVALIDFILES | 0x7C | 源或目标中的路径或两者都无效。 |
| DE_DESTSAMETREE | 0x7D | 源和目标具有相同的父文件夹。 |
| DE_FLDDESTISFILE | 0x7E | 目标路径是现有文件。 |
| DE_FILEDESTISFLD | 0x80 | 目标路径是现有文件夹。 |
| DE_FILENAMETOOLONG | 0x81 | 文件名超过 MAX_PATH。 |
| DE_DEST_IS_CDROM | 0x82 | 目标是只读 CD-ROM，可能未格式化。 |
| DE_DEST_IS_DVD | 0x83 | 目标是只读 DVD，可能未格式化。 |
| DE_DEST_IS_CDRECORD | 0x84 | 目标为可写 CD-ROM，可能未格式化。 |
| DE_FILE_TOO_LARGE | 0x85 | 操作中涉及的文件对于目标媒体或文件系统来说太大。 |
| DE_SRC_IS_CDROM | 0x86 | 源是只读 CD-ROM，可能未格式化。 |
| DE_SRC_IS_DVD | 0x87 | 源是只读 DVD，可能未格式化。 |
| DE_SRC_IS_CDRECORD | 0x88 | 源是可写 CD-ROM，可能未格式化。 |
| DE_ERROR_MAX | 0xB7 | 操作期间已超出MAX_PATH。 |
| 0x402 | 出现未知错误。 这通常是由于源或目标中的路径无效。 此错误不会在 Windows Vista 及更高版本上发生。 | |
| ERRORONDEST | 0x10000 | 目标上发生未指定的错误。 |
| DE_ROOTDIR |ERRORONDEST | 0x10074 | Destination 是根目录，无法重命名。 |
注解
应使用此函数的完全限定路径名。 将它与相对路径名称一起使用不是线程安全的。
有两个例外，不能使用 SHFileOperation 通过指定网络路径将特殊文件夹从本地驱动器移动到远程计算机。 例外是 “我的文档 ” (CSIDL_PERSONAL、 CSIDL_DOCUMENTS) 和 “我的图片 ”文件夹 (CSIDL_MYPICTURES) 。
使用删除文件时，SHFileOperation 会永久删除该文件，除非你在 lpFileOp 指向的 SHFILEOPSTRUCT 结构的 fFlags 成员中设置了 FOF_ALLOWUNDO 标志。 设置该标志会将文件发送到回收站。 如果只想删除文件并保证不会将其放置在回收站中，请使用 DeleteFile。
如果公开并注册了复制回调处理程序，SHFileOperation 将调用它，除非你在 lpFileOp 指向的结构的 fFlags成员中设置了FOF_NOCONFIRMATION等标志。 有关实现复制回调处理程序的详细信息，请参阅 ICopyHook：：CopyCallback 。
除非在 lpFileOp 中设置FOF_NORECURSION标志，否则文件删除是递归的。
连接文件
使用 Windows 2000 或更高版本，可以将 HTML 文件与包含相关文件（例如图形交换格式 (GIF) 图像或样式表）的文件夹 连接 起来。 如果启用文件连接，则移动或复制 HTML 文件时，连接的文件夹及其所有文件也会移动或复制。 相反，如果移动包含相关文件的文件夹，也会移动 HTML 文件。HTML 文件必须具有 .htm 或 .html 扩展名。 通过将包含相关文件的文件夹放入 HTML 文件所在的同一文件夹中，创建与相关文件的连接。 包含已连接文件的文件夹的名称必须与 HTML 文件的名称相同，后跟“_files”或“.files”， (这区分大小写;例如，“.文件“) 不起作用。 此处提供了一个示例。
- 在 C：\Files 目录 (C:\Files\Test.htm) 中创建名为 Test.htm 的文件。
- 在 C：\Files 目录中创建一个名为 Test.files 的新文件夹， (C：\Files\Test.files) 。
- 使用几个文件填充文件夹。 放置在此文件夹中的任何文件都连接到 Test.htm。
- 将 Test.htm 文件移动或复制到 C：\Files2 目录。
- 请注意，Test.files 目录现在也位于 C：\Files2 目录中。
默认情况下，文件连接处于启用状态。 可以通过添加 REG_DWORD 项 NoFileFolderConnection 来禁用它，如下所示：
HKEY_CURRENT_USER Software Microsoft Windows CurrentVersion Explorer NoFileFolderConnection
将 NoFileFolderConnection 设置为 1 会禁用文件连接。 如果值设置为零或缺失，则启用文件连接。
若要仅移动指定的文件而没有连接的文件，请在 lpFileOp 指向的结构的 fFlags 成员中设置FOF_NO_CONNECTED_ELEMENTS标志。
请注意，使用名称为“MyFile_files”的文件夹来定义连接对于本地化版本的 Windows 可能无效。 术语“files”可能需要替换为本地语言中的等效词。
注意
shellapi.h 标头将 SHFileOperation 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。
要求
| 要求 | 值 |
|---|---|
| 最低受支持的客户端 | Windows XP [仅限桌面应用] |
| 最低受支持的服务器 | Windows 2000 Server [仅限桌面应用] |
| 目标平台 | Windows |
| 标头 | shellapi.h |
| Library | Shell32.lib |
| DLL | Shell32.dll (版本 4.0 或更高版本) |
| API 集 | Windows 10版本 10.0.10240 中引入的 ext-ms-win-shell-shell32-l1-2-1 () |