Compartilhar via


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
MOVEFILE_COPY_ALLOWED
2 (0x2)
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.

MOVEFILE_CREATE_HARDLINK
16 (0x10)
Reservado para uso futuro.
MOVEFILE_DELAY_UNTIL_REBOOT
4 (0x4)
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.

MOVEFILE_REPLACE_EXISTING
1 (0x1)
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.

MOVEFILE_WRITE_THROUGH
8 (0x8)
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.

Nota Embora \0\0 tecnicamente não seja permitido em um nó REG_MULTI_SZ , ele pode porque o arquivo é considerado renomeado para um nome nulo.
 
O sistema usa essas entradas do Registro para concluir as operações na reinicialização na mesma ordem em que foram emitidas. Para obter mais informações sobre como usar o sinalizador MOVEFILE_DELAY_UNTIL_REBOOT , consulte MoveFileWithProgress.

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

Confira também

CopyFileTransacted

Funções de gerenciamento de arquivos

MoveFileWithProgress

NTFS transacional