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

  • Статья

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

Синтаксис

HRESULT CopyFile2(
  [in]           PCWSTR                        pwszExistingFileName,
  [in]           PCWSTR                        pwszNewFileName,
  [in, optional] COPYFILE2_EXTENDED_PARAMETERS *pExtendedParameters
);

Параметры

[in] pwszExistingFileName

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

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

Совет Начиная с Windows 10 версии 1607, вы можете согласиться на удаление ограничения символов MAX_PATH без добавления в начало "\\?\". Дополнительные сведения см. в разделе "Максимальное ограничение пути" статьи Именование файлов, путей и пространств имен .
 
Если lpExistingFileName не существует, функция CopyFile2 не возвращает .HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)

[in] pwszNewFileName

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

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

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

[in, optional] pExtendedParameters

Необязательный адрес структуры COPYFILE2_EXTENDED_PARAMETERS .

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

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

Код возврата Описание
S_OK
 Операция копирования успешно завершена.
HRESULT_FROM_WIN32(ERROR_REQUEST_PAUSED)
 Операция копирования была приостановлена COPYFILE2_PROGRESS_PAUSE возвратом функции обратного вызова CopyFile2ProgressRoutine .
HRESULT_FROM_WIN32(ERROR_REQUEST_ABORTED)
 Операция копирования была приостановлена COPYFILE2_PROGRESS_CANCEL или COPYFILE2_PROGRESS_STOP возвратом функции обратного вызова CopyFile2ProgressRoutine .
HRESULT_FROM_WIN32(ERROR_ALREADY_EXISTS)
 Элемент dwCopyFlags структуры COPYFILE2_EXTENDED_PARAMETERS , передаваемый через параметр pExtendedParameters , содержит флаг COPY_FILE_FAIL_IF_EXISTS и конфликтующее имя.
HRESULT_FROM_WIN32(ERROR_FILE_EXISTS)
 Элемент dwCopyFlags структуры COPYFILE2_EXTENDED_PARAMETERS , передаваемый через параметр pExtendedParameters , содержит флаг COPY_FILE_FAIL_IF_EXISTS и конфликтующее имя.

Комментарии

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

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

Чтобы скомпилировать приложение, использующее эту функцию, определите макрос _WIN32_WINNTкак _WIN32_WINNT_WIN8 или более поздней версии. Дополнительные сведения см. в разделе Использование заголовков Windows.

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

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

Начиная с Windows 10 версии 1903 и Windows Server 2022, новое значение , COPY_FILE_REQUEST_COMPRESSED_TRAFFIC, поддерживается для поля dwCopyFlags структуры COPYFILE2_EXTENDED_PARAMETERS , передаваемой в аргументе pExtendedParameters этой функции. Это новое значение запрашивает, чтобы базовый канал передачи сжимал данные во время операции копирования. Запрос может поддерживаться не для всех носителей, и в этом случае он игнорируется. Атрибуты и параметры сжатия (сложность вычислений, использование памяти) не настраиваются с помощью этого API и могут изменяться в разных выпусках ОС. В Windows 10 флаг поддерживается для файлов, находящихся в общих папках SMB, где согласованная версия протокола SMB — SMB версии 3.1.1 или выше.

Требования

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

См. также

COPYFILE2_EXTENDED_PARAMETERS

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