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 | 目标是根目录,无法重命名。 |
言论
应使用此函数的完全限定路径名称。 将它与相对路径名称一起使用不是线程安全的。
除了两个例外,不能使用 SHFileOperation 通过指定网络路径将特殊文件夹从本地驱动器移动到远程计算机。 例外情况是“我的文档”
用于删除文件时,
如果公开并注册了复制回调处理程序,
除非在 lpFileOp中设置 FOF_NORECURSION 标志,否则文件删除是递归的。
连接文件
使用 Windows 2000 或更高版本时,可以 将 HTML 文件与包含图形交换格式(GIF)图像或样式表等相关文件的文件夹 连接。 如果启用了文件连接,则移动或复制 HTML 文件时,也会移动或复制连接的文件夹及其所有文件。 相反,如果使用相关文件移动文件夹,HTML 文件也会移动。HTML 文件必须具有 .htm 或 .html 扩展名。 通过将包含相关文件的文件夹放置在 HTML 文件所在的同一文件夹中来创建与相关文件的连接。 包含已连接文件的文件夹的名称必须与 HTML 文件的名称相同,后跟“_files”或“.files”(这区分大小写;例如“)。文件“不起作用。 此处提供了一个示例。
- 在 C:\Files 目录中创建名为 Test.htm 的文件(C:\Files\Test.htm)。
- 在 C:\Files 目录(C:\Files\Test.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 会禁用文件连接。 如果该值设置为零或缺失,则启用文件连接。
若要仅移动指定的文件和未移动任何连接的文件,请将
请注意,使用名称为“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 中引入) |