ftpFindFirstFileA 函数 (wininet.h)

  • 项目

搜索给定 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

从 InternetConnect 返回的 FTP 会话的句柄。

[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，WIN32_FIND_DATA结构中返回的文件时间位于本地时区，而不是协调的通用时间 (UTC) 格式。

FtpFindFirstFile 类似于 FindFirstFile 函数。 但请注意，在给定的 FTP 会话中，一次只能发生一个 FtpFindFirstFile 。 因此，枚举与 FTP 会话句柄相关。 这是因为 FTP 协议只允许每个会话一个目录枚举。

调用 FtpFindFirstFile 后，直到调用 InternetCloseHandle，应用程序无法在给定的 FTP 会话句柄上再次调用 FtpFindFirstFile 。 如果调用该句柄上的 FtpFindFirstFile ，则函数将失败并 ERROR_FTP_TRANSFER_IN_PROGRESS。 调用应用程序使用 FtpFindFirstFile 返回的 HINTERNET 句柄后，必须使用 InternetCloseHandle 函数将其关闭。

使用 FtpFindFirstFile 开始目录枚举后，可以使用 InternetFindNextFile 函数继续枚举。

由于 FTP 协议不提供标准枚举方式，因此有关文件的一些常见信息（例如文件创建日期和时间）并非始终可用或正确。 发生这种情况时， FtpFindFirstFile 和 InternetFindNextFile 会根据可用信息使用最佳猜测填充不可用的信息。 例如，创建日期和上次访问日期通常与文件的修改日期相同。

应用程序无法在调用 FtpOpenFile 和 InternetCloseHandle 之间调用 FtpFindFirstFile。

与 WinINet API 的所有其他方面一样，无法从 DllMain 或全局对象的构造函数和析构函数中安全地调用此函数。

注意 WinINet 不支持服务器实现。 此外，不应从服务使用它。 对于服务器实现或服务，请使用 Microsoft Windows HTTP Services (WinHTTP) 。
 

注意

wininet.h 标头将 FtpFindFirstFile 定义为别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。 将非特定编码别名的使用与非非特定编码的代码混合使用可能会导致不匹配，从而导致编译或运行时错误。 有关详细信息，请参阅 函数原型的约定。

要求

要求 值
最低受支持的客户端 Windows 2000 Professional [仅限桌面应用]
最低受支持的服务器 Windows 2000 Server [仅限桌面应用]
目标平台 Windows
标头 wininet.h
Library Wininet.lib
DLL Wininet.dll

另请参阅

FTP 会话

WinINet 函数