MoveFileExA 函数（winbase.h）

项目
06/27/2024

使用各种移动选项移动现有文件或目录，包括其子级。

MoveFileWithProgress 函数等效于 MoveFileEx 函数，但 MoveFileWithProgress 允许你提供接收进度通知的回调函数。

若要将此操作作为事务处理操作执行，请使用 MoveFileTransacted 函数。

语法

BOOL MoveFileExA(
  [in]           LPCSTR lpExistingFileName,
  [in, optional] LPCSTR lpNewFileName,
  [in]           DWORD  dwFlags
);

参数

[in] lpExistingFileName

本地计算机上的文件或目录的当前名称。

如果 dwFlags 指定 MOVEFILE_DELAY_UNTIL_REBOOT，则远程共享上不能存在该文件，因为在网络可用之前会执行延迟的操作。

默认情况下，名称限制为MAX_PATH个字符。若要将此限制扩展到 32,767 宽字符，请将“\\？\”前面追加到路径。有关详细信息，请参阅命名文件、路径和命名空间。

提示

从 Windows 10 版本 1607 开始，你可以选择加入以删除MAX_PATH限制，而无需追加“\\？\”。有关详细信息，请参阅命名文件、路径和命名空间的“最大路径长度限制”部分。

[in, optional] lpNewFileName

本地计算机上的文件或目录的新名称。

移动文件时，目标可以位于其他文件系统或卷上。如果目标位于另一个驱动器上，则必须在 dwFlags中设置 MOVEFILE_COPY_ALLOWED 标志。

移动目录时，目标必须位于同一驱动器上。

如果 dwFlags 指定 MOVEFILE_DELAY_UNTIL_REBOOT，lpNewFileName为 NULL，MoveFileEx 注册在系统重启时要删除的 lpExistingFileName 文件。如果 lpExistingFileName 引用目录，则仅当目录为空时，系统才会在重新启动时删除目录。

提示

[in] dwFlags

此参数可以是以下一个或多个值。

价值	意义
MOVEFILE_COPY_ALLOWED 2 （0x2）	如果要将文件移动到其他卷，该函数将使用 CopyFile 和 DeleteFile 函数模拟移动。如果文件已成功复制到其他卷，并且无法删除原始文件，该函数会成功使源文件保持不变。此值不能与 MOVEFILE_DELAY_UNTIL_REBOOT一起使用。
MOVEFILE_CREATE_HARDLINK 16 （0x10）	保留以供将来使用。
MOVEFILE_DELAY_UNTIL_REBOOT 4 （0x4）	在重新启动操作系统之前，系统不会移动该文件。系统在执行 AUTOCHK 后立即移动文件，但在创建任何分页文件之前。因此，此参数使函数能够从以前的启动中删除分页文件。仅当进程位于属于管理员组或 LocalSystem 帐户的用户的上下文中时，才能使用此值。此值不能与 MOVEFILE_COPY_ALLOWED一起使用。
MOVEFILE_FAIL_IF_NOT_TRACKABLE 32 （0x20）	如果源文件是链接源，但移动后无法跟踪该文件，则函数将失败。如果目标是使用 FAT 文件系统格式化的卷，则可能会出现这种情况。
MOVEFILE_REPLACE_EXISTING 1 （0x1）	如果存在名为 lpNewFileName 的文件，该函数会将其内容替换为 lpExistingFileName 文件的内容，前提是满足与访问控制列表（ACL）相关的安全要求。有关详细信息，请参阅本主题的“备注”部分。如果 lpNewFileName 为现有目录命名，则报告错误。
MOVEFILE_WRITE_THROUGH 8 （0x8）	在磁盘上实际移动文件之前，该函数不会返回。设置此值可确保在函数返回之前将作为复制和删除操作执行的移动刷新到磁盘。刷新发生在复制操作结束时。如果设置了 MOVEFILE_DELAY_UNTIL_REBOOT，则此值不起作用。

返回值

如果函数成功，则返回值为非零。

如果函数失败，则返回值为零（0）。若要获取扩展的错误信息，请调用 GetLastError。

言论

如果 dwFlags 参数指定 MOVEFILE_DELAY_UNTIL_REBOOT，MoveFileEx 无法访问注册表时将失败。该函数在以下注册表值中存储要在重启时重命名的文件的位置：HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\PendingFileRenameOperations

此注册表值的类型为 REG_MULTI_SZ。每个重命名操作存储以下以 NULL 结尾的字符串之一，具体取决于重命名是否为删除：

szSrcFile\0\0
szSrcFile\0szDstFile\0

字符串 szSrcFile\0\0 指示在重新启动时删除 szSrcFile 文件。 szSrcFile\0szDstFile\0 表示重新启动时 szSrcFile重命名 szDstFile。

注意尽管在技术上不允许在 REG_MULTI_SZ 节点中使用 \0\0，但由于文件被视为重命名为 null 名称，因此原因可能是。

系统使用这些注册表项以发出相同的顺序在重启时完成操作。例如，以下代码片段创建注册表项，这些注册表项删除 szSrcFile，并在重启时重命名 szSrcFile，以 szDstFile：

MoveFileEx(szSrcFile, NULL, MOVEFILE_DELAY_UNTIL_REBOOT);
MoveFileEx(szSrcFile, szDstFile, MOVEFILE_DELAY_UNTIL_REBOOT);

由于调用应用程序停止运行后，使用 MOVEFILE_DELAY_UNTIL_REBOOT 标志指定的实际移动和删除操作，因此返回值无法反映移动或删除文件的成功或失败。相反，它反映了将适当的条目放入注册表中的成功或失败。

仅当 MOVEFILE_DELAY_UNTIL_REBOOT 标志为空时，系统才会删除标记为删除的目录。若要确保删除目录，请先移动或删除目录中的所有文件，然后再尝试删除它。文件可能在启动时位于目录中，但必须先删除或移动文件，然后系统才能删除目录。

移动和删除操作在启动时按在调用应用程序中指定的顺序执行。若要在启动时删除包含其中文件的目录，请先删除这些文件。

如果文件跨卷移动，MoveFileEx 不会移动文件的安全描述符。该文件在目标目录中分配了默认的安全描述符。

MoveFileEx 函数使用链接跟踪服务协调其操作，因此可以在移动链接源时进行跟踪。

若要删除或重命名文件，必须对文件具有删除权限，或者删除父目录中的子权限。如果设置了具有除删除和删除子级和新文件的 ACL 以外的所有访问权限的目录，则应能够创建一个文件，而无需删除它。但是，然后，可以创建一个文件，并在创建文件时返回的句柄上获取请求的所有访问权限。如果在创建文件时请求删除权限，则可以使用该句柄删除或重命名该文件，但不能使用任何其他句柄来重命名该文件。有关详细信息，请参阅文件安全和访问权限。

在 Windows 8 和 Windows Server 2012 中，以下技术支持此函数。

科技	支持
服务器消息块（SMB） 3.0 协议	是的
SMB 3.0 透明故障转移（TFO）	是的
具有横向扩展文件共享的 SMB 3.0 （SO）	是的
群集共享卷文件系统（CsvFS）	是的
可复原文件系统（ReFS）	是的

例子

有关示例，请参阅创建和使用临时文件。

要求

要求	价值
最低支持的客户端	Windows XP [桌面应用 \|UWP 应用]
支持的最低服务器	Windows Server 2003 [桌面应用 \|UWP 应用]
目标平台	窗户
标头	winbase.h （包括 Windows.h）
库	Kernel32.lib
DLL	Kernel32.dll