Функция MoveFileWithProgressA (winbase.h)

Статья
11/20/2024

Перемещает файл или каталог, включая дочерние элементы. Вы можете предоставить функцию обратного вызова, которая получает уведомления о ходе выполнения.

Чтобы выполнить эту операцию как транзакцию, используйте функцию MoveFileTransacted.

Синтаксис

BOOL MoveFileWithProgressA(
  [in]           LPCSTR             lpExistingFileName,
  [in, optional] LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in]           DWORD              dwFlags
);

Параметры

[in] lpExistingFileName

Имя существующего файла или каталога на локальном компьютере.

Если dwFlags указывает MOVEFILE_DELAY_UNTIL_REBOOT, файл не может существовать в удаленной общей папке, так как отложенные операции выполняются до доступности сети.

По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 расширенных символов, добавьте "\\?\" в путь. Дополнительные сведения см. в именовании файлов, путей и пространств имен.

Кончик

Начиная с Windows 10 версии 1607, вы можете отказаться от ограничения MAX_PATH без предустановки "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" файлы именования, пути и пространства имен.

[in, optional] lpNewFileName

Новое имя файла или каталога на локальном компьютере.

При перемещении файла lpNewFileName может находиться в другой файловой системе или томе. Если lpNewFileName находится на другом диске, необходимо задать флаг MOVEFILE_COPY_ALLOWED в dwFlags.

При перемещении каталога lpExistingFileName и lpNewFileName должны находиться на одном диске.

Если dwFlags указывает MOVEFILE_DELAY_UNTIL_REBOOT и lpNewFileNameNULL, MoveFileWithProgress регистрирует lpExistingFileName, которые будут удалены при перезапуске системы. Функция завершается ошибкой, если она не может получить доступ к реестру для хранения сведений об операции удаления. Если lpExistingFileName ссылается на каталог, система удаляет каталог при перезапуске, только если каталог пуст.

Кончик

[in, optional] lpProgressRoutine

Указатель на функцию обратного вызова copyProgressRoutine , которая вызывается при каждом перемещении другой части файла. Функция обратного вызова может оказаться полезной, если вы предоставляете пользовательский интерфейс, отображающий ход выполнения операции. Этот параметр может быть NULL.

[in, optional] lpData

Аргумент, передаваемый в функцию обратного вызова CopyProgressRout ine. Этот параметр может быть NULL.

[in] dwFlags

Параметры перемещения. Этот параметр может быть одним или несколькими из следующих значений.

Ценность	Значение
MOVEFILE_COPY_ALLOWED 2 (0x2)	Если файл перемещается в другой том, функция имитирует перемещение с помощью функций CopyFile и DeleteFile. Если файл успешно скопирован в другой том, и исходный файл не удается удалить, функция завершает работу с исходным файлом без изменений. Это значение нельзя использовать с MOVEFILE_DELAY_UNTIL_REBOOT.
MOVEFILE_CREATE_HARDLINK 16 (0x10)	Зарезервировано для дальнейшего использования.
MOVEFILE_DELAY_UNTIL_REBOOT 4 (0x4)	Система не перемещает файл до перезапуска операционной системы. Система перемещает файл сразу после выполнения AUTOCHK, но перед созданием файлов разбиения по страницам. Следовательно, этот параметр позволяет функции удалять файлы разбиения на страницы из предыдущих запусков. Это значение можно использовать только в том случае, если процесс находится в контексте пользователя, который принадлежит группе администраторов или учетной записи LocalSystem. Это значение нельзя использовать с MOVEFILE_COPY_ALLOWED.
MOVEFILE_FAIL_IF_NOT_TRACKABLE 32 (0x20)	Функция завершается ошибкой, если исходный файл является источником ссылки, но после перемещения невозможно отслеживать файл. Эта ситуация может произойти, если назначение является томом, отформатированным с файловой системой FAT.
MOVEFILE_REPLACE_EXISTING 1 (0x1)	Если файл с именем lpNewFileName существует, функция заменяет его содержимое содержимым файла lpExistingFileName. Это значение нельзя использовать, если lpNewFileName или lpExistingFileName имена каталога.
MOVEFILE_WRITE_THROUGH 8 (0x8)	Функция не возвращается, пока файл не будет перемещен на диск. Задание этого значения гарантирует, что перемещение, выполняемое как операция копирования и удаления, удаляется на диск перед возвратом функции. Очистка происходит в конце операции копирования. Это значение не действует, если задано MOVEFILE_DELAY_UNTIL_REBOOT.

Возвращаемое значение

Если функция выполнена успешно, возвращаемое значение ненулевое.

Если функция завершается ошибкой, возвращаемое значение равно нулю. Чтобы получить расширенные сведения об ошибке, вызовите GetLastError.

При перемещении файла между томами, если lpProgressRoutine возвращает PROGRESS_CANCEL из-за отмены операции, MoveFileWithProgress вернет ноль и GetLastError вернет ERROR_REQUEST_ABORTED. Существующий файл остается нетронутым.

При перемещении файла между томами, если lpProgressRoutine возвращает PROGRESS_STOP из-за остановки операции, MoveFileWithProgress вернет ноль и GetLastError вернет ERROR_REQUEST_ABORTED. Существующий файл остается нетронутым.

Замечания

Функция moveFileWithProgress координирует свою работу со службой отслеживания ссылок, поэтому источники ссылок можно отслеживать по мере перемещения.

Чтобы удалить или переименовать файл, необходимо либо удалить разрешение на удаление файла, либо удалить дочернее разрешение в родительском каталоге. Если вы настроили каталог со всеми доступами, кроме удаления и удаления дочерних элементов, а списки ACL новых файлов наследуются, то вы сможете создать файл, не имея возможности удалить его. Тем не менее вы можете создать файл, и вы получите все запросы на доступ к дескриптору, возвращенном вам во время создания файла. Если вы запросили разрешение на удаление во время создания файла, можно удалить или переименовать файл с этим дескриптором, но не с другими.

В Windows 8 и Windows Server 2012 эта функция поддерживается следующими технологиями.

Технологии	Поддержанный
Протокол SMB 3.0	Да
Отработка отказа SMB 3.0 (TFO)	Да
SMB 3.0 с масштабируемыми общими папками (SO)	Да
Файловая система общего тома кластера (CSVFS)	Да
Отказоустойчивая файловая система (ReFS)	Да

CsvFs будет выполнять перенаправленные операции ввода-вывода для сжатых файлов.

Заметка

Заголовок winbase.h определяет MoveFileWithProgress в качестве псевдонима, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, нейтрального для кодирования, с кодом, не зависящим от кодирования, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в соглашениях о прототипах функций.

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows XP [только классические приложения]
минимальный поддерживаемый сервер	Windows Server 2003 [только классические приложения]
целевая платформа	Виндоус
заголовка	winbase.h (включая Windows.h)
библиотеки	Kernel32.lib
DLL	Kernel32.dll

См. также

CopyFileEx

CopyProgressRoutine

функции управления файлами

MoveFileEx

MoveFileTransacted

Поделиться через