Функция MoveFileWithProgressW (winbase.h)
Перемещает файл или каталог, включая его дочерние элементы. Вы можете предоставить функцию обратного вызова, которая получает уведомления о ходе выполнения.
Чтобы выполнить эту операцию как транзакцию, используйте функцию MoveFileTransacted .
Синтаксис
BOOL MoveFileWithProgressW(
[in] LPCWSTR lpExistingFileName,
[in, optional] LPCWSTR 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 ссылается на каталог, система удаляет каталог при перезапуске, только если каталог пуст.
По умолчанию имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 символов в ширину, добавьте к пути "\\?\". Дополнительные сведения см. в статье Именование файлов, путей и пространств имен.
Совет
Начиная с Windows 10 версии 1607, вы можете согласиться на удаление ограничения MAX_PATH без добавления в начало "\\?\". Дополнительные сведения см. в разделе "Ограничение максимальной длины пути" статьи Именование файлов, путей и пространств имен .
[in, optional] lpProgressRoutine
Указатель на функцию обратного вызова CopyProgressRoutine , которая вызывается при каждом перемещении другой части файла. Функция обратного вызова может быть полезна, если предоставить пользовательский интерфейс, отображающий ход выполнения операции. Этот параметр может принимать значение NULL.
[in, optional] lpData
Аргумент, передаваемый функции обратного вызова CopyProgressRoutine . Этот параметр может принимать значение NULL.
[in] dwFlags
Параметры перемещения. Этот параметр может иметь одно или несколько из следующих значений.
| Значение | Значение |
|---|---|
|
Если файл должен быть перемещен в другой том, функция имитирует перемещение с помощью функций CopyFile и DeleteFile .
Если файл успешно скопирован в другой том, а исходный файл не удается удалить, функция успешно оставить исходный файл без изменений. Это значение нельзя использовать с MOVEFILE_DELAY_UNTIL_REBOOT. |
|
Зарезервировано для последующего использования. |
|
Система не перемещает файл до перезапуска операционной системы. Система перемещает файл сразу после выполнения AUTOCHK, но перед созданием файлов подкачки. Следовательно, этот параметр позволяет функции удалять файлы подкачки из предыдущих запусков.
Это значение можно использовать только в том случае, если процесс находится в контексте пользователя, который принадлежит к группе администраторов или учетной записи LocalSystem. Это значение нельзя использовать с MOVEFILE_COPY_ALLOWED. |
|
Функция завершается сбоем, если исходный файл является источником ссылки, но после перемещения его невозможно отследить. Такая ситуация может возникнуть, если назначением является том, отформатированный с помощью файловой системы FAT. |
|
Если существует файл с именем lpNewFileName , функция заменяет его содержимое содержимым файла lpExistingFileName .
Это значение нельзя использовать, если lpNewFileName или lpExistingFileName именует каталог. |
|
Функция не возвращается, пока файл не будет перемещен на диск.
Установка этого значения гарантирует, что перемещение, выполненное в качестве операции копирования и удаления, будет сброшено на диск перед возвратом функции. Очистка происходит в конце операции копирования. Это значение не действует, если задано MOVEFILE_DELAY_UNTIL_REBOOT . |
Возвращаемое значение
Если функция выполняется успешно, возвращается ненулевое значение.
Если функция выполняется неудачно, возвращается нулевое значение. Дополнительные сведения об ошибке можно получить, вызвав GetLastError.
Если при перемещении файла между томами lpProgressRoutine возвращает PROGRESS_CANCEL из-за отмены пользователем операции , MoveFileWithProgress вернет ноль, а GetLastError — ERROR_REQUEST_ABORTED. Существующий файл остается без изменений.
Если при перемещении файла между томами lpProgressRoutine возвращает PROGRESS_STOP из-за того, что пользователь остановил операцию, MoveFileWithProgress вернет ноль, а GetLastError вернет ERROR_REQUEST_ABORTED. Существующий файл остается без изменений.
Комментарии
Функция MoveFileWithProgress координирует свою работу со службой отслеживания ссылок, поэтому источники ссылок можно отслеживать по мере их перемещения.
Чтобы удалить или переименовать файл, необходимо иметь разрешение на удаление файла или удаление дочернего элемента в родительском каталоге. Если вы настроили каталог со всеми доступами, кроме удаления и удаления дочерних элементов, а списки управления доступом для новых файлов наследуются, вы сможете создать файл, не удаляя его. Однако затем можно создать файл, и вы получите весь запрашиваемый доступ к дескриптору, возвращенный вам во время создания файла. Если вы запросили разрешение на удаление во время создания файла, вы можете удалить или переименовать файл с помощью этого дескриптора, но не с помощью любого другого.
В 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 |