InternetConnectA 函数 (wininet.h)

  • 项目

打开给定站点 (FTP) 或 HTTP 会话的文件传输协议。

语法

HINTERNET InternetConnectA(
  [in] HINTERNET     hInternet,
  [in] LPCSTR        lpszServerName,
  [in] INTERNET_PORT nServerPort,
  [in] LPCSTR        lpszUserName,
  [in] LPCSTR        lpszPassword,
  [in] DWORD         dwService,
  [in] DWORD         dwFlags,
  [in] DWORD_PTR     dwContext
);

参数

[in] hInternet

上一次调用 InternetOpen 返回的句柄。

[in] lpszServerName

指向以 null 结尾的字符串的指针，该字符串指定 Internet 服务器的主机名。 或者，字符串可以包含站点的 IP 编号，采用 ASCII 点十进制格式 (例如 11.0.1.45) 。

[in] nServerPort

传输控制协议/Internet 协议 (服务器上的 TCP/IP) 端口。 这些标志仅设置使用的端口。 该服务由 dwService 的值设置。 此参数的取值可为下列值之一：

值 含义
INTERNET_DEFAULT_FTP_PORT
 使用 FTP 服务器的默认端口 (端口 21) 。
INTERNET_DEFAULT_GOPHER_PORT
 使用 Gopher 服务器的默认端口 (端口 70) 。
注意 仅限 Windows XP 和 Windows Server 2003 R2 及更早版本。
 
INTERNET_DEFAULT_HTTP_PORT
 使用 HTTP 服务器的默认端口 (端口 80) 。
INTERNET_DEFAULT_HTTPS_PORT
 使用安全超文本传输协议的默认端口 (HTTPS) 服务器 (端口 443) 。
INTERNET_DEFAULT_SOCKS_PORT
 将 SOCKS 防火墙服务器的默认端口 (端口 1080) 。
INTERNET_INVALID_PORT_NUMBER
 使用 由 dwService 指定的服务的默认端口。

[in] lpszUserName

指向以 null 结尾的字符串的指针，该字符串指定要登录的用户的名称。 如果此参数为 NULL，则该函数使用适当的默认值。 对于 FTP 协议，默认值为“匿名”。

[in] lpszPassword

指向以 null 结尾的字符串的指针，该字符串包含用于登录的密码。 如果 lpszPassword 和 lpszUsername 均为 NULL，则该函数使用默认的“匿名”密码。 对于 FTP，默认密码是用户的电子邮件名称。 如果 lpszPassword 为 NULL，但 lpszUsername 不是 NULL，则该函数使用空密码。

[in] dwService

要访问的服务的类型。 此参数的取值可为下列值之一：

值 含义
INTERNET_SERVICE_FTP
 FTP 服务。
INTERNET_SERVICE_GOPHER
 Gopher 服务。
注意 仅限 Windows XP 和 Windows Server 2003 R2 及更早版本。
 
INTERNET_SERVICE_HTTP
 HTTP 服务。

[in] dwFlags

特定于所用服务的选项。 如果
dwService 是 INTERNET_SERVICE_FTP，INTERNET_FLAG_PASSIVE 导致应用程序使用被动 FTP 语义。

[in] dwContext

指向变量的指针，该变量包含应用程序定义的值，该值用于标识回调中返回的句柄的应用程序上下文。

返回值

如果连接成功，则返回会话的有效句柄，否则返回 NULL 。 若要检索扩展的错误信息，请调用 GetLastError。 应用程序还可以使用 InternetGetLastResponseInfo 来确定拒绝访问服务的原因。

注解

下表描述了 lpszUsername 和 lpszPassword 这四个可能设置的行为。

lpszUsername lpszPassword 发送到 FTP 服务器的用户名 发送到 FTP 服务器的密码
NULL NULL “anonymous” 用户的电子邮件名称
非 NULL 字符串 NULL lpszUsername ""
NULL 非 NULL 字符串 ERROR ERROR
非 NULL 字符串 非 NULL 字符串 lpszUsername lpszPassword
 

对于 FTP 站点， InternetConnect 实际上与服务器建立连接;对于其他人，在应用程序请求特定事务之前，不会建立实际连接。

为了最大限度地提高效率，使用 HTTP 协议的应用程序应尽量减少对 InternetConnect 的调用，并避免对用户请求的每个事务调用此函数。 实现此目的的一种方法是保留从 InternetConnect 返回的句柄的小型缓存;当用户向以前访问的服务器发出请求时，该会话句柄仍然可用。

调用应用程序使用 InternetConnect 返回的 HINTERNET 句柄后，必须使用 InternetCloseHandle 函数将其关闭。

注意当请求 (InternetOpen 的 dwFlags 参数指定INTERNET_FLAG_ASYNC) ，而 dwContext 参数为零 (INTERNET_NO_CALLBACK) 时，将不会调用在连接句柄上使用 InternetSetStatusCallback 设置的回调函数，但调用仍将在异步模式下执行。

可在以下主题中找到 InternetConnect 用法示例。

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

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

注意

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

要求

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

另请参阅

启用 Internet 功能

WinINet 函数