Função CopyFileW (winbase.h)

Artigo
11/20/2024

Copia um arquivo existente para um novo arquivo.

A função CopyFileEx fornece dois recursos adicionais. CopyFileEx pode chamar uma função de retorno de chamada especificada sempre que uma parte da operação de cópia for concluída e CopyFileEx puder ser cancelada durante a operação de cópia.

Para executar essa operação como uma operação transacionada, use a função CopyFileTransacted.

Sintaxe

BOOL CopyFileW(
  [in] LPCWSTR lpExistingFileName,
  [in] LPCWSTR lpNewFileName,
  [in] BOOL    bFailIfExists
);

Parâmetros

[in] lpExistingFileName

O nome de um arquivo existente.

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.

Se lpExistingFileName não existir, CopyFile falhará e GetLastError retornará ERROR_FILE_NOT_FOUND.

[in] lpNewFileName

O nome do novo arquivo.

Ponta

[in] bFailIfExists

Se esse parâmetro for verdadeiro e o novo arquivo especificado por lpNewFileName já existir, a função falhará. Se esse parâmetro for FALSE e o novo arquivo já existir, a função substituirá o arquivo existente e terá êxito.

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.

Observações

As propriedades do recurso de segurança (ATTRIBUTE_SECURITY_INFORMATION) do arquivo existente são copiadas para o novo arquivo.

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: As propriedades de recurso de segurança do arquivo existente não serão copiadas para o novo arquivo até o Windows 8 e o Windows Server 2012.

Os atributos de arquivo para o arquivo existente são copiados para o novo arquivo. Por exemplo, se um arquivo existente tiver o atributo de arquivo FILE_ATTRIBUTE_READONLY, uma cópia criada por meio de uma chamada para CopyFile também terá o atributo de arquivo FILE_ATTRIBUTE_READONLY. Para obter mais informações, consulte Recuperação e alteração de atributos de arquivo.

Essa função falhará com ERROR_ACCESS_DENIED se o arquivo de destino já existir e tiver o FILE_ATTRIBUTE_HIDDEN ou FILE_ATTRIBUTE_READONLY conjunto de atributos.

Quando CopyFile é usado para copiar um arquivo criptografado, ele tenta criptografar o arquivo de destino com as chaves usadas na criptografia do arquivo de origem. Se isso não puder ser feito, essa função tentará criptografar o arquivo de destino com chaves padrão. Se nenhum desses métodos puder ser feito, CopyFile falhará com um código de erro ERROR_ENCRYPTION_FAILED.

Comportamento simbólico do link – se o arquivo de origem for um link simbólico, o arquivo real copiado será o destino do link simbólico.

Se o arquivo de destino já existir e for um link simbólico, o destino do link simbólico será substituído pelo arquivo de origem.

No Windows 8 e no Windows Server 2012, essa função é compatível com as tecnologias a seguir.

Tecnologia	Suportado
Protocolo SMB (Bloco de Mensagens do Servidor) 3.0	Sim
TFO (Failover Transparente) do SMB 3.0	Sim
SMB 3.0 com Compartilhamentos de Arquivos de Expansão (SO)	Sim
Sistema de Arquivos de Volume Compartilhado de Cluster (CsvFS)	Sim
ReFS (Sistema de Arquivos Resiliente)	Sim

Exemplos

Para obter um exemplo, consulte Recuperar e alterar atributos de arquivo.

Nota

O cabeçalho winbase.h define CopyFile 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

CopyFileEx

CopyFileTransacted

CreateFile

constantes de atributo de arquivo

Funções de gerenciamento de arquivos

movefile

links simbólicos

Compartilhar via