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

Статья
06/02/2023

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

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

Синтаксис

BOOL CopyFileTransactedA(
  [in]           LPCSTR             lpExistingFileName,
  [in]           LPCSTR             lpNewFileName,
  [in, optional] LPPROGRESS_ROUTINE lpProgressRoutine,
  [in, optional] LPVOID             lpData,
  [in, optional] LPBOOL             pbCancel,
  [in]           DWORD              dwCopyFlags,
  [in]           HANDLE             hTransaction
);

Параметры

[in] lpExistingFileName

Имя существующего файла.

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

Совет

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

Если lpExistingFileName не существует, функция CopyFileTransacted завершается сбоем, а функция GetLastError возвращает ERROR_FILE_NOT_FOUND.

Файл должен находиться на локальном компьютере; В противном случае функция завершается сбоем, а для последнего кода ошибки задано значение ERROR_TRANSACTIONS_UNSUPPORTED_REMOTE.

[in] lpNewFileName

Имя нового файла.

Совет

[in, optional] lpProgressRoutine

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

[in, optional] lpData

Аргумент, передаваемый функции обратного вызова. Этот параметр может принимать значение NULL.

[in, optional] pbCancel

Если во время операции копирования для этого флага задано значение TRUE , операция отменяется. В противном случае операция копирования продолжится.

[in] dwCopyFlags

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

Значение	Значение
COPY_FILE_COPY_SYMLINK 0x00000800	Если исходный файл является символьной ссылкой, конечный файл также является символьной ссылкой, указывающей на тот же файл, на который указывает исходная символьная ссылка.
COPY_FILE_FAIL_IF_EXISTS 0x00000001	Операция копирования немедленно завершается ошибкой, если целевой файл уже существует.
COPY_FILE_OPEN_SOURCE_FOR_WRITE 0x00000004	Файл копируется, и исходный файл открывается для доступа на запись.
COPY_FILE_RESTARTABLE 0x00000002	Ход выполнения копирования отслеживается в целевом файле в случае сбоя копирования. Сбойную копию можно перезапустить позже, указав те же значения для lpExistingFileName и lpNewFileName , что и те, которые использовались в вызове, завершившемся сбоем. Это может значительно замедлить операцию копирования, так как во время операции копирования новый файл может быть сброшен несколько раз.

[in] hTransaction

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

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

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

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

Если lpProgressRoutine возвращает PROGRESS_CANCEL из-за отмены операции, CopyFileTransacted вернет ноль, а GetLastError вернет ERROR_REQUEST_ABORTED. В этом случае частично скопированный целевой файл удаляется.

Если lpProgressRoutine возвращает PROGRESS_STOP из-за того, что пользователь остановил операцию, CopyFileTransacted вернет ноль, а GetLastError вернет ERROR_REQUEST_ABORTED. В этом случае частично скопированный целевой файл остается без изменений.

При попытке вызвать эту функцию с дескриптором транзакции, которая уже была откатена, CopyFileTransacted вернет либо ERROR_TRANSACTION_NOT_ACTIVE , либо ERROR_INVALID_TRANSACTION.

Эта функция сохраняет расширенные атрибуты, структурированное хранилище OLE, альтернативные потоки данных файловой системы NTFS, атрибуты безопасности и атрибуты файлов.

Windows 7, Windows Server 2008 R2, Windows Server 2008 и Windows Vista: Атрибуты ресурсов безопасности (ATTRIBUTE_SECURITY_INFORMATION) для существующего файла не копируются в новый файл, пока не Windows 8 и Windows Server 2012.

Эта функция завершается сбоем с ERROR_ACCESS_DENIED , если целевой файл уже существует и имеет атрибут FILE_ATTRIBUTE_HIDDEN или FILE_ATTRIBUTE_READONLY .

TxF не поддерживает зашифрованные файлы.

Если указано COPY_FILE_COPY_SYMLINK , применяются следующие правила:

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

Если COPY_FILE_COPY_SYMLINK не указан, применяются следующие правила:

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

Отслеживание ссылок не поддерживается службой TxF.

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

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

Обратите внимание, что SMB 3.0 не поддерживает TxF.

Примечание

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

Требования


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