Função CopyFileTransactedA (winbase.h)
[A Microsoft recomenda fortemente que os desenvolvedores utilizem meios alternativos para alcançar as necessidades do 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 para usar o 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 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 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 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.
[in] hTransaction
Um identificador para a transação. Esse identificador é retornado pela função
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, 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.
Observações
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: Atributos de recurso de segurança (ATTRIBUTE_SECURITY_INFORMATION) para o arquivo existente não são copiados 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.
Não há suporte para arquivos criptografados pelo 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 acompanhamento de link pelo TxF.
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 | Não |
| TFO (Failover Transparente) do SMB 3.0 | Não |
| SMB 3.0 com Compartilhamentos de Arquivos de Expansão (SO) | Não |
| Sistema de Arquivos de Volume Compartilhado de Cluster (CsvFS) | Não |
| ReFS (Sistema de Arquivos Resiliente) | Não |
Observe que o SMB 3.0 não dá suporte ao TxF.
Nota
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. 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 Vista [somente aplicativos da área de trabalho] |
| servidor com suporte mínimo | Windows Server 2008 [somente aplicativos da área de trabalho] |
| 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