Partilhar via

Função ReplaceFileFromAppW (fileapifromapp.h)

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 ao ReplaceFile, exceto pelo fato de que essa função adere ao modelo de segurança de aplicativo da 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 de Segurança de Arquivos e Direitos de Acesso.

lpReplacementFileName

O nome do arquivo que substituirá o arquivo 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.

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 no arquivo de backup.

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.

dwReplaceFlags

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

Value Meaning
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.

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 Description
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.

Requirements

Requirement Value
Cliente mínimo suportado Windows 10, versão 1803
Header fileapifromapp.h
Library OneCore.Lib
  • Last updated on