ReplaceFileA 函数（winbase.h）

项目
11/20/2024

将一个文件替换为另一个文件，并可以选择创建原始文件的备份副本。替换文件假定替换文件的名称及其标识。

语法

BOOL ReplaceFileA(
  [in]           LPCSTR lpReplacedFileName,
  [in]           LPCSTR lpReplacementFileName,
  [in, optional] LPCSTR lpBackupFileName,
  [in]           DWORD  dwReplaceFlags,
                 LPVOID lpExclude,
                 LPVOID lpReserved
);

参数

[in] lpReplacedFileName

要替换的文件的名称。

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

提示

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

此文件使用 GENERIC_READ、DELETE打开，SYNCHRONIZE 访问权限。共享模式 FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE。

调用方必须对要替换的文件具有写入访问权限。有关详细信息，请参阅文件安全和访问权限。

[in] lpReplacementFileName

将替换 lpReplacedFileName 文件的文件的名称。

提示

该函数尝试使用 SYNCHRONIZE、GENERIC_READ、GENERIC_WRITE、DELETE打开此文件，并 WRITE_DAC 访问权限，以便它可以保留所有属性和 ACL。如果此操作失败，该函数会尝试使用 SYNCHRONIZE、GENERIC_READ、DELETE和 WRITE_DAC 访问权限打开文件。未指定共享模式。

[in, optional] lpBackupFileName

将用作 lpReplacedFileName 文件的备份副本的文件的名称。如果此参数 NULL，则不会创建备份文件。有关备份文件的实现详细信息，请参阅“备注”部分。

提示

[in] dwReplaceFlags

替换选项。此参数可以是以下一个或多个值。

价值	意义
REPLACEFILE_WRITE_THROUGH 0x00000001	不支持此值。
REPLACEFILE_IGNORE_MERGE_ERRORS 0x00000002	忽略将替换文件中的信息（如属性和 ACL）合并到替换文件时发生的错误。因此，如果指定此标志并且没有 WRITE_DAC 访问权限，则函数会成功，但不会保留 ACL。
REPLACEFILE_IGNORE_ACL_ERRORS 0x00000004	忽略将 ACL 信息从替换文件合并到替换文件时发生的错误。因此，如果指定此标志并且没有 WRITE_DAC 访问权限，则函数会成功，但不会保留 ACL。若要编译使用此值的应用程序，请将 _WIN32_WINNT 宏定义为0x0600或更高版本。 Windows Server 2003 和 Windows XP：不支持此值。

lpExclude

保留以供将来使用。

lpReserved

保留以供将来使用。

返回值

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

如果函数失败，则返回值为零。若要获取扩展的错误信息，请调用 GetLastError。下面是此函数的可能错误代码。

返回代码/值	描述
ERROR_UNABLE_TO_MOVE_REPLACEMENT 1176 （0x498）	无法重命名替换文件。如果指定了 lpBackupFileName，则替换和替换文件将保留其原始文件名。否则，替换的文件不再存在，替换文件位于其原始名称下。
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 1177 （0x499）	无法移动替换文件。替换文件仍位于其原始名称下;但是，它从它替换的文件继承了文件流和属性。要替换的文件仍然存在，名称不同。如果指定了 lpBackupFileName，它将是替换文件的名称。
ERROR_UNABLE_TO_REMOVE_REPLACED 1175 （0x497）	无法删除替换的文件。替换文件和替换文件保留其原始文件名。

如果返回任何其他错误（如 ERROR_INVALID_PARAMETER），则替换的文件和替换文件将保留其原始文件名。在此方案中，备份文件不存在，并且不能保证替换文件将继承已替换文件的所有属性和流。

言论

提示从 Windows 10 版本 1607 开始，对于此函数的 unicode 版本（ReplaceFileW），可以选择加入以删除 MAX_PATH 限制。有关详细信息，请参阅命名文件、路径和命名空间的“最大路径长度限制”部分。

ReplaceFile 函数将单个函数中的几个步骤组合在一起。应用程序可以调用 ReplaceFile，而不是调用单独的函数将数据保存到新文件，使用临时名称重命名原始文件，重命名新文件以具有与原始文件相同的名称，并删除原始文件。另一个优点是，ReplaceFile 不仅复制新文件数据，而且还保留原始文件的以下属性：

创建时间
短文件名
对象标识符
DACL
安全资源属性
加密
压缩
替换文件中尚未命名的流

例如，如果替换文件已加密，但已替换的文件未加密，则生成的文件不会加密。

Windows 7、Windows Server 2008 R2、Windows Server 2008、Windows Vista、Windows Server 2003 和 Windows XP ：在 Windows 8 和 Windows Server 2012 之前，不会保留原始文件的安全资源属性（ATTRIBUTE_SECURITY_INFORMATION）。

注释

如果使用选择性擦除保护替换文件，则替换的文件将由替换文件的企业 ID 进行保护。

生成的文件与替换文件具有相同的文件 ID。

备份文件、替换的文件和替换文件必须全部驻留在同一卷上。

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

注意

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

要求

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