Функция FtpGetFileA (wininet.h)

  • Статья

Извлекает файл с FTP-сервера и сохраняет его под указанным именем файла, создавая в процессе новый локальный файл.

Синтаксис

BOOL FtpGetFileA(
  [in] HINTERNET hConnect,
  [in] LPCSTR    lpszRemoteFile,
  [in] LPCSTR    lpszNewFile,
  [in] BOOL      fFailIfExists,
  [in] DWORD     dwFlagsAndAttributes,
  [in] DWORD     dwFlags,
  [in] DWORD_PTR dwContext
);

Параметры

[in] hConnect

Обработка сеанса FTP.

[in] lpszRemoteFile

Указатель на строку, завершающуюся нулевым значением, которая содержит имя извлекаемого файла.

[in] lpszNewFile

Указатель на строку, завершающуюся нулевым значением, которая содержит имя файла, создаваемого в локальной системе.

[in] fFailIfExists

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

[in] dwFlagsAndAttributes

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

[in] dwFlags

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

Приложение может выбрать одно из этих значений типа передачи.

Значение Значение
FTP_TRANSFER_TYPE_ASCII
 Передает файл с помощью метода передачи ASCII (тип A) FTP. Сведения об элементе управления и форматировании преобразуются в локальные эквиваленты.
FTP_TRANSFER_TYPE_BINARY
 Передает файл с помощью метода передачи образа (тип I) FTP. Файл передается в том виде, в который он существует, без изменений. Это метод передачи по умолчанию.
FTP_TRANSFER_TYPE_UNKNOWN
 По умолчанию используется FTP_TRANSFER_TYPE_BINARY.
INTERNET_FLAG_TRANSFER_ASCII
 Передает файл как ASCII.
INTERNET_FLAG_TRANSFER_BINARY
 Передает файл в виде двоичного файла.
 

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

Значение Значение
INTERNET_FLAG_HYPERLINK
 При определении того, следует ли перезагружать элемент из сети, принудительно выполняется перезагрузка, если не было возвращено время окончания срока действия и время последнего изменения с сервера.
INTERNET_FLAG_NEED_FILE
 Вызывает создание временного файла, если файл не может быть кэширован.
INTERNET_FLAG_RELOAD
 Принудительное скачивание запрошенного файла, объекта или списка каталогов с сервера-источника, а не из кэша.
INTERNET_FLAG_RESYNCHRONIZE
 Перезагружает ресурсы HTTP, если ресурс был изменен с момента последнего скачивания. Все ресурсы FTP перезагружаются.

Windows XP и Windows Server 2003 R2 и более ранние версии: Ресурсы Gopher также перезагружаются.

[in] dwContext

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

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

Возвращает значение TRUE в случае успешного выполнения или FALSE в противном случае. Чтобы получить определенное сообщение об ошибке, вызовите Метод GetLastError.

Комментарии

FtpGetFile — это высокоуровневая подпрограмма, которая обрабатывает все расходы, связанные с чтением файла с FTP-сервера и его локальным хранением. Приложение, которому требуется получать только данные файла или которому требуется тщательный контроль над передачей файлов, должно использовать функции FtpOpenFile и InternetReadFile .

Если параметр dwFlags указывает FTP_TRANSFER_TYPE_ASCII, преобразование файловых данных преобразует символы управления и форматирования в локальные эквиваленты. Передача по умолчанию — двоичный режим, в котором файл скачиваются в том же формате, что и на сервере.

Как lpszRemoteFile, так и lpszNewFile могут быть частичными или полными именами файлов относительно текущего каталога.

Как и все другие аспекты API WinINet, эту функцию нельзя безопасно вызывать из библиотеки DllMain или из конструкторов и деструкторов глобальных объектов.

Примечание WinINet не поддерживает реализации сервера. Кроме того, его не следует использовать из службы. Для серверных реализаций или служб используйте службы Microsoft Windows HTTP (WinHTTP).
 

Примечание

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

Требования

Требование Значение
Минимальная версия клиента Windows 2000 Professional [только классические приложения]
Минимальная версия сервера Windows 2000 Server [только классические приложения]
Целевая платформа Windows
Header wininet.h
Библиотека Wininet.lib
DLL Wininet.dll

См. также раздел

Сеансы FTP

Функции WinINet