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 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 .
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 sobre o 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 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 |