Função MoveFileTransactedA (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, confira Alternativas ao uso do NTFS transacional.]
Move um arquivo ou um diretório existente, incluindo os filhos dele, como uma operação transacionada.
Sintaxe
BOOL MoveFileTransactedA(
[in] LPCSTR lpExistingFileName,
[in, optional] LPCSTR lpNewFileName,
[in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
[in, optional] LPVOID lpData,
[in] DWORD dwFlags,
[in] HANDLE hTransaction
);
Parâmetros
[in] lpExistingFileName
O nome atual do arquivo ou diretório existente no computador local.
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] lpNewFileName
O novo nome para o arquivo ou diretório. O novo nome ainda não deve existir. Um novo arquivo pode estar em um sistema de arquivos ou unidade diferente. Um novo diretório precisa estar na mesma unidade.
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
Um ponteiro para uma função de retorno de chamada CopyProgressRoutine que é chamada sempre que outra parte do arquivo é movida. A função de retorno de chamada poderá ser útil se você fornecer uma interface do usuário que exiba o progresso da operação. Este parâmetro pode ser NULL.
[in, optional] lpData
Um argumento a ser passado para a função de retorno de chamada CopyProgressRoutine . Este parâmetro pode ser NULL.
[in] dwFlags
As opções de movimentação. Esse parâmetro pode usar um dos valores a seguir.
| Valor | Significado |
|---|---|
|
Se o arquivo deve ser movido para um volume diferente, a função simula a movimentação usando as funções CopyFile e DeleteFile .
Se o arquivo for copiado com êxito para um volume diferente e o arquivo original não puder ser excluído, a função terá êxito em deixar o arquivo de origem intacto. Esse valor não pode ser usado com MOVEFILE_DELAY_UNTIL_REBOOT. |
|
Reservado para uso futuro. |
|
O sistema não move o arquivo até que o sistema operacional seja reiniciado. O sistema move o arquivo imediatamente após a execução do AUTOCHK, mas antes de criar arquivos de paginação. Consequentemente, esse parâmetro permite que a função exclua arquivos de paginação de inicializações anteriores.
Esse valor só poderá ser usado se o processo estiver no contexto de um usuário que pertence ao grupo de administradores ou à conta LocalSystem. Esse valor não pode ser usado com MOVEFILE_COPY_ALLOWED. A operação de gravação no valor do Registro, conforme detalhado na seção Comentários, é o que é transacionado. A movimentação do arquivo é concluída quando o computador é reiniciado, após a conclusão da transação. |
|
Se existir um arquivo chamado lpNewFileName , a função substituirá seu conteúdo pelo conteúdo do arquivo lpExistingFileName .
Esse valor não poderá ser usado se lpNewFileName ou lpExistingFileName nomear um diretório. |
|
Uma chamada para MoveFileTransacted significa que a operação de movimentação de arquivo é concluída quando a operação de confirmação é concluída. Esse sinalizador é desnecessário; não haverá nenhum efeito negativo se esse sinalizador for especificado, além de uma lentidão de operação. A função não retorna até que o arquivo seja realmente movido no disco.
Definir esse valor garante que uma movimentação executada como uma operação de cópia e exclusão seja liberada para o disco antes que a função retorne. A liberação ocorre no final da operação de cópia. Esse valor não terá efeito se MOVEFILE_DELAY_UNTIL_REBOOT estiver definido. |
[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.
Ao mover um arquivo entre volumes, se lpProgressRoutine retornar PROGRESS_CANCEL devido ao usuário cancelar a operação, MoveFileTransacted retornará zero e GetLastError retornará ERROR_REQUEST_ABORTED. O arquivo existente é deixado intacto.
Ao mover um arquivo entre volumes, se lpProgressRoutine retornar PROGRESS_STOP devido ao usuário interromper a operação, MoveFileTransacted retornará zero e GetLastError retornará ERROR_REQUEST_ABORTED. O arquivo existente é deixado intacto.
Comentários
Se o parâmetro dwFlagsespecificar MOVEFILE_DELAY_UNTIL_REBOOT, MoveFileTransacted falhará se não puder acessar o registro. A função armazena transacionalmente os locais dos arquivos a serem renomeados na reinicialização no seguinte valor do Registro: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\PendingFileRenameOperations
Esse valor do Registro é do tipo REG_MULTI_SZ. Cada operação de renomeação armazena uma das seguintes cadeias de caracteres terminadas em NULL, dependendo se a renomeação é uma exclusão ou não:
szDstFile\0\0
szSrcFile\0szDstFile\0
A cadeia de caracteres szDstFile\0\0 indica que o arquivo szDstFile deve ser excluído na reinicialização.
A cadeia de caracteres szSrcFile\0szDstFile\0 indica que szSrcFile deve ser renomeado szDstFile na reinicialização.
Se um arquivo for movido entre volumes, MoveFileTransacted não moverá o descritor de segurança com o arquivo. O arquivo recebe o descritor de segurança padrão no diretório de destino.
Essa função sempre falhará se você especificar o sinalizador MOVEFILE_FAIL_IF_NOT_TRACKABLE ; não há suporte para o rastreamento pelo TxF.
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 | No |
| TFO (Failover transparente) do SMB 3.0 | No |
| SMB 3.0 com compartilhamentos de arquivos de expansão (SO) | No |
| Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS) | No |
| ReFS (Sistema de Arquivos Resiliente) | No |
O SMB 3.0 não dá suporte a TxF.
Requisitos
| Requisito | Valor |
|---|---|
| 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 |