moveFileTransactedA 函数 (winbase.h)

项目
03/13/2024

[Microsoft 强烈建议开发人员利用替代方法来实现应用程序的需求。 TxF 致力于实现的许多方案都可以通过更简单、更易用的技术来实现。此外，TxF 在 Microsoft Windows 的将来版本中可能不可用。有关详细信息，以及 TxF 的替代方法，请参阅事务性 NTFS 的替代方法。]

将现有文件或目录（包括其子级）作为事务处理操作移动。

语法

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

参数

[in] lpExistingFileName

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

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

提示

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

[in, optional] lpNewFileName

文件或目录的新名称。新名称不得已存在。新文件可能位于不同的文件系统或驱动器上。新目录必须位于同一驱动器上。

提示

[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_REPLACE_EXISTING 1 (0x1)	如果存在名为 lpNewFileName 的文件，则函数将其内容替换为 lpExistingFileName 文件的内容。如果 lpNewFileName 或 lpExistingFileName 命名目录，则不能使用此值。
MOVEFILE_WRITE_THROUGH 8 (0x8)	调用 MoveFileTransacted 意味着在完成提交操作时移动文件操作已完成。此标志是不必要的;如果指定此标志，则不会造成负面影响，但操作速度会变慢。在磁盘上实际移动文件之前，函数不会返回。设置此值可确保作为复制和删除操作执行的移动在函数返回之前刷新到磁盘。刷新发生在复制操作结束时。如果设置了 MOVEFILE_DELAY_UNTIL_REBOOT ，则此值无效。

[in] hTransaction

事务的句柄。此句柄由 CreateTransaction 函数返回。

返回值

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

如果函数失败，则返回值为零。要获得更多的错误信息，请调用 GetLastError。

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

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

注解

如果 dwFlags 参数指定 MOVEFILE_DELAY_UNTIL_REBOOT，则 MoveFileTransacted 如果无法访问注册表，则它将失败。函数以事务方式将重启时要重命名的文件的位置存储在以下注册表值中： HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\控制\会话管理器\PendingFileRenameOperations

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

szDstFile\0\0

szSrcFile\0szDstFile\0

字符串 szDstFile\0\0 指示文件 szDstFile 将在重新启动时删除。

字符串 szSrcFile\0szDstFile\0 指示 szSrcFile 将在重新启动时重命名为 szDstFile 。

注意尽管在技术上不允许 在REG_MULTI_SZ 节点中使用 \0\0，但它是因为它被视为重命名为空名称。

系统使用这些注册表项在重启时按照它们发出的相同顺序完成操作。有关使用 MOVEFILE_DELAY_UNTIL_REBOOT 标志的详细信息，请参阅 MoveFileWithProgress。

如果文件跨卷移动， MoveFileTransacted 不会随文件一起移动安全描述符。文件在目标目录中分配默认安全描述符。

如果指定 MOVEFILE_FAIL_IF_NOT_TRACKABLE 标志，则此函数始终失败;TxF 不支持跟踪。

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

技术	支持
服务器消息块 (SMB) 3.0 协议	否
SMB 3.0 透明故障转移 (TFO)	否
具有横向扩展文件共享的 SMB 3.0 (SO)	否
群集共享卷文件系统 (CSV)	否
弹性文件系统 (ReFS)	否

SMB 3.0 不支持 TxF。

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	winbase.h (包括 Windows.h)
Library	Kernel32.lib
DLL	Kernel32.dll

另请参阅

通过

moveFileTransactedA 函数 (winbase.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源