WinHttpConnect 函数 (winhttp.h)
WinHttpConnect 函数指定 HTTP 请求的初始目标服务器,并将 HINTERNET 连接句柄返回到该初始目标的 HTTP 会话。
语法
WINHTTPAPI HINTERNET WinHttpConnect(
[in] HINTERNET hSession,
[in] LPCWSTR pswzServerName,
[in] INTERNET_PORT nServerPort,
[in] DWORD dwReserved
);
参数
[in] hSession
由先前调用 WinHttpOpen 返回的有效 HINTERNETWinHTTP 会话句柄。
[in] pswzServerName
指向包含 HTTP 服务器的主机名的 以 null 结尾的字符串的指针。 或者,字符串可以包含 ASCII 中站点的 IP 地址,例如 10.0.1.45。 请注意,WinHttp 不接受未首先将国际主机名转换为 Punycode。 有关详细信息,请参阅 处理国际化域名 (IDN) 。
[in] nServerPort
无符号整数,指定建立连接的服务器上的 TCP/IP 端口。 此参数可以是任何有效的 TCP/IP 端口号,也可以是以下值之一。
值 | 含义 |
---|---|
|
使用 HTTP 服务器的默认端口 (端口 80) 。 |
|
使用 HTTPS 服务器的默认端口 (端口 443) 。 选择此端口不会自动建立安全连接。 你仍必须通过将 WINHTTP_FLAG_SECURE 标志与 WinHttpOpenRequest 一起使用来指定使用安全事务语义。 |
|
将端口 80 用于 HTTP,将端口 443 用于安全超文本传输协议 (HTTPS) 。 |
[in] dwReserved
此参数是保留的,必须为 0。
返回值
如果连接成功,则返回 HTTP 会话的有效连接句柄,否则返回 NULL 。 若要检索扩展的错误信息,请调用 GetLastError。 返回的错误代码如下。
错误代码 | 说明 |
---|---|
|
为此操作提供的句柄类型不正确。 |
|
发生了内部错误。 |
|
URL 无效。 |
|
该操作被取消,通常是因为操作完成之前,操作所针对的句柄已关闭。 |
|
无法识别或不支持 URL 方案。 |
|
WinHTTP 函数支持正在关闭或卸载。 |
|
内存不足,无法完成请求的操作。 (Windows 错误代码) |
注解
即使在异步模式下使用 WinHTTP (即在 WinHttpOpen) 中设置了WINHTTP_FLAG_ASYNC时,此函数也会同步运行。 返回值指示成功或失败。 要获得更多的错误信息,请调用 GetLastError。
调用应用程序使用 WinHttpConnect 返回的 HINTERNET 句柄后,必须使用 WinHttpCloseHandle 函数将其关闭。
WinHttpConnect 指定目标 HTTP 服务器,但如果重定向了请求,则响应可能来自另一台服务器。 可以通过使用 WINHTTP_OPTION_URL 标志调用 WinHttpQueryOption 来确定发送响应的服务器 URL。
示例
以下示例演示如何使用安全事务语义从 HTTPS 服务器下载资源。 示例代码初始化 Microsoft Windows HTTP Services (WinHTTP) 应用程序编程接口 (API) ,选择目标 HTTPS 服务器,然后打开并发送对此安全资源的请求。
WinHttpQueryDataAvailable 与请求句柄一起使用,以确定有多少数据可供下载,然后 WinHttpReadData 用于读取该数据。 此过程将重复,直到检索并显示整个文档。
DWORD dwSize = 0;
DWORD dwDownloaded = 0;
LPSTR pszOutBuffer;
BOOL bResults = FALSE;
HINTERNET hSession = NULL,
hConnect = NULL,
hRequest = NULL;
// Use WinHttpOpen to obtain a session handle.
hSession = WinHttpOpen( L"WinHTTP Example/1.0",
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
WINHTTP_NO_PROXY_NAME,
WINHTTP_NO_PROXY_BYPASS, 0);
// Specify an HTTP server.
if (hSession)
hConnect = WinHttpConnect( hSession, L"www.microsoft.com",
INTERNET_DEFAULT_HTTPS_PORT, 0);
// Create an HTTP request handle.
if (hConnect)
hRequest = WinHttpOpenRequest( hConnect, L"GET", NULL,
NULL, WINHTTP_NO_REFERER,
WINHTTP_DEFAULT_ACCEPT_TYPES,
WINHTTP_FLAG_SECURE);
// Send a request.
if (hRequest)
bResults = WinHttpSendRequest( hRequest,
WINHTTP_NO_ADDITIONAL_HEADERS,
0, WINHTTP_NO_REQUEST_DATA, 0,
0, 0);
// End the request.
if (bResults)
bResults = WinHttpReceiveResponse( hRequest, NULL);
// Keep checking for data until there is nothing left.
if (bResults)
do
{
// Check for available data.
dwSize = 0;
if (!WinHttpQueryDataAvailable( hRequest, &dwSize))
printf("Error %u in WinHttpQueryDataAvailable.\n", GetLastError());
// Allocate space for the buffer.
pszOutBuffer = new char[dwSize+1];
if (!pszOutBuffer)
{
printf("Out of memory\n");
dwSize=0;
}
else
{
// Read the Data.
ZeroMemory(pszOutBuffer, dwSize+1);
if (!WinHttpReadData( hRequest, (LPVOID)pszOutBuffer,
dwSize, &dwDownloaded))
printf( "Error %u in WinHttpReadData.\n", GetLastError());
else
printf( "%s\n", pszOutBuffer);
// Free the memory allocated to the buffer.
delete [] pszOutBuffer;
}
} while (dwSize > 0);
// Report any errors.
if (!bResults)
printf("Error %d has occurred.\n", GetLastError());
// Close any open handles.
if (hRequest) WinHttpCloseHandle(hRequest);
if (hConnect) WinHttpCloseHandle(hConnect);
if (hSession) WinHttpCloseHandle(hSession);
要求
要求 | 值 |
---|---|
最低受支持的客户端 | Windows XP、Windows 2000 Professional 和 SP3 [仅限桌面应用] |
最低受支持的服务器 | Windows Server 2003、Windows 2000 Server SP3 [仅限桌面应用] |
目标平台 | Windows |
标头 | winhttp.h |
Library | Winhttp.lib |
DLL | Winhttp.dll |
可再发行组件 | Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更高版本。 |
另请参阅
反馈
https://aka.ms/ContentUserFeedback。
即将发布:在整个 2024 年,我们将逐步淘汰作为内容反馈机制的“GitHub 问题”,并将其取代为新的反馈系统。 有关详细信息,请参阅:提交和查看相关反馈