WinHttpConnect 函数 (winhttp.h)

项目
08/27/2023

WinHttpConnect 函数指定 HTTP 请求的初始目标服务器，并将 HINTERNET 连接句柄返回到该初始目标的 HTTP 会话。

语法

WINHTTPAPI HINTERNET WinHttpConnect(
  [in] HINTERNET     hSession,
  [in] LPCWSTR       pswzServerName,
  [in] INTERNET_PORT nServerPort,
  [in] DWORD         dwReserved
);

参数

[in] hSession

由先前调用 WinHttpOpen 返回的有效 HINTERNET WinHTTP 会话句柄。

[in] pswzServerName

指向包含 HTTP 服务器的主机名的 以 null 结尾的字符串的指针。或者，字符串可以包含 ASCII 中站点的 IP 地址，例如 10.0.1.45。请注意，WinHttp 不接受未首先将国际主机名转换为 Punycode。有关详细信息，请参阅处理国际化域名 (IDN) 。

[in] nServerPort

无符号整数，指定建立连接的服务器上的 TCP/IP 端口。此参数可以是任何有效的 TCP/IP 端口号，也可以是以下值之一。

值	含义
INTERNET_DEFAULT_HTTP_PORT	使用 HTTP 服务器的默认端口 (端口 80) 。
INTERNET_DEFAULT_HTTPS_PORT	使用 HTTPS 服务器的默认端口 (端口 443) 。选择此端口不会自动建立安全连接。你仍必须通过将 WINHTTP_FLAG_SECURE 标志与 WinHttpOpenRequest 一起使用来指定使用安全事务语义。
INTERNET_DEFAULT_PORT	将端口 80 用于 HTTP，将端口 443 用于安全超文本传输协议 (HTTPS) 。

[in] dwReserved

此参数是保留的，必须为 0。

返回值

如果连接成功，则返回 HTTP 会话的有效连接句柄，否则返回 NULL 。若要检索扩展的错误信息，请调用 GetLastError。返回的错误代码如下。

错误代码	说明
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	为此操作提供的句柄类型不正确。
ERROR_WINHTTP_INTERNAL_ERROR	发生了内部错误。
ERROR_WINHTTP_INVALID_URL	URL 无效。
ERROR_WINHTTP_OPERATION_CANCELLED	该操作被取消，通常是因为操作完成之前，操作所针对的句柄已关闭。
ERROR_WINHTTP_UNRECOGNIZED_SCHEME	无法识别或不支持 URL 方案。
ERROR_WINHTTP_SHUTDOWN	WinHTTP 函数支持正在关闭或卸载。
ERROR_NOT_ENOUGH_MEMORY	内存不足，无法完成请求的操作。 (Windows 错误代码)

注解

即使在异步模式下使用 WinHTTP (即在 WinHttpOpen) 中设置了WINHTTP_FLAG_ASYNC时，此函数也会同步运行。返回值指示成功或失败。要获得更多的错误信息，请调用 GetLastError。

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

WinHttpConnect 指定目标 HTTP 服务器，但如果重定向了请求，则响应可能来自另一台服务器。可以通过使用 WINHTTP_OPTION_URL 标志调用 WinHttpQueryOption 来确定发送响应的服务器 URL。

注意对于 Windows XP 和 Windows 2000，请参阅 WinHttp 起始页的运行时要求部分。

示例

以下示例演示如何使用安全事务语义从 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 或更高版本。