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.

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.

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

Requisitos

Confira também

CopyFile

CopyFileTransacted

CopyProgressRoutine

CreateFile

Constantes de atributo de arquivo

Funções de gerenciamento de arquivos

MoveFile

MoveFileWithProgress

Links simbólicos

Transmitfile