Função CopyFileTransactedA (winbase.h)
[A Microsoft recomenda fortemente que os desenvolvedores utilizem meios alternativos para atender às necessidades do seu aplicativo. Muitos cenários para os quais o TxF foi desenvolvido podem ser obtidos por meio de técnicas mais simples e prontamente disponíveis. Além disso, o TxF pode não estar disponível em versões futuras do Microsoft Windows. Para obter mais informações e alternativas ao TxF, consulte Alternativas ao uso do NTFS transacional.]
Copia um arquivo existente para um novo arquivo como uma operação transacionada, notificando o aplicativo de seu progresso por meio de uma função de retorno de chamada.
Sintaxe
BOOL CopyFileTransactedA(
[in] LPCSTR lpExistingFileName,
[in] LPCSTR lpNewFileName,
[in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
[in, optional] LPVOID lpData,
[in, optional] LPBOOL pbCancel,
[in] DWORD dwCopyFlags,
[in] HANDLE hTransaction
);
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 largos, acrescente "\\?\" ao 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 do comprimento do caminho" de Arquivos de Nomenclatura, Caminhos e Namespaces para obter detalhes.>.
Se lpExistingFileName não existir, a função CopyFileTransacted falhará e a função GetLastError retornará ERROR_FILE_NOT_FOUND.
O arquivo deve residir no computador local; caso contrário, a função falhará e o último código de erro será definido como ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.
[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 largos, acrescente "\\?\" ao 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 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. 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.
[in] hTransaction
Um identificador para a transação. Esse identificador é retornado pela função CreateTransaction .
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, CopyFileTransacted 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, CopyFileTransacted retornará zero e GetLastError retornará ERROR_REQUEST_ABORTED. Nesse caso, o arquivo de destino parcialmente copiado é deixado intacto.
Se você tentar chamar essa função com um identificador para uma transação que já foi revertida, CopyFileTransacted retornará ERROR_TRANSACTION_NOT_ACTIVE ou ERROR_INVALID_TRANSACTION.
Comentários
Essa função preserva atributos estendidos, armazenamento estruturado OLE, fluxos de dados alternativos do sistema de arquivos NTFS, atributos de segurança e atributos de arquivo.
Windows 7, Windows Server 2008 R2, Windows Server 2008 e Windows Vista: Os atributos de recurso de segurança (ATTRIBUTE_SECURITY_INFORMATION) para o arquivo existente não são copiados para o novo arquivo até que Windows 8 e 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 atributo definido.
Não há suporte para arquivos criptografados no TxF.
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.
Não há suporte para o rastreamento de link no TxF.
Em Windows 8 e Windows Server 2012, essa função é compatível com as tecnologias a seguir.
| Tecnologia | Com suporte |
|---|---|
| Protocolo SMB 3.0 | Não |
| TFO (Failover Transparente) do SMB 3.0 | Não |
| SMB 3.0 com compartilhamentos de arquivos de expansão (SO) | Não |
| CsvFS (Sistema de Arquivos de Volume Compartilhado clusterizado) | Não |
| ReFS (Sistema de Arquivos Resiliente) | Não |
Observe que o SMB 3.0 não dá suporte a TxF.
Observação
O cabeçalho winbase.h define CopyFileTransacted 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
| Cliente mínimo com suporte | Windows Vista [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2008 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbase.h (incluir Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |
Confira também
Constantes de atributo de arquivo