Функция ReplaceFile


Функция 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.

Смотри также 

Обзор Управление файламиФункции, используемые в управлении файлами, CopyFileCopyFileEx, 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. 

 Замечания по платформе

Не имеется

 

Назад в оглавление
На главную страницу
На оглавление справки

Hosted by uCoz