Função ReplaceFileA (winbase.h)

Artigo
11/20/2024

Substitui um arquivo por outro arquivo, com a 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 MAX_PATH caracteres. Para estender esse limite para 32.767 caracteres de largura, acrescente "\\?\" ao caminho. Para obter mais informações, consulte Arquivos de Nomenclatura, Caminhos e Namespaces.

Ponta

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 do comprimento do caminho" de arquivos de nomenclatura, caminhos e namespaces para obter detalhes.

Esse arquivo é aberto com os direitos de acesso GENERIC_READ, DELETEe 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 de Segurança de Arquivos e Direitos de Acesso.

[in] lpReplacementFileName

O nome do arquivo que substituirá o arquivo lpReplacedFileName.

Ponta

A função tenta abrir esse arquivo com o SYNCHRONIZE, GENERIC_READ, GENERIC_WRITE, DELETEe WRITE_DAC direitos de acesso 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, DELETEe 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 no arquivo de backup.

Ponta

[in] dwReplaceFlags

As opções de substituição. Esse parâmetro pode ser um ou mais 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: Esse valor não tem suporte.

lpExclude

Reservado para uso futuro.

lpReserved

Reservado para uso futuro.

Valor de retorno

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

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

Código/valor de retorno	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 em 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 em 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.

Observações

Dica Começando com o 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 do 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 do 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
Encriptação
Compressã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: Atributos de recursos de segurança (ATTRIBUTE_SECURITY_INFORMATION) para o arquivo original não serão preservados até o Windows 8 e o Windows Server 2012.

de Observação

Se o arquivo de substituição estiver protegido usando de 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 e 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.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	winbase.h (inclua Windows.h)
biblioteca	Kernel32.lib
de DLL	Kernel32.dll

Consulte também

CopyFile

CopyFileEx

Funções de gerenciamento de arquivos

movefile

MoveFileEx

MoveFileWithProgress

Compartilhar via

Função ReplaceFileA (winbase.h)

Sintaxe

Parâmetros

Valor de retorno

Observações

Requisitos

Consulte também

Comentários

Recursos adicionais