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

Статья
06/02/2023

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

Чтобы выполнить эту операцию как транзакцию, используйте функцию 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 а lpNewFileName имеет значение NULL, MoveFileWithProgress регистрирует lpExistingFileName для удаления при перезапуске системы. Функция завершается ошибкой, если ей не удается получить доступ к реестру для хранения сведений об операции удаления. Если lpExistingFileName ссылается на каталог, система удаляет каталог при перезапуске, только если каталог пуст.

Совет

[in, optional] lpProgressRoutine

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

[in, optional] lpData

Аргумент, передаваемый функции обратного вызова CopyProgressRoutine . Этот параметр может принимать значение 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. Существующий файл остается без изменений.

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

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

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

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

Примечание

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

Требования

Требование	Значение
Минимальная версия клиента	Windows XP [только классические приложения]
Минимальная версия сервера	Windows Server 2003 [только классические приложения]
Целевая платформа	Windows
Header	winbase.h (включая Windows.h)
Библиотека	Kernel32.lib
DLL	Kernel32.dll

См. также

CopyFileEx

CopyProgressRoutine

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

MoveFileEx

MoveFileTransacted