SHFileOperationA 函数 (shellapi.h)

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

语法

int SHFileOperationA(
  [in, out] LPSHFILEOPSTRUCTA lpFileOp
);

参数

[in, out] lpFileOp

类型:LPSHFILEOPSTRUCT

指向 SHFILEOPSTRUCT 结构的指针,该结构包含此函数执行指定操作所需的信息。 此参数必须包含无效值,该值不 NULL。 你负责验证该值。 如果未验证,将遇到意外结果。

返回值

类型:int

如果成功,则返回零;否则为非零。 应用程序通常应只检查零个或非零。

最好检查 SHFILEOPSTRUCTfAnyOperationsAborted 成员的值。 如果用户取消操作,则 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 目标是根目录,无法重命名。

言论

应使用此函数的完全限定路径名称。 将它与相对路径名称一起使用不是线程安全的。

除了两个例外,不能使用 SHFileOperation 通过指定网络路径将特殊文件夹从本地驱动器移动到远程计算机。 例外情况是“我的文档” CSIDL_PERSONALCSIDL_DOCUMENTS)和 “我的图片” 文件夹(CSIDL_MYPICTURES)。

用于删除文件时,SHFileOperation 永久删除该文件,除非在由 lpFileOp指向的 SHFILEOPSTRU CT 成员的 fFlags 成员中设置 FOF_ALLOWUNDO 标志。 设置该标志会将文件发送到回收站。 如果只想删除文件并确保它未放置在回收站中,请使用 DeleteFile

如果公开并注册了复制回调处理程序,SHFileOperation 调用该处理程序,除非在 fFlags 结构 成员设置标志(FOF_NOCONFIRMATIONlpFileOp)。 有关实现复制回调处理程序的详细信息,请参阅 ICopyHook::CopyCallback

除非在 lpFileOp中设置 FOF_NORECURSION 标志,否则文件删除是递归的。

连接文件

使用 Windows 2000 或更高版本时,可以 将 HTML 文件与包含图形交换格式(GIF)图像或样式表等相关文件的文件夹 连接。 如果启用了文件连接,则移动或复制 HTML 文件时,也会移动或复制连接的文件夹及其所有文件。 相反,如果使用相关文件移动文件夹,HTML 文件也会移动。

HTML 文件必须具有 .htm 或 .html 扩展名。 通过将包含相关文件的文件夹放置在 HTML 文件所在的同一文件夹中来创建与相关文件的连接。 包含已连接文件的文件夹的名称必须与 HTML 文件的名称相同,后跟“_files”或“.files”(这区分大小写;例如“)。文件“不起作用。 此处提供了一个示例。

  1. 在 C:\Files 目录中创建名为 Test.htm 的文件(C:\Files\Test.htm)。
  2. 在 C:\Files 目录(C:\Files\Test.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 会禁用文件连接。 如果该值设置为零或缺失,则启用文件连接。

若要仅移动指定的文件和未移动任何连接的文件,请将 FOF_NO_CONNECTED_ELEMENTS 标志设置为 lpFileOp指向的结构 成员 标志。

请注意,使用名称为“MyFile_files”的文件夹定义连接可能对 Windows 的本地化版本无效。 术语“files”可能需要用本地语言的等效单词替换。

注意

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

要求

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