共用方式為


WinHttpConnect 函式 (winHTTP.h)

WinHttpConnect 函式會指定 HTTP 要求的初始目標伺服器,並傳回該初始目標的 HTTP 會話 HINTERNET 連線句柄。

語法

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

參數

[in] hSession

由先前 呼叫 winHttpOpen所傳回的有效 HINTERNET WinHTTP 會話句柄。

[in] pswzServerName

null字串的指標,其中包含 HTTP 伺服器的主機名。 或者,字串可以包含月臺的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)。 選取此埠不會自動建立安全的連線。 您仍必須使用具有 winHttpOpenRequestWINHTTP_FLAG_SECURE 旗標來指定使用安全交易語意。
INTERNET_DEFAULT_PORT
針對 HTTP 使用埠 80,而埠 443 則用於安全超文字傳輸通訊協定 (HTTPS)。

[in] dwReserved

此參數是保留的,而且必須是 0。

傳回值

如果連線成功,或 NULL,則傳回 HTTP 會話的有效連線句柄。 若要擷取擴充的錯誤資訊,請呼叫 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 在異步模式中使用 (也就是說,WINHTTP_FLAG_ASYNC 已在 winHttpOpen中設定 時),此函式仍會同步運作。 傳回值表示成功或失敗。 若要取得擴充的錯誤資訊,請呼叫 GetLastError

呼叫端應用程式使用 WinHttpConnect傳回的 HINTERNET 句柄之後,必須使用 winHttpCloseHandle 函式 關閉。

WinHttpConnect 指定目標 HTTP 伺服器,不過,如果重新導向要求,回應可能會來自另一部伺服器。 您可以使用 WINHTTP_OPTION_URL 旗標呼叫 winHttpQueryOption,以判斷傳送回應的伺服器 URL。

Windows XP 和 Windows 2000 的附註,請參閱 WinHttp 起始頁的 Run-Time 需求 一節。
 

例子

下列範例示範如何使用安全交易語意,從 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 with SP3 [僅限傳統型應用程式]
支援的最低伺服器 Windows Server 2003、Windows 2000 Server with SP3 [僅限傳統型應用程式]
目標平臺 窗戶
標頭 winhttp.h
連結庫 Winhttp.lib
DLL Winhttp.dll
可轉散發 Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更新版本。

另請參閱

關於 windows HTTP 服務 Microsoft

WinHTTP 版本

WinHttpCloseHandle

WinHttpOpen

WinHttpOpenRequest