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

Статья
05/20/2023

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

Функция MoveFileWithProgress эквивалентна функции MoveFileEx , за исключением того, что MoveFileWithProgress позволяет предоставить функцию обратного вызова, которая получает уведомления о ходе выполнения.

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

Синтаксис

BOOL MoveFileExW(
  [in]           LPCWSTR lpExistingFileName,
  [in, optional] LPCWSTR lpNewFileName,
  [in]           DWORD   dwFlags
);

Параметры

[in] lpExistingFileName

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

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

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

Совет

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

[in, optional] lpNewFileName

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

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

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

Если dwFlags указывает , MOVEFILE_DELAY_UNTIL_REBOOT а lpNewFileName имеет значение NULL, MoveFileEx регистрирует файл lpExistingFileName для удаления при перезапуске системы. Если lpExistingFileName ссылается на каталог, система удаляет каталог при перезапуске, только если каталог пуст.

В версии ANSI этой функции имя ограничено MAX_PATH символами. Чтобы расширить это ограничение до 32 767 символов ширины, вызовите версию функции в Юникоде и добавьте к пути "\?". Дополнительные сведения см. в разделе Именование файла.

Совет

[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 при условии соблюдения требований безопасности, касающихся списков управления доступом (ACL). Дополнительные сведения см. в разделе Примечания этого раздела. Если lpNewFileName присваивает имя существующему каталогу, сообщается об ошибке.
MOVEFILE_WRITE_THROUGH 8 (0x8)	Функция не возвращается, пока файл не будет перемещен на диск. Установка этого значения гарантирует, что перемещение, выполненное в качестве операции копирования и удаления, будет сброшено на диск перед возвратом функции. Очистка происходит в конце операции копирования. Это значение не действует, если задано MOVEFILE_DELAY_UNTIL_REBOOT .

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

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

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

Если параметр dwFlags указывает MOVEFILE_DELAY_UNTIL_REBOOT, moveFileEx завершается сбоем, если не удается получить доступ к реестру. Функция сохраняет расположения файлов, которые будут переименованы при перезапуске, в следующем значении реестра: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\PendingFileRenameOperations

Это значение реестра имеет тип REG_MULTI_SZ. Каждая операция переименования сохраняет одну из следующих строк, завершаемых значением NULL, в зависимости от того, является ли переименование удалением:

szDstFile\0\0
szSrcFile\0szDstFile\0

Строка szDstFile\0\0 указывает, что файл szDstFile должен быть удален при перезагрузке. Строка szSrcFile\0szDstFile\0 указывает, что szSrcFile следует переименовать szDstFile при перезагрузке .

Примечание Хотя \0\0 технически не допускается в узле REG_MULTI_SZ , это возможно, так как файл считается переименованным в пустое имя.

Система использует эти записи реестра для выполнения операций при перезапуске в том же порядке, в котором они были выданы. Например, следующий фрагмент кода создает записи реестра, которые удаляют szDstFile и переименовывает szSrcFile в szDstFile при перезапуске :

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

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

Система удаляет каталог, помеченный для удаления флагом MOVEFILE_DELAY_UNTIL_REBOOT , только если он пуст. Чтобы обеспечить удаление каталогов, перед удалением всех файлов из каталога необходимо переместить или удалить их. Файлы могут находиться в каталоге во время загрузки, но их необходимо удалить или переместить, прежде чем система сможет удалить каталог.

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

Если файл перемещается между томами, MoveFileEx не перемещает дескриптор безопасности вместе с файлом. Файлу назначается дескриптор безопасности по умолчанию в целевом каталоге.

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

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

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

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

Примеры

Пример см. в разделе Создание и использование временного файла.

Требования

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