Edit

Share via

ReplaceFileFromAppW function (fileapifromapp.h)

  • Article

Replaces one file with another file, with the option of creating a backup copy of the original file. The behavior of this function is identical to ReplaceFile, except that this function adheres to the Universal Windows Platform app security model.

Syntax

WINSTORAGEAPI BOOL ReplaceFileFromAppW(
  LPCWSTR lpReplacedFileName,
  LPCWSTR lpReplacementFileName,
  LPCWSTR lpBackupFileName,
  DWORD   dwReplaceFlags,
  LPVOID  lpExclude,
  LPVOID  lpReserved
) noexcept;

Parameters

lpReplacedFileName

For information about opting out of the MAX_PATH limitation without prepending "\\?\", see the "Maximum Path Length Limitation" section of Naming Files, Paths, and Namespaces for details.

This file is opened with the GENERIC_READ, DELETE, and SYNCHRONIZE access rights. The sharing mode is FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

The caller must have write access to the file to be replaced. For more information, see File Security and Access Rights.

lpReplacementFileName

The name of the file that will replace the lpReplacedFileName file.

For information about opting out of the MAX_PATH limitation without prepending "\\?\", see the "Maximum Path Length Limitation" section of Naming Files, Paths, and Namespaces for details.

The function attempts to open this file with the SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETE, and WRITE_DAC access rights so that it can preserve all attributes and ACLs. If this fails, the function attempts to open the file with the SYNCHRONIZE, GENERIC_READ, DELETE, and WRITE_DAC access rights. No sharing mode is specified.

lpBackupFileName

The name of the file that will serve as a backup copy of the lpReplacedFileName file. If this parameter is NULL, no backup file is created. See the Remarks section for implementation details on the backup file.

For information about opting out of the MAX_PATH limitation without prepending "\\?\", see the "Maximum Path Length Limitation" section of Naming Files, Paths, and Namespaces for details.

dwReplaceFlags

The replacement options. This parameter can be one or more of the following values.

Value Meaning
REPLACEFILE_WRITE_THROUGH 0x00000001

This value is not supported.
REPLACEFILE_IGNORE_MERGE_ERRORS 0x00000002

Ignores errors that occur while merging information (such as attributes and ACLs) from the replaced file to the replacement file. Therefore, if you specify this flag and do not have WRITE_DAC access, the function succeeds but the ACLs are not preserved.
REPLACEFILE_IGNORE_ACL_ERRORS 0x00000004

Ignores errors that occur while merging ACL information from the replaced file to the replacement file. Therefore, if you specify this flag and do not have WRITE_DAC access, the function succeeds but the ACLs are not preserved. To compile an application that uses this value, define the _WIN32_WINNT macro as 0x0600 or later.

lpExclude

Reserved for future use.

lpReserved

Reserved for future use.

Return value

If the function succeeds, the return value is nonzero.

If the function fails, the return value is zero. To get extended error information, call GetLastError. The following are possible error codes for this function.

Return code/value Description
ERROR_UNABLE_TO_MOVE_REPLACEMENT 1176 (0x498)

The replacement file could not be renamed. If lpBackupFileName was specified, the replaced and replacement files retain their original file names. Otherwise, the replaced file no longer exists and the replacement file exists under its original name.
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 1177 (0x499)

The replacement file could not be moved. The replacement file still exists under its original name; however, it has inherited the file streams and attributes from the file it is replacing. The file to be replaced still exists with a different name. If lpBackupFileName is specified, it will be the name of the replaced file.
ERROR_UNABLE_TO_REMOVE_REPLACED 1175 (0x497)

The replaced file could not be deleted. The replaced and replacement files retain their original file names.

 

If any other error is returned, such as ERROR_INVALID_PARAMETER, the replaced and replacement files will retain their original file names. In this scenario, a backup file does not exist and it is not guaranteed that the replacement file will have inherited all of the attributes and streams of the replaced file.

Requirements

Requirement Value
Minimum supported client Windows 10, version 1803
Header fileapifromapp.h