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

Статья
11/20/2024

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

Чтобы выполнить эту операцию как транзакцию, используйте функцию 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 завершается ошибкой, а функция GetLastErr or возвращает 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: Если вы пишете приложение, оптимизированное для операций копирования файлов в локальной сети, рассмотрите возможность использования функции Передачи Файлов из сокетов Windows (Winsock). TransferFile поддерживает высокопроизводительную передачу сети и предоставляет простой интерфейс для отправки содержимого файла на удаленный компьютер. Чтобы использовать SendFile, необходимо написать клиентское приложение Winsock, которое отправляет файл с исходного компьютера, а также серверное приложение Winsock, использующее другие функции Winsock для получения файла на удаленном компьютере.

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

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

Заметка

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

Требования

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