SHFileOperationA 函数 (shellapi.h)

  • 项目

复制、移动、重命名或删除文件系统对象。 此函数已在 Windows Vista 中由 IFileOperation 替换。

语法

int SHFileOperationA(
  [in, out] LPSHFILEOPSTRUCTA 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”， (区分大小写;例如，“.文件“) 不起作用。 此处提供了一个示例。

  1. 在 C：\Files 目录 (C:\Files\Test.htm) 中创建名为 Test.htm 的文件。
  2. 在 C：\Files 目录中创建名为 Test.files 的新文件夹 (C：\Files\Test.files) 。
  3. 使用几个文件填充 文件夹。 放置在此文件夹中的任何文件都连接到 Test.htm。
  4. 将 Test.htm 文件移动或复制到 C：\Files2 目录。
  5. 请注意，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 可能无效。 术语“文件”可能需要替换为本地语言中的等效词。

注意

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

要求

要求 值
最低受支持的客户端 Windows XP [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 shellapi.h
Library Shell32.lib
DLL Shell32.dll (4.0 或更高版本)
API 集 ext-ms-win-shell-shell32-l1-2-1 (在 Windows 10 版本 10.0.10240 中引入)