MoveFileWithProgressA 函数（winbase.h）

项目
11/20/2024

移动文件或目录，包括其子级。可以提供接收进度通知的回调函数。

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

语法

BOOL MoveFileWithProgressA(
  [in]           LPCSTR             lpExistingFileName,
  [in, optional] LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in]           DWORD              dwFlags
);

参数

[in] lpExistingFileName

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

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

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

提示

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

[in, optional] lpNewFileName

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

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

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

如果 dwFlags 指定 MOVEFILE_DELAY_UNTIL_REBOOT，lpNewFileName为 NULL，MoveFileWithProgress 注册 lpExistingFileName，以便在系统重新启动时将其删除。如果函数无法访问注册表来存储有关删除操作的信息，则函数将失败。如果 lpExistingFileName 引用目录，则仅当目录为空时，系统才会在重新启动时删除目录。

提示

[in, optional] lpProgressRoutine

指向 CopyProgressRoutine 回调函数的指针，该函数每次移动文件的另一部分时都会调用该函数。如果提供显示操作进度的用户界面，则回调函数非常有用。此参数可以 NULL。

[in, optional] lpData

要传递给 CopyProgressRoutine 回调函数的参数。此参数可以 NULL。

[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 文件的内容。如果 lpNewFileName 或 lpExistingFileName 为目录命名，则不能使用此值。
MOVEFILE_WRITE_THROUGH 8 （0x8）	在文件实际移动到磁盘之前，该函数不会返回。设置此值可确保在函数返回之前将作为复制和删除操作执行的移动刷新到磁盘。刷新发生在复制操作结束时。如果设置了 MOVEFILE_DELAY_UNTIL_REBOOT，则此值不起作用。

返回值

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

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

在卷之间移动文件时，如果由于用户取消操作，lpProgressRoutine 返回 PROGRESS_CANCEL，MoveFileWithProgress 将返回零，GetLastError 将返回 ERROR_REQUEST_ABORTED。现有文件保持不变。

在卷之间移动文件时，如果由于用户停止操作而 lpProgressRoutine 返回 PROGRESS_STOP，MoveFileWithProgress 将返回零，GetLastError 将返回 ERROR_REQUEST_ABORTED。现有文件保持不变。

言论

MoveFileWithProgress 函数将其操作与链接跟踪服务协调，因此可以在移动链接源时跟踪链接源。

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

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

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

Csv 将为压缩文件执行重定向的 IO。

注意

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

要求

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