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

Статья
11/20/2024

Извлекает файл с 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

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

[in] lpszNewFile

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

[in] fFailIfExists

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

[in] dwFlagsAndAttributes

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

[in] dwFlags

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

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

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

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

Ценность	Значение
INTERNET_FLAG_HYPERLINK	Принудивает перезагрузку, если срок действия истекает, и время LastModified не возвращается с сервера при определении необходимости перезагрузки элемента из сети.
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 Services (WinHTTP).

Заметка

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

Требования

Требование	Ценность
минимальные поддерживаемые клиентские	Windows 2000 Профессиональный [только классические приложения]
минимальный поддерживаемый сервер	Windows 2000 Server [только классические приложения]
целевая платформа	Виндоус
заголовка	wininet.h
библиотеки	Wininet.lib
DLL	Wininet.dll

См. также

сеансов FTP

Функции WinINet

Поделиться через