Функция CopyFileEx

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

Синтаксис

BOOL CopyFileEx(
  LPCTSTR lpExistingFileName,           // имя существующего файла
  LPCTSTR lpNewFileName,                // имя нового файла
  LPPROGRESS_ROUTINE lpProgressRoutine, // функция обратного вызова
  LPVOID lpData,                        // параметры обратного вызова
  LPBOOL pbCancel,                      // отмененный статус
  DWORD dwCopyFlags                     // опции копирования
);

Параметры

lpExistingFileName

[in] Указатель на символьную строку с нулем в конце, которая определяет имя существующего файла.

Windows NT/2000/XP: В версии ANSI этой функции, число символов имени ограничивается флажком MAX_PATH. Чтобы выйти за пределы этого ограничения до длины равной 32767 символам, вызовите Unicode версию функции и присоедините спереди пути "\\?\". Подробную информацию см. статье  Именование файлов.

Windows 95/98/Me: Эта строка не должна выходить за пределы, установленные флажком MAX_PATH.

lpNewFileName

[in] Указатель на символьную строку с нулем в конце, которая определяет имя нового файла.

Windows NT/2000/XP: В версии ANSI этой функции, число символов имени ограничивается флажком MAX_PATH. Чтобы выйти за пределы этого ограничения до длины равной 32767 символам, вызовите Unicode версию функции и присоедините спереди пути "\\?\". Подробную информацию см. статье  Именование файлов.

Windows 95/98/Me: Эта строка не должна выходить за пределы, установленные флажком MAX_PATH.

lpProgressRoutine

[in] Адрес функции обратного вызова типа LPPROGRESS_ROUTINE, которая вызывается каждый раз, когда скопирована еще одна часть файла. Этот параметр может иметь значение ПУСТО (NULL). Подробную информацию о выполнении функции обратного вызова см. в описании функции CopyProgressRoutine.

lpData

[in] Параметр, который передается в функцию обратного вызова. Этот параметр может иметь значение ПУСТО (NULL).

pbCancel

[in] Если этот флажок в ходе  операции копирования устанавливается в значение ИСТИНА (TRUE), операция отменяется. В противном случае, операция копирования продолжится до завершения.

dwCopyFlags

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

 

Значение Предназначение
COPY_FILE_ALLOW_DECRYPTED_DESTINATION Windows XP: Попытка копировать зашифрованный файл завершится успешно, даже если получаемая копия не может быть зашифрована.

Windows 2000/NT и Windows Me/98/95:  Это значение не поддерживается.

COPY_FILE_FAIL_IF_EXISTS Операция копирования немедленно завершается ошибкой, если конечный файл уже существует.
COPY_FILE_RESTARTABLE Ход выполнения копирования отслеживается в конечном файле в случае, если копия завершается ошибкой. Завершенное ошибкой копирование может быть перезапущено впоследствии, при помощи установки, тех же самых значений в параметрах lpExistingFileName и lpNewFileName,  использованных при вызове функции, который завершился ошибкой.
 

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

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

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

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

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

Замечания

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

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

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

Windows 2000: Когда CopyFileEx используется для копирования зашифрованного файла, функция пытается зашифровать выходной файл с ключом по умолчанию. Не пытайтесь сделать так, чтобы зашифровать выходной файл с ключом, использованным при кодировании исходного файла. Если файл не может быть зашифрован, CopyFileEx заканчивает операцию копирования, не зашифровав выходной файл.

Windows 98/Me: Хотя функция CopyFileEx не выполняется  Windows 98/Me, CopyFileExW поддерживается подпрограммой Microsoft Layer for Unicode.

Чтобы компилировать приложение, которое использует эту функцию, определите макрокоманду _WIN32_WINNT  как 0x0400 или выше. Подробную информацию, см. в статье Использование заголовков SDK.

Смотри также 

Обзор Управление файламиФункции, используемые в управлении файлами, CreateFile, CopyFile, CopyProgressRoutine, MoveFile, MoveFileWithProgress

Размещение и совместимость CopyFileEx

К

Windows XP

Да 

л

Windows 2000 Professional

Да

и

Windows NT Workstation

Да версии 4.0

е

Windows Me

Нет

н

Windows 98

Нет

т

Windows 95

Нет

 
С

Windows Server 2003

Да

е Windows 2000 Server Да
р Windows NT Server Да версии 4.0
в    
е    
р    

Используемая библиотека

Kernel32.lib

Используемая DLL -
 Заголовочный файл  

- объявлено в

Winbase.h

 - включено в

Windows.h

 Unicode

Реализуется как версии Unicode и  ANSI для Windows 2000/XP. Обратите внимание на то, что поддержка в Windows Me/98/95 требует программы Microsoft Layer for Unicode.

 Замечания по платформе

Не имеется

 

Назад в оглавление
На главную страницу
В оглавление справки
23.02.2004 00:12 ©Copyright V. Sokovikov
Hosted by uCoz