Функция ReplaceFileA (winbase.h)
Заменяет один файл другим файлом с возможностью создания резервной копии исходного файла. Файл замены предполагает имя замененного файла и его удостоверение.
Синтаксис
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и ПРАВ доступа СИНХРОНИЗАЦИИ. Режим общего доступа FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
Вызывающий объект должен иметь доступ на запись к файлу для замены. Дополнительные сведения см. в права доступа и безопасности файлов.
[in] lpReplacementFileName
Имя файла, заменяющего файл lpReplacedFileName.
По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 расширенных символов, добавьте "\\?\" в путь. Дополнительные сведения см. в именовании файлов, путей и пространств имен.
Кончик
Начиная с Windows 10 версии 1607, вы можете отказаться от ограничения MAX_PATH без предустановки "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" файлы именования, пути и пространства имен.
Функция пытается открыть этот файл с помощью SYNC, GENERIC_READ, GENERIC_WRITE, DELETEи WRITE_DAC прав доступа, чтобы сохранить все атрибуты и списки управления доступом. Если это не удается, функция пытается открыть файл с SYNCHRONIZE, GENERIC_READ, DELETEи WRITE_DAC права доступа. Режим общего доступа не указан.
[in, optional] lpBackupFileName
Имя файла, который будет служить резервной копией файла lpReplacedFileName. Если этот параметр null, файл резервной копии не создается. Дополнительные сведения о реализации файла резервного копирования см. в разделе "Примечания".
По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 расширенных символов, добавьте "\\?\" в путь. Дополнительные сведения см. в именовании файлов, путей и пространств имен.
Кончик
Начиная с Windows 10 версии 1607, вы можете отказаться от ограничения MAX_PATH без предустановки "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" файлы именования, пути и пространства имен.
[in] dwReplaceFlags
Параметры замены. Этот параметр может быть одним или несколькими из следующих значений.
lpExclude
Зарезервировано для дальнейшего использования.
lpReserved
Зарезервировано для дальнейшего использования.
Возвращаемое значение
Если функция выполнена успешно, возвращаемое значение ненулевое.
Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError. Ниже приведены коды ошибок для этой функции.
Возврат кода или значения | Описание |
---|---|
|
Не удалось переименовать файл замены. Если указан lpBackupFileName, замененные и заменяющие файлы сохраняют свои исходные имена файлов. В противном случае замененный файл больше не существует, и файл замены существует под его исходным именем. |
|
Не удалось переместить файл замены. Файл замены по-прежнему существует под исходным именем; однако он наследовал потоки файлов и атрибуты из файла, который он заменяет. Файл, который необходимо заменить, по-прежнему существует другим именем. Если указан lpBackupFileName, это будет имя замененного файла. |
|
Замененный файл не удалось удалить. Замененные и заменяющие файлы сохраняют свои исходные имена файлов. |
Если возвращается любая другая ошибка, например ERROR_INVALID_PARAMETER, замененные и заменяющие файлы будут хранить свои исходные имена файлов. В этом сценарии файл резервной копии не существует и не гарантируется, что файл замены наследует все атрибуты и потоки замененного файла.
Замечания
- Время создания
- Короткое имя файла
- Идентификатор объекта
- Списки управления доступом к файлам данных
- Атрибуты ресурсов безопасности
- Шифрование
- Сжатие
- Именованные потоки, которые еще не в файле замены
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 |