Função CopyFileExA (winbase.h)
Copia um arquivo existente para um novo arquivo, notificando o aplicativo sobre 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 CopyFileExA(
[in] LPCSTR lpExistingFileName,
[in] LPCSTR 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 caracteres MAX_PATH. Para estender esse limite para 32.767 caracteres largos, preencha "\\?\" para o caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.
Dica
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 de 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 caracteres MAX_PATH. Para estender esse limite para 32.767 caracteres largos, preencha "\\?\" para o caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.
Dica
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 de 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. Este parâmetro pode ser NULL. Para obter mais informações sobre a função de retorno de chamada de progresso, consulte a função CopyProgressRoutine .
[in, optional] lpData
O argumento a ser passado para a função de retorno de chamada. Este parâmetro pode ser NULL.
[in, optional] pbCancel
Se esse sinalizador for 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 seguintes valores.
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.
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.
Comentários
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: Os atributos de recurso de segurança (ATTRIBUTE_SECURITY_INFORMATION) para o arquivo existente não são copiados para o novo arquivo até Windows 8 e Windows Server 2012.
As propriedades do recurso de segurança (ATTRIBUTE_SECURITY_INFORMATION) para o 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 são copiadas para o novo arquivo até Windows 8 e Windows Server 2012.
Essa função falhará com ERROR_ACCESS_DENIED se o arquivo de destino já existir e tiver o atributo FILE_ATTRIBUTE_HIDDEN ou FILE_ATTRIBUTE_READONLY definido.
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á 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á apenas se o destino do link simbólico existir.
- Se COPY_FILE_FAIL_IF_EXISTS não for especificado, não haverá 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 está otimizando operações de cópia de arquivo em uma LAN, considere usar a função TransmitFile do Windows Sockets (Winsock). O 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 o 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 Windows Server 2012, essa função é compatível com as tecnologias a seguir.
| Tecnologia | Com suporte |
|---|---|
| Protocolo SMB (SMB) 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 Clusterizado (CsvFS) | Sim |
| ReFS (Sistema de Arquivos Resiliente) | Sim |
Observação
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 de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbase.h (inclua Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
Confira também
Constantes de atributo de arquivo