Função CopyFileExW (winbase.h)
Copia um arquivo existente para um novo arquivo, notificando o aplicativo de seu progresso por meio de uma função de retorno de chamada.
Para executar essa operação como uma operação transacionada, use a função CopyFileTransacted.
Sintaxe
BOOL CopyFileExW(
[in] LPCWSTR lpExistingFileName,
[in] LPCWSTR lpNewFileName,
[in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
[in, optional] LPVOID lpData,
[in, optional] LPBOOL pbCancel,
[in] DWORD dwCopyFlags
);
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, a função CopyFileEx falhará e a função GetLastError retornará ERROR_FILE_NOT_FOUND.
[in] lpNewFileName
O nome do novo arquivo.
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.
[in, optional] lpProgressRoutine
O endereço de uma função de retorno de chamada do tipo LPPROGRESS_ROUTINE que é chamado sempre que outra parte do arquivo é copiada. Esse parâmetro pode ser NULL. Para obter mais informações sobre a função de retorno de chamada de progresso, consulte a função
[in, optional] lpData
O argumento a ser passado para a função de retorno de chamada. Esse parâmetro pode ser NULL.
[in, optional] pbCancel
Se esse sinalizador estiver definido como TRUE durante a operação de cópia, a operação será cancelada. Caso contrário, a operação de cópia continuará a ser concluída.
[in] dwCopyFlags
Sinalizadores que especificam como o arquivo deve ser copiado. Esse parâmetro pode ser uma combinação dos valores a seguir.
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 uma chamada de informações de erro estendida GetLastError .
Se lpProgressRoutine retornar PROGRESS_CANCEL devido ao usuário cancelar a operação, CopyFileEx retornará zero e GetLastError retornará ERROR_REQUEST_ABORTED. Nesse caso, o arquivo de destino parcialmente copiado é excluído.
Se lpProgressRoutine retornar PROGRESS_STOP devido ao usuário interromper a operação, CopyFileEx retornará zero e GetLastError retornará ERROR_REQUEST_ABORTED. Nesse caso, o arquivo de destino parcialmente copiado é deixado intacto.
Observações
Essa função preserva atributos estendidos, armazenamento estruturado OLE, fluxos de dados alternativos do sistema de arquivos NTFS, atributos de recurso de segurança e atributos de arquivo.
Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Atributos de recurso de segurança (ATTRIBUTE_SECURITY_INFORMATION) para o arquivo existente não serão copiados para o novo arquivo até o Windows 8 e o Windows Server 2012.
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.
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 arquivos criptografados são copiados usando CopyFileEx, a função 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 ambos os métodos não puderem ser feitos, CopyFileEx falhará com um código de erro ERROR_ENCRYPTION_FAILED. Se você quiser que CopyFileEx conclua a operação de cópia mesmo que o arquivo de destino não possa ser criptografado, inclua o COPY_FILE_ALLOW_DECRYPTED_DESTINATION como o valor do parâmetro dwCopyFlags em sua chamada para CopyFileEx.
Se COPY_FILE_COPY_SYMLINK for especificado, as seguintes regras se aplicarão:
- Se o arquivo de origem for um link simbólico, o link simbólico será copiado, não o arquivo de destino.
- Se o arquivo de origem não for um link simbólico, não haverá nenhuma alteração no comportamento.
- Se o arquivo de destino for um link simbólico existente, o link simbólico será substituído, não o arquivo de destino.
- Se COPY_FILE_FAIL_IF_EXISTS também for especificado e o arquivo de destino for um link simbólico existente, a operação falhará em todos os casos.
- Se COPY_FILE_FAIL_IF_EXISTS também for especificado e o arquivo de destino for um link simbólico existente, a operação falhará somente se o destino do link simbólico existir.
- Se COPY_FILE_FAIL_IF_EXISTS não for especificado, não haverá nenhuma alteração no comportamento.
Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 e Windows XP: Se você estiver escrevendo um aplicativo que esteja otimizando operações de cópia de arquivo em uma LAN, considere usar a função TransmitFile do Windows Sockets (Winsock). TransmitFile dá suporte a transferências de rede de alto desempenho e fornece uma interface simples para enviar o conteúdo de um arquivo para um computador remoto. Para usar TransmitFile, você deve escrever um aplicativo cliente Winsock que envia o arquivo do computador de origem, bem como um aplicativo de servidor Winsock que usa outras funções Winsock para receber o arquivo no computador remoto.
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 |
Nota
O cabeçalho winbase.h define CopyFileEx 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
constantes de atributo de arquivo
Funções de gerenciamento de arquivos
movefile