replaceFileW 函数 (winbase.h)

项目
03/09/2024

使用创建原始文件备份副本的选项将一个文件替换为另一个文件。替换文件采用被替换文件的名称及其标识。

语法

BOOL ReplaceFileW(
  [in]           LPCWSTR lpReplacedFileName,
  [in]           LPCWSTR lpReplacementFileName,
  [in, optional] LPCWSTR 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
安全资源属性
Encryption
压缩
已命名流不在替换文件中

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

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。

备份文件、替换文件和替换文件必须都位于同一卷上。

若要删除或重命名文件，必须具有对文件的删除权限或父目录中的删除子权限。如果设置了除 delete 和 delete 子级以外的所有访问权限的目录，并且新文件的 DACL 均继承，则应该能够创建文件而不删除该文件。但是，你可以随后创建一个文件，你将获得在创建文件时返回的句柄上请求的所有访问权限。如果在创建文件时请求了删除权限，则可以使用该句柄删除或重命名文件，但不能使用该句柄重命名该文件。

注意

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

要求

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

另请参阅

通过

replaceFileW 函数 (winbase.h)

语法

参数

返回值

注解

要求

另请参阅

反馈

其他资源