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

Статья
06/27/2024

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

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

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

Синтаксис

BOOL MoveFileExA(
  [in]           LPCSTR lpExistingFileName,
  [in, optional] LPCSTR 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 ссылается на каталог, система удаляет каталог при перезапуске, только если каталог пуст.

Кончик

[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, в зависимости от того, является ли переименование удаленным или нет:

szSrcFile\0\0
szSrcFile\0szDstFile\0

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

примечание Хотя \0\0 технически не разрешено в узле REG_MULTI_SZ, он может быть переименован в пустое имя.

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

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

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

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

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

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

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

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

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

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

Примеры

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

Требования

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