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

Статья
08/27/2023

Выполняет поиск в указанном каталоге заданного сеанса FTP. Записи файлов и каталогов возвращаются приложению в структуре WIN32_FIND_DATA .

Синтаксис

HINTERNET FtpFindFirstFileA(
  [in]  HINTERNET          hConnect,
  [in]  LPCSTR             lpszSearchFile,
  [out] LPWIN32_FIND_DATAA lpFindFileData,
  [in]  DWORD              dwFlags,
  [in]  DWORD_PTR          dwContext
);

Параметры

[in] hConnect

Дескриптор сеанса FTP, возвращенного из InternetConnect.

[in] lpszSearchFile

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

[out] lpFindFileData

Указатель на структуру WIN32_FIND_DATA , которая получает сведения об найденном файле или каталоге.

[in] dwFlags

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

INTERNET_FLAG_HYPERLINK

INTERNET_FLAG_NEED_FILE

INTERNET_FLAG_NO_CACHE_WRITE

INTERNET_FLAG_RELOAD

INTERNET_FLAG_RESYNCHRONIZE

[in] dwContext

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

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

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

FtpFindFirstFile похож на функцию FindFirstFile . Однако обратите внимание, что в сеансе FTP одновременно может возникать только один ftpFindFirstFile . Таким образом, перечисления сопоставляются с дескриптором сеанса FTP. Это связано с тем, что протокол FTP допускает перечисление только одного каталога в сеансе.

После вызова FtpFindFirstFile и до вызова InternetCloseHandle приложение не сможет снова вызвать FtpFindFirstFile для заданного дескриптора сеанса FTP. Если для этого дескриптора выполняется вызов FtpFindFirstFile , функция завершается сбоем с ERROR_FTP_TRANSFER_IN_PROGRESS. После завершения работы вызывающего приложения с помощью дескриптора HINTERNET , возвращаемого ftpFindFirstFile, его необходимо закрыть с помощью функции InternetCloseHandle .

После начала перечисления каталога с помощью FtpFindFirstFile можно использовать функцию InternetFindNextFile для продолжения перечисления.

Так как протокол FTP не предоставляет стандартных средств перечисления, некоторые общие сведения о файлах, такие как дата и время создания файла, не всегда доступны или верны. В этом случае FtpFindFirstFile и InternetFindNextFile заполняют недоступные сведения лучшим предположением на основе доступных сведений. Например, даты создания и последнего доступа часто совпадают с датой изменения файла.

Приложение не может вызывать FtpFindFirstFile между вызовами FtpOpenFile и InternetCloseHandle.

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

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

Примечание

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

Требования

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

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

Сеансы FTP

Функции WinINet

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