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

Статья
11/20/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и ПРАВ доступа СИНХРОНИЗАЦИИ. Режим общего доступа FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

Вызывающий объект должен иметь доступ на запись к файлу для замены. Дополнительные сведения см. в права доступа и безопасности файлов.

[in] lpReplacementFileName

Имя файла, заменяющего файл lpReplacedFileName.

Кончик

Функция пытается открыть этот файл с помощью SYNC, 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 не только копирует новые данные файла, но и сохраняет следующие атрибуты исходного файла:

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

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

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

Примечание

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

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

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

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

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [классические приложения \| Приложения UWP]
минимальный поддерживаемый сервер	Windows Server 2003 [классические приложения \| Приложения UWP]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll