Função ReplaceFileA (winbase.h)

Artigo
06/02/2023

Substitui um arquivo por outro arquivo, pela opção de criar uma cópia de backup do arquivo original. O arquivo de substituição pressupõe o nome do arquivo substituído e sua identidade.

Sintaxe

BOOL ReplaceFileA(
  [in]           LPCSTR lpReplacedFileName,
  [in]           LPCSTR lpReplacementFileName,
  [in, optional] LPCSTR lpBackupFileName,
  [in]           DWORD  dwReplaceFlags,
                 LPVOID lpExclude,
                 LPVOID lpReserved
);

Parâmetros

[in] lpReplacedFileName

O nome do arquivo a ser substituído.

Por padrão, o nome é limitado a caracteres MAX_PATH. Para estender esse limite para 32.767 caracteres largos, preencha "\\?\" para o caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.

Dica

A partir do Windows 10, versão 1607, você pode optar por remover a limitação de MAX_PATH sem acrescentar "\\?\". Consulte a seção "Limitação máxima de comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.

Esse arquivo é aberto com os direitos de acesso GENERIC_READ, DELETE e SYNCHRONIZE . O modo de compartilhamento é FILE_SHARE_READ | FILE_SHARE_WRITE | FILE_SHARE_DELETE.

O chamador deve ter acesso de gravação ao arquivo a ser substituído. Para obter mais informações, consulte Segurança de arquivos e Direitos de Acesso.

[in] lpReplacementFileName

O nome do arquivo que substituirá o arquivo lpReplacedFileName .

Dica

A função tenta abrir esse arquivo com os direitos de acesso SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETE e WRITE_DAC para que ele possa preservar todos os atributos e ACLs. Se isso falhar, a função tentará abrir o arquivo com os direitos de acesso SYNCHRONIZE, GENERIC_READ, DELETE e WRITE_DAC . Nenhum modo de compartilhamento é especificado.

[in, optional] lpBackupFileName

O nome do arquivo que servirá como uma cópia de backup do arquivo lpReplacedFileName . Se esse parâmetro for NULL, nenhum arquivo de backup será criado. Consulte a seção Comentários para obter detalhes de implementação sobre o arquivo de backup.

Dica

[in] dwReplaceFlags

As opções de substituição. Esse parâmetro pode usar um dos valores a seguir.

Valor	Significado
REPLACEFILE_WRITE_THROUGH 0x00000001	Não há suporte para esse valor.
REPLACEFILE_IGNORE_MERGE_ERRORS 0x00000002	Ignora erros que ocorrem durante a mesclagem de informações (como atributos e ACLs) do arquivo substituído para o arquivo de substituição. Portanto, se você especificar esse sinalizador e não tiver acesso WRITE_DAC , a função terá êxito, mas as ACLs não serão preservadas.
REPLACEFILE_IGNORE_ACL_ERRORS 0x00000004	Ignora erros que ocorrem ao mesclar informações de ACL do arquivo substituído ao arquivo de substituição. Portanto, se você especificar esse sinalizador e não tiver acesso WRITE_DAC , a função terá êxito, mas as ACLs não serão preservadas. Para compilar um aplicativo que usa esse valor, defina a macro _WIN32_WINNT como 0x0600 ou posterior. Windows Server 2003 e Windows XP: Não há suporte para esse valor.

lpExclude

Reservado para uso futuro.

lpReserved

Reservado para uso futuro.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError. Veja a seguir os possíveis códigos de erro para essa função.

Retornar código/valor	Descrição
ERROR_UNABLE_TO_MOVE_REPLACEMENT 1176 (0x498)	Não foi possível renomear o arquivo de substituição. Se lpBackupFileName tiver sido especificado, os arquivos substituídos e de substituição manterão seus nomes de arquivo originais. Caso contrário, o arquivo substituído não existe mais e o arquivo de substituição existe sob seu nome original.
ERROR_UNABLE_TO_MOVE_REPLACEMENT_2 1177 (0x499)	Não foi possível mover o arquivo de substituição. O arquivo de substituição ainda existe sob seu nome original; no entanto, herdou os fluxos de arquivo e os atributos do arquivo que está substituindo. O arquivo a ser substituído ainda existe com um nome diferente. Se lpBackupFileName for especificado, ele será o nome do arquivo substituído.
ERROR_UNABLE_TO_REMOVE_REPLACED 1175 (0x497)	O arquivo substituído não pôde ser excluído. Os arquivos substituídos e de substituição mantêm seus nomes de arquivo originais.

Se qualquer outro erro for retornado, como ERROR_INVALID_PARAMETER, os arquivos substituídos e de substituição manterão seus nomes de arquivo originais. Nesse cenário, um arquivo de backup não existe e não é garantido que o arquivo de substituição terá herdado todos os atributos e fluxos do arquivo substituído.

Comentários

Ponta A partir do Windows 10, versão 1607, para a versão unicode dessa função (ReplaceFileW), você pode optar por remover a limitação de MAX_PATH. Consulte a seção "Limitação máxima de comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.

A função ReplaceFile combina várias etapas em uma única função. Um aplicativo pode chamar ReplaceFile em vez de chamar funções separadas para salvar os dados em um novo arquivo, renomear o arquivo original usando um nome temporário, renomear o novo arquivo para ter o mesmo nome que o arquivo original e excluir o arquivo original. Outra vantagem é que ReplaceFile não apenas copia os novos dados de arquivo, mas também preserva os seguintes atributos do arquivo original:

Hora de criação
Nome do arquivo curto
Identificador de objeto
Dacls
Atributos de recurso de segurança
Criptografia
Compactação
Fluxos nomeados ainda não estão no arquivo de substituição

Por exemplo, se o arquivo de substituição for criptografado, mas o arquivo substituído não for criptografado, o arquivo resultante não será criptografado.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Os atributos de recurso de segurança (ATTRIBUTE_SECURITY_INFORMATION) para o arquivo original não são preservados até Windows 8 e Windows Server 2012.

Observação

Se o arquivo de substituição estiver protegido usando Apagamento Seletivo, o arquivo substituído será protegido pela ID corporativa do arquivo de substituição.

O arquivo resultante tem a mesma ID de arquivo que o arquivo de substituição.

O arquivo de backup, o arquivo substituído e o arquivo de substituição devem residir no mesmo volume.

Para excluir ou renomear um arquivo, você deve ter permissão de exclusão no arquivo ou excluir a permissão filho no diretório pai. Se você configurar um diretório com todo o acesso, exceto excluir filho e os DACLs de novos arquivos forem herdados, você poderá criar um arquivo sem poder excluí-lo. No entanto, você pode criar um arquivo e obterá todo o acesso solicitado no identificador retornado a você no momento em que criar o arquivo. Se você solicitou a permissão de exclusão no momento em que criou o arquivo, poderá excluir ou renomear o arquivo com esse identificador, mas não com qualquer outro.

Observação

O cabeçalho winbase.h define ReplaceFile como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos


Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| Aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	winbase.h (inclua Windows.h)
Biblioteca	Kernel32.lib
DLL	Kernel32.dll