Função MoveFileWithProgressA (winbase.h)
Move um arquivo ou diretório, incluindo seus filhos. Você pode fornecer uma função de retorno de chamada que recebe notificações de progresso.
Para executar essa operação como uma operação transacionada, use a função MoveFileTransacted .
Sintaxe
BOOL MoveFileWithProgressA(
[in] LPCSTR lpExistingFileName,
[in, optional] LPCSTR lpNewFileName,
[in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
[in, optional] LPVOID lpData,
[in] DWORD dwFlags
);
Parâmetros
[in] lpExistingFileName
O nome do arquivo ou diretório existente no computador local.
Se dwFlagsespecificar MOVEFILE_DELAY_UNTIL_REBOOT, o arquivo não poderá existir em um compartilhamento remoto porque as operações atrasadas são executadas antes que a rede esteja disponível.
Por padrão, o nome é limitado a caracteres MAX_PATH. Para estender esse limite para 32.767 caracteres largos, preencha "\\?\" para o 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 de 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, lpNewFileName pode estar em um sistema de arquivos ou volume diferente. Se lpNewFileName estiver em outra unidade, você deverá definir o sinalizador MOVEFILE_COPY_ALLOWED em dwFlags.
Ao mover um diretório, lpExistingFileName e lpNewFileName devem estar na mesma unidade.
Se dwFlagsespecificar MOVEFILE_DELAY_UNTIL_REBOOT e lpNewFileName for NULL, MoveFileWithProgress registrará lpExistingFileName a ser excluído quando o sistema for reiniciado. A função falhará se não puder acessar o Registro para armazenar as informações sobre a operação de exclusão. Se lpExistingFileName se referir a um diretório, o sistema removerá o diretório na reinicialização somente se o diretório estiver vazio.
Por padrão, o nome é limitado a caracteres MAX_PATH. Para estender esse limite para 32.767 caracteres largos, preencha "\\?\" para o 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 de 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 exibe 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 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. |
|
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 função falhará se o arquivo de origem for uma fonte de link, mas o arquivo não puder 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. |
|
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 nomeia um diretório. |
|
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 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, MoveFileWithProgress 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, MoveFileWithProgress retornará zero e GetLastError retornará ERROR_REQUEST_ABORTED. O arquivo existente é deixado intacto.
Comentários
A função MoveFileWithProgress coordena sua operação com o serviço de acompanhamento de link, para que as fontes de link possam ser rastreadas conforme 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 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 retornado a você no momento em que criar o arquivo. Se você solicitou a permissão de exclusão no momento em que criou o arquivo, poderá excluir ou renomear o arquivo com esse identificador, mas não com qualquer outro.
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 | 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 Clusterizado (CsvFS) | Sim |
| ReFS (Sistema de Arquivos Resiliente) | Sim |
CsvFs fará E/S redirecionada em caso de arquivos compactados.
Observação
O cabeçalho winbase.h define MoveFileWithProgress 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
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Plataforma de Destino | Windows |
| Cabeçalho | winbase.h (incluir Windows.h) |
| Biblioteca | Kernel32.lib |
| DLL | Kernel32.dll |