Função ReplaceFileFromAppW (fileapifromapp.h)

Artigo
08/23/2023

Substitui um arquivo por outro arquivo, com a opção de criar uma cópia de backup do arquivo original. O comportamento dessa função é idêntico a ReplaceFile, exceto que essa função segue o modelo de segurança do aplicativo Plataforma Universal do Windows.

Sintaxe

WINSTORAGEAPI BOOL ReplaceFileFromAppW(
  LPCWSTR lpReplacedFileName,
  LPCWSTR lpReplacementFileName,
  LPCWSTR lpBackupFileName,
  DWORD   dwReplaceFlags,
  LPVOID  lpExclude,
  LPVOID  lpReserved
) noexcept;

Parâmetros

lpReplacedFileName

Para obter informações sobre como recusar 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, 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 arquivo e direitos de acesso.

lpReplacementFileName

O nome do arquivo que substituirá o arquivo lpReplacedFileName .

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.

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.

dwReplaceFlags

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

Valor	Significado
0x00000001 REPLACEFILE_WRITE_THROUGH	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 durante a mesclagem de informações de ACL 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. Para compilar um aplicativo que usa esse valor, defina a macro _WIN32_WINNT como 0x0600 ou posterior.

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 possíveis códigos de erro para essa função.

Valor/código retornado	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)	Não foi possível excluir o arquivo substituí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.

Requisitos


Cliente mínimo com suporte	Windows 10, versão 1803
Cabeçalho	fileapifromapp.h

Share via