Função CopyFile2 (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.
Sintaxe
HRESULT CopyFile2(
[in] PCWSTR pwszExistingFileName,
[in] PCWSTR pwszNewFileName,
[in, optional] COPYFILE2_EXTENDED_PARAMETERS *pExtendedParameters
);
Parâmetros
[in] pwszExistingFileName
O nome de um arquivo existente.
Para estender esse limite para 32.767 caracteres largos, acrescente "\?" ao caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND).
[in] pwszNewFileName
O nome do novo arquivo.
Para estender esse limite para 32.767 caracteres largos, acrescente "\?" ao caminho. Para obter mais informações, confira Nomear arquivos, caminhos e namespaces.
[in, optional] pExtendedParameters
Endereço opcional de uma estrutura COPYFILE2_EXTENDED_PARAMETERS .
Valor retornado
Se a função for bem-sucedida, o valor retornado retornará TRUE quando passado para a macro SUCCEEDED .
| Código de retorno | Descrição |
|---|---|
|
A operação de cópia foi concluída com êxito. |
|
A operação de cópia foi pausada por um retorno COPYFILE2_PROGRESS_PAUSE da função de retorno de chamada CopyFile2ProgressRoutine . |
|
A operação de cópia foi pausada por uma COPYFILE2_PROGRESS_CANCEL ou COPYFILE2_PROGRESS_STOP retorno da função de retorno de chamada CopyFile2ProgressRoutine . |
|
O membro dwCopyFlags da estrutura COPYFILE2_EXTENDED_PARAMETERS passada pelo parâmetro pExtendedParameters contém o sinalizador COPY_FILE_FAIL_IF_EXISTS e um nome conflitante existia. |
|
O membro dwCopyFlags da estrutura COPYFILE2_EXTENDED_PARAMETERS passada pelo parâmetro pExtendedParameters contém o sinalizador COPY_FILE_FAIL_IF_EXISTS e um nome conflitante existia. |
Comentários
Essa função preserva atributos estendidos, armazenamento estruturado OLE, fluxos de dados alternativos do sistema de arquivos NTFS e atributos de arquivo. Os atributos de segurança para o arquivo existente não são copiados para o novo arquivo. Para copiar atributos de segurança, use a função SHFileOperation .
Essa função falhará com HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED) se o arquivo de destino já existir e tiver o FILE_ATTRIBUTE_HIDDEN ou FILE_ATTRIBUTE_READONLY atributo definido.
Para compilar um aplicativo que usa essa função, defina a macro _WIN32_WINNT como _WIN32_WINNT_WIN8 ou posterior. Para obter mais informações, consulte Usando os cabeçalhos do Windows.
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 |
A partir do Windows 10, versão 1903 e Windows Server 2022, há suporte para um novo valor, COPY_FILE_REQUEST_COMPRESSED_TRAFFIC, no campo dwCopyFlags da estrutura COPYFILE2_EXTENDED_PARAMETERS passada no argumento pExtendedParameters para essa função. Esse novo valor solicita que o canal de transferência subjacente compacte os dados durante a operação de cópia. A solicitação pode não ter suporte para todos os meios, caso em que ela é ignorada. Os atributos e parâmetros de compactação (complexidade computacional, uso de memória) não são configuráveis por meio dessa API e estão sujeitos a alterações entre diferentes versões do sistema operacional. No Windows 10, o sinalizador tem suporte para arquivos que residem em compartilhamentos SMB, em que a versão do protocolo SMB negociada é SMB v3.1.1 ou superior.
Requisitos
| Cliente mínimo com suporte | Windows 8 [aplicativos da área de trabalho | Aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2012 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbase.h (incluir Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |