Функция ReplaceFile заменяет один файл другим, с параметром создания резервной копии первоначального файла. Файл замены принимает имя замененного файла и его идентичность.
Синтаксис
BOOL ReplaceFile( LPCTSTR lpReplacedFileName, // имя файла LPCTSTR lpReplacementFileName, // файл замены LPCTSTR lpBackupFileName, // дополнительный резервный файл DWORD dwReplaceFlags, // параметры замены LPVOID lpExclude, // зарезервированный LPVOID lpReserved // зарезервированный ); |
Параметры
lpReplacedFileName
[in]Указатель на символьную строку с нулем в конце, устанавливающую имя файла, который должен быть заменен файлом в параметре lpReplacementFileName .Этот файл открывается с правами доступа GENERIC_READ, DELETE и SYNCHRONIZE. Режимом совместного использования является FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.
Вызывающая программа должна иметь доступ для записи в заменяемый файл. Для получения дополнительной информации, см. статью Защита файла и права доступа.
lpReplacementFileName
[in] Указатель на символьную строку с нулем в конце, которая устанавливает имя заменяющего файла, определенного в параметре lpReplacedFileName.Функция пытается открыть этот файл с правами доступа SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETE и WRITE_DAC так, чтобы она могла сберечь все атрибуты и списки контроля доступа (ACL). Если функция завершается ошибкой, то она пытается открыть файл с с правами доступа SYNCHRONIZE, GENERIC_READ, DELETE и WRITE_DAC. Режим совместного использования не определяется.
lpBackupFileName
[in] Указатель на символьную строку с нулем в конце, устанавливающую имя файла, который будет служить резервной копией файла, определенного в lpReplacedFileName . Если этот параметр - ПУСТО (NULL), резервный файл не создается.dwReplaceFlags
[in] Параметры замены. Этот параметр может состоять из одного или нескольких нижеследующих значений.Значение | Предназначение |
---|---|
REPLACEFILE_WRITE_THROUGH | Гарантирует, что информация, скопированная из замененного файла сбрасывается на диск перед возвращениями значения функцией. |
REPLACEFILE_IGNORE_MERGE_ERRORS | Игнорирует ошибки, которые происходят при слиянии информации (такие как атрибуты и ACLы) замененного файла с файлом замены. Поэтому, если Вы устанавливаете этот флажок и не имеете доступа WRITE_DAC, функция завершается успешно, но списки контроля доступа (ACL) не сохраняются. |
lpExclude
Зарезервировано для будущего использования.lpReserved
Зарезервировано для будущего использования.Возвращаемые значения
Если функция завершается успешно, возвращаемое значение не нуль.
Если функция завершается ошибкой, возвращаемое значение равняется нулю. Чтобы получить дополнительную информацию об ошибке, вызовите GetLastError. Ниже перечислены возможные коды ошибок для этой функции.
Код ошибки | Значение |
---|---|
ERROR_UNABLE_TO_REMOVE_REPLACED | Замененный файл невозможно удалить. Замененный и заменяющий файлы сохраняют свои первоначальные имена. |
ERROR_UNABLE_TO_MOVE_REPLACEMENT | Файл замены невозможно переименовать. Если параметр lpBackupFileName был определен, замененный и заменяющий файлы сохраняют свои первоначальные имена. В противном случае, замененный файл больше не существует, а файл замены существует под его первоначальным названием. |
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 | Файл замены
невозможно переименовать. Он существует со своим первоначальным
именем, а замененный файл существует с
именем, определенным параметром lpBackupFileName. Эта ошибка происходит только в том случае, если lpBackupFileName - не ПУСТО (NULL). |
Если возвращается любая другая ошибка, типа ERROR_INVALID_PARAMETER, замененный и заменяющий файлы сохранят свои первоначальные имена. В этом сценарии, не гарантируется, что файл замены унаследует все атрибуты и потоки замененного файла и существование резервного файла.
Замечания
Функция ReplaceFile объединяет несколько шагов в пределах единственной функции. Приложение может вызвать ReplaceFile вместо вызова отдельных функций, чтобы сохранить данные в новом файле, переименовать первоначальный файл, используя временное имя, переименовать новый файл, чтобы иметь одно и то же название как и первоначальный файл и удалить первоначальный файл. Другое преимущество состоит в том, что функция ReplaceFile не только копирует новые данные файла, но также и сохраняет нижеследующие атрибуты первоначального файла:
Например, если файл замены зашифрован, а замененный файл не зашифрован, получающийся файл не зашифрован.
Резервный файл, замененный файл и файл замены должны все находиться на одном и том же томе.
Чтобы удалить или переименовать файл, Вы должны иметь или разрешение на удаление файла или разрешение на удаление потомков в родительском каталоге. Если Вы устанавливаете каталог с максимально возможным доступом, кроме удаления его самого и дочерних элементов, а списки разграничительного контроля доступа (DACLы) новых файлов унаследованы, то вы должны быть в состоянии создать файл, не будучи способными удалить его. Однако, Вы можете затем создать файл и получить весь доступ, который запрашиваете дескриптором, возвращенным Вам, когда создаете файл. Если Вы затребовали разрешение на удаление, когда создавали файл, то можете удалить или переименовать файл с этим дескриптором, но не с каким-либо другим.
Чтобы компилировать приложение, которое использует эту функцию, определите макрос _WIN32_WINNT как 0x0500 или позже. Для получения дополнительной информации, см. статью Использование заголовочных файлов SDK.
Смотри также
Обзор Управление файлами, Функции, используемые в управлении файлами, CopyFile, CopyFileEx, MoveFile, MoveFileEx, MoveFileWithProgress
Размещение и совместимость ReplaceFile |
||
К |
Windows XP |
Да |
л |
Windows 2000 Professional |
Да |
и |
Windows NT |
Нет |
е |
Windows Me |
Нет |
н |
Windows 98 |
Нет |
т |
Windows 95 |
Нет |
С |
Windows Server 2003 |
Да |
е | Windows 2000 Server | Да |
р | Windows NT Server | Нет |
в | ||
е | ||
р | ||
Используемая библиотека |
Kernel32.lib |
|
Используемая DLL | - | |
Заголовочный файл | ||
- объявлено в |
Winbase.h |
|
- включено в |
Windows.h |
|
Unicode |
Реализуется как версии Unicode и ANSI для Windows 2000/XP. |
|
Замечания по платформе |
Не имеется |