Função MoveFileExA (winbase.h)

Artigo
06/27/2024

Move um arquivo ou diretório existente, incluindo seus filhos, com várias opções de movimentação.

A função MoveFileWithProgress é equivalente à função MoveFileEx, exceto que MoveFileWithProgress permite que você forneça uma função de retorno de chamada que receba notificações de progresso.

Para executar essa operação como uma operação transacionada, use a função MoveFileTransacted.

Sintaxe

BOOL MoveFileExA(
  [in]           LPCSTR lpExistingFileName,
  [in, optional] LPCSTR lpNewFileName,
  [in]           DWORD  dwFlags
);

Parâmetros

[in] lpExistingFileName

O nome atual do arquivo ou diretório no computador local.

Se dwFlags especificar MOVEFILE_DELAY_UNTIL_REBOOT, o arquivo não poderá existir em um compartilhamento remoto, pois as operações atrasadas são executadas antes que a rede esteja disponível.

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] lpNewFileName

O novo nome do arquivo ou diretório no computador local.

Ao mover um arquivo, o destino pode estar em um sistema de arquivos ou volume diferente. Se o destino estiver em outra unidade, você deverá definir o sinalizador MOVEFILE_COPY_ALLOWED em dwFlags.

Ao mover um diretório, o destino deve estar na mesma unidade.

Se dwFlags especificar MOVEFILE_DELAY_UNTIL_REBOOT e lpNewFileName NULL, MoveFileEx registrará o arquivo lpExistingFileName a ser excluído quando o sistema for reiniciado. Se lpExistingFileName se referir a um diretório, o sistema removerá o diretório na reinicialização somente se o diretório estiver vazio.

Ponta

[in] dwFlags

Esse parâmetro pode ser um ou mais dos valores a seguir.

Valor	Significado
MOVEFILE_COPY_ALLOWED 2 (0x2)	Se o arquivo for 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.
MOVEFILE_FAIL_IF_NOT_TRACKABLE 32 (0x20)	A função falhará se o arquivo de origem for uma fonte de link, mas o arquivo não poderá ser rastreado após a movimentação. Essa situação poderá ocorrer se o destino for um volume formatado com o sistema de arquivos FAT.
MOVEFILE_REPLACE_EXISTING 1 (0x1)	Se houver um arquivo chamado lpNewFileName, a função substituirá seu conteúdo pelo conteúdo do arquivo lpExistingFileName , desde que os requisitos de segurança relacionados às ACLs (listas de controle de acesso) sejam atendidos. Para obter mais informações, consulte a seção Comentários deste tópico. Se lpNewFileName nomear um diretório existente, um erro será relatado.
MOVEFILE_WRITE_THROUGH 8 (0x8)	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.

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 (0). Para obter informações de erro estendidas, chame GetLastError.

Observações

Se o parâmetro dwFlags especificar MOVEFILE_DELAY_UNTIL_REBOOT, MoveFileEx falhará se não puder acessar o registro. A função armazena 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:

szSrcFile\0\0
szSrcFile\0szDstFile\0

A cadeia de caracteres szSrcFile\0\0 indica que o arquivo szSrcFile deve ser excluído na reinicialização. A cadeia de caracteres szSrcFile\0szDstFile\0 indica que szSrcFile deve ser renomeado szDstFile na reinicialização.

Observação 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. Por exemplo, o fragmento de código a seguir cria entradas de registro que excluem szSrcFile e renomeiem szSrcFile para serem szDstFile na reinicialização:

MoveFileEx(szSrcFile, NULL, MOVEFILE_DELAY_UNTIL_REBOOT);
MoveFileEx(szSrcFile, szDstFile, MOVEFILE_DELAY_UNTIL_REBOOT);

Como as operações reais de movimentação e exclusão especificadas com o sinalizador MOVEFILE_DELAY_UNTIL_REBOOT ocorrem depois que o aplicativo de chamada deixou de ser executado, o valor retornado não pode refletir o êxito ou a falha na movimentação ou exclusão do arquivo. Em vez disso, isso reflete o êxito ou falha ao colocar as entradas apropriadas no registro.

O sistema exclui um diretório marcado para exclusão com o sinalizador MOVEFILE_DELAY_UNTIL_REBOOT somente se ele estiver vazio. Para garantir a exclusão de diretórios, mova ou exclua todos os arquivos do diretório antes de tentar excluí-lo. Os arquivos podem estar no diretório no momento da inicialização, mas devem ser excluídos ou movidos antes que o sistema possa excluir o diretório.

As operações de movimentação e exclusão são realizadas no momento da inicialização na mesma ordem especificada no aplicativo de chamada. Para excluir um diretório que tenha arquivos no momento da inicialização, primeiro exclua os arquivos.

Se um arquivo for movido entre volumes, MoveFileEx 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.

A função MoveFileEx coordena sua operação com o o controle de link serviço, para que as fontes de link possam ser rastreadas à medida que são movidas.

Para excluir ou renomear um arquivo, você deve ter permissão de exclusão no arquivo ou excluir a permissão filho no diretório pai. Se você configurar um diretório com todo o acesso, exceto excluir e excluir filho e as ACLs de novos arquivos forem herdadas, você poderá criar um arquivo sem poder excluí-lo. No entanto, você pode criar um arquivo e obter todo o acesso solicitado no identificador que é retornado a você no momento em que você cria o arquivo. Se você solicitar permissão de exclusão no momento em que criar o arquivo, poderá excluir ou renomear o arquivo com esse identificador, mas não com qualquer outro identificador. Para obter mais informações, consulte de Segurança de Arquivos e Direitos de Acesso.

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	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 de Cluster (CsvFS)	Sim
ReFS (Sistema de Arquivos Resiliente)	Sim

Exemplos

Para obter um exemplo, consulte Criando e usando um arquivo temporário.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows XP [aplicativos da área de trabalho \| Aplicativos UWP]
servidor com suporte mínimo	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
da Plataforma de Destino	Windows
cabeçalho	winbase.h (inclua Windows.h)
biblioteca	Kernel32.lib
de DLL	Kernel32.dll

Consulte também

CopyFile

DeleteFile

Funções de gerenciamento de arquivos

de Direitos de Acesso e Segurança de Arquivos

GetWindowsDirectory

MoveFileTransacted

MoveFileWithProgress

WritePrivateProfileString

Compartilhar via