Функция ReplaceFileW (winbase.h)

Статья
06/02/2023

Заменяет один файл другим с возможностью создания резервной копии исходного файла. Файл замены предполагает имя замененного файла и его удостоверение.

Синтаксис

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 , чтобы сохранить все атрибуты и списки управления доступом. В случае сбоя функция пытается открыть файл с правами доступа SYNCHRONIZE, GENERIC_READ, DELETE и WRITE_DAC . Режим общего доступа не указан.

[in, optional] lpBackupFileName

Имя файла, который будет служить резервной копией файла lpReplacedFileName . Если этот параметр имеет значение NULL, файл резервной копии не создается. Сведения о реализации файла резервной копии см. в разделе Примечания.

Совет

[in] dwReplaceFlags

Варианты замены. Этот параметр может иметь одно или несколько из следующих значений.

Значение	Значение
REPLACEFILE_WRITE_THROUGH 0x00000001	Это значение не поддерживается.
REPLACEFILE_IGNORE_MERGE_ERRORS 0x00000002	Игнорирует ошибки, возникающие при объединении сведений (например, атрибутов и списков управления доступом) из замененного файла в файл замены. Таким образом, если вы укажете этот флаг и не имеете WRITE_DAC доступа, функция будет выполнена успешно, но списки управления доступом не сохраняются.
REPLACEFILE_IGNORE_ACL_ERRORS 0x00000004	Игнорирует ошибки, возникающие при объединении сведений ACL из замененного файла в файл замены. Таким образом, если вы укажете этот флаг и не имеете WRITE_DAC доступа, функция будет выполнена успешно, но списки управления доступом не сохраняются. Чтобы скомпилировать приложение, использующее это значение, определите макрос _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 для версии Юникод этой функции (ReplaceFileW) можно согласиться на удаление ограничения MAX_PATH. Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" статьи Именование файлов, путей и пространств имен .

Функция ReplaceFile объединяет несколько шагов в одной функции. Приложение может вызвать ReplaceFile вместо вызова отдельных функций для сохранения данных в новый файл, переименовать исходный файл, используя временное имя, переименовать новый файл с тем же именем, что и исходный файл, и удалить исходный файл. Еще одно преимущество заключается в том, что ReplaceFile не только копирует данные нового файла, но и сохраняет следующие атрибуты исходного файла:

Creation time (время создания)
Короткое имя файла
Идентификаторы объектов
Списки DACLs
Атрибуты ресурсов безопасности
Шифрование
Сжатие
Именованные потоки еще не находятся в файле замены

Например, если файл замены зашифрован, но замененный файл не зашифрован, результирующий файл не шифруется.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Атрибуты ресурсов безопасности (ATTRIBUTE_SECURITY_INFORMATION) для исходного файла не сохраняются до тех пор, пока не Windows 8 и Windows Server 2012.

Примечание

Если файл замены защищен с помощью выборочной очистки, замененный файл будет защищен корпоративным идентификатором замещающего файла.

Результирующий файл имеет тот же идентификатор, что и файл замены.

Файл резервной копии, замененный файл и файл замены должны находиться на одном томе.

Чтобы удалить или переименовать файл, необходимо иметь разрешение на удаление файла или удаление дочернего элемента в родительском каталоге. Если вы настроили каталог со всеми доступами, кроме удаления и удаления дочерних, а списки DACLS новых файлов наследуются, вы сможете создать файл, не удаляя его. Однако затем можно создать файл, и вы получите весь запрашиваемый доступ к дескриптору, возвращенный вам во время создания файла. Если вы запросили разрешение на удаление во время создания файла, вы можете удалить или переименовать файл с помощью этого дескриптора, но не с любым другим.

Примечание

Заголовок winbase.h определяет ReplaceFile как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора UNICODE. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [классические приложения \| Приложения UWP]
Минимальная версия сервера	Windows Server 2003 [классические приложения \| Приложения UWP]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll