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

Статья
06/02/2023

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

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

Синтаксис

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

Параметры

[in] lpExistingFileName

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

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

Совет

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

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

[in] lpNewFileName

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

Совет

[in, optional] lpProgressRoutine

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

[in, optional] lpData

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

[in, optional] pbCancel

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

[in] dwCopyFlags

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

Значение	Значение
COPY_FILE_ALLOW_DECRYPTED_DESTINATION 0x00000008	Попытка копирования зашифрованного файла будет выполнена успешно, даже если не удается зашифровать конечную копию.
COPY_FILE_COPY_SYMLINK 0x00000800	Если исходный файл является символьной ссылкой, целевой файл также является символьной ссылкой, указывающей на тот же файл, на который указывает исходная символьная ссылка. Windows Server 2003 и Windows XP: Это значение не поддерживается.
COPY_FILE_FAIL_IF_EXISTS 0x00000001	Операция копирования немедленно завершается ошибкой, если целевой файл уже существует.
COPY_FILE_NO_BUFFERING 0x00001000	Операция копирования выполняется с использованием небуферированных операций ввода-вывода, минуя ресурсы системного кэша ввода-вывода. Рекомендуется для передачи очень больших файлов. Windows Server 2003 и Windows XP: Это значение не поддерживается.
COPY_FILE_OPEN_SOURCE_FOR_WRITE 0x00000004	Файл копируется, а исходный файл открывается для доступа на запись.
COPY_FILE_RESTARTABLE 0x00000002	Ход выполнения копирования отслеживается в целевом файле на случай сбоя копирования. Сбойную копию можно перезапустить позже, указав те же значения для lpExistingFileName и lpNewFileName , что и те, которые использовались в вызове, завершившемся сбоем. Это может значительно замедлить операцию копирования, так как во время операции копирования новый файл может быть выброшен несколько раз.
COPY_FILE_REQUEST_COMPRESSED_TRAFFIC 0x10000000	Запросите сжатие данных в базовом канале передачи во время операции копирования. Запрос может поддерживаться не для всех носителей, и в этом случае он игнорируется. Атрибуты и параметры сжатия (сложность вычислений, использование памяти) не настраиваются с помощью этого API и могут изменяться в разных выпусках ОС. Этот флаг появился в Windows 10 версии 1903 и Windows Server 2022. На Windows 10 флаг поддерживается для файлов, размещенных в общих папках SMB, где согласованная версия протокола SMB — SMB версии 3.1.1 или выше.

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

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

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

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

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

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

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

Свойства ресурсов безопасности (ATTRIBUTE_SECURITY_INFORMATION) для существующего файла копируются в новый файл.

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

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

При копировании зашифрованных файлов с помощью CopyFileEx функция пытается зашифровать целевой файл с помощью ключей, используемых при шифровании исходного файла. Если это не удается сделать, эта функция пытается зашифровать целевой файл с помощью ключей по умолчанию. Если оба этих метода не могут быть выполнены, CopyFileEx завершается ошибкой с кодом ERROR_ENCRYPTION_FAILED . Если вы хотите, чтобы copyFileEx завершил операцию копирования, даже если целевой файл не может быть зашифрован, включите COPY_FILE_ALLOW_DECRYPTED_DESTINATION в качестве значения параметра dwCopyFlags в вызове CopyFileEx.

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

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

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

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

Windows 7, Windows Server 2008 R2, Windows Server 2008, Windows Vista, Windows Server 2003 и Windows XP: Если вы пишете приложение, которое оптимизирует операции копирования файлов в локальной сети, рассмотрите возможность использования функции TransmitFile из сокетов Windows (Winsock). TransmitFile поддерживает высокопроизводительные сетевые передачи и предоставляет простой интерфейс для отправки содержимого файла на удаленный компьютер. Чтобы использовать TransmitFile, необходимо написать клиентское приложение Winsock, которое отправляет файл с исходного компьютера, а также серверное приложение Winsock, которое использует другие функции Winsock для получения файла на удаленном компьютере.

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

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

Примечание

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

Требования

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