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

Статья
06/02/2023

[Корпорация Майкрософт настоятельно рекомендует разработчикам использовать альтернативные средства для удовлетворения потребностей вашего приложения. Многие сценарии, для которые был разработан TxF, могут быть реализованы с помощью более простых и доступных методов. Кроме того, TxF может быть недоступен в будущих версиях Microsoft Windows. Дополнительные сведения и альтернативы TxF см. в статье Альтернативы использованию транзакционной NTFS.]

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

Синтаксис

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

Параметры

[in] lpExistingFileName

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

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

Совет

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

[in, optional] lpNewFileName

Новое имя файла или каталога. Новое имя не должно существовать. Новый файл может находиться в другой файловой системе или на другом диске. Новый каталог должен находиться на том же диске.

Совет

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

[in] hTransaction

Дескриптор транзакции. Этот дескриптор возвращается функцией CreateTransaction .

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

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

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

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

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

Если параметр dwFlags указывает MOVEFILE_DELAY_UNTIL_REBOOT, moveFileTransacted завершается ошибкой , если не удается получить доступ к реестру. Функция транзакционно сохраняет расположения файлов, которые будут переименованы при перезапуске, в следующем значении\ реестра: HKEY_LOCAL_MACHINESYSTEM\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 , это возможно, так как файл считается переименованным в пустое имя.

Система использует эти записи реестра для выполнения операций при перезапуске в том же порядке, в котором они были выданы. Дополнительные сведения об использовании флага MOVEFILE_DELAY_UNTIL_REBOOT см. в разделе MoveFileWithProgress.

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

Эта функция всегда завершается ошибкой при указании флага MOVEFILE_FAIL_IF_NOT_TRACKABLE ; отслеживание не поддерживается TxF.

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

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

SMB 3.0 не поддерживает TxF.

Требования

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

См. также

CopyFileTransacted

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

MoveFileWithProgress

Поддержка транзакций в NTFS