WinHttpOpen 函式 (winHTTP.h)

  • 發行項

WinHttpOpen函式會針對應用程式初始化 WinHTTP 函式，並傳回 WinHTTP 會話控制碼。

語法

WINHTTPAPI HINTERNET WinHttpOpen(
  [in, optional] LPCWSTR pszAgentW,
  [in]           DWORD   dwAccessType,
  [in]           LPCWSTR pszProxyW,
  [in]           LPCWSTR pszProxyBypassW,
  [in]           DWORD   dwFlags
);

參數

[in, optional] pszAgentW

字串變數的指標，其中包含呼叫 WinHTTP 函式的應用程式或機構名稱。 此名稱會當做 HTTP 通訊協定中的 使用者代理程式 使用。

[in] dwAccessType

需要存取的類型。 這可以是下列其中一個值。

值 意義
WINHTTP_ACCESS_TYPE_NO_PROXY
 直接解析所有主機名稱，而不使用 Proxy。
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY
重要此選項在 Windows 8.1 和更新版本上已被取代。 請改用WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY。
 
從登錄擷取靜態 Proxy 或直接組態。 WINHTTP_ACCESS_TYPE_DEFAULT_PROXY 不會繼承瀏覽器 Proxy 設定。

WinHTTP Proxy 設定是由其中一種機制所設定。
WINHTTP_ACCESS_TYPE_NAMED_PROXY
 除非提供 Proxy 略過清單，且要解析的名稱會略過 Proxy，否則會將要求傳遞至 Proxy。 在此情況下，此函式會使用針對 pwszProxyName 和 pwszProxyBypass傳遞的值。
WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY
 使用系統和每個使用者 Proxy 設定， (包括 Internet Explorer Proxy 組態) 來判斷要使用的 Proxy/Proxy。 自動嘗試處理多個 Proxy 之間的容錯移轉、每個介面的不同 Proxy 組態，以及驗證。 Windows 8.1和更新版本中支援。

[in] pszProxyW

字串變數的指標，其中包含 Proxy 存取指定時所要使用的 Proxy 伺服器名稱，方法是將 dwAccessType 設定為 WINHTTP_ACCESS_TYPE_NAMED_PROXY。 WinHTTP 函式只會辨識 HTTP 的 CERN 類型 Proxy。 如果 dwAccessType 未設定為 WINHTTP_ACCESS_TYPE_NAMED_PROXY，則必須將此參數設定為 WINHTTP_NO_PROXY_NAME。

[in] pszProxyBypassW

字串變數的指標，其中包含選擇性的以分號分隔的主機名稱或 IP 位址清單，或兩者，當 dwAccessType 設定為 WINHTTP_ACCESS_TYPE_NAMED_PROXY時，不應該透過 Proxy 路由傳送。 清單可以包含萬用字元。 請勿使用空字串，因為 WinHttpOpen 函式會使用它作為 Proxy 略過清單。 如果此參數將清單中的 「 < local > 」 宏指定為唯一的專案，則此函式會略過不包含句點的任何主機名稱。 如果 dwAccessType 未設定為 WINHTTP_ACCESS_TYPE_NAMED_PROXY，則必須將此參數設定為 WINHTTP_NO_PROXY_BYPASS。

[in] dwFlags

不帶正負號的長整數值，其中包含指出影響此函式行為的各種選項的旗標。 此參數可以有下列值。

值 意義
WINHTTP_FLAG_ASYNC
 以非同步方式使用 WinHTTP 函式。 根據預設，所有使用傳回 HINTERNET 控制碼的 WinHTTP 函式都會同步執行。 設定此旗標時，呼叫端必須透過 WinHttpSetStatusCallback指定回呼函式。
WINHTTP_FLAG_SECURE_DEFAULTS
 設定此旗標時，WinHttp 將需要使用 TLS 1.2 或更新版本。 如果呼叫端嘗試透過 設定WINHTTP_OPTION_SECURE_PROTOCOLS來啟用較舊的 TLS 版本， 則會失敗並ERROR_ACCESS_DENIED。 此外，TLS 後援將會停用。 請注意，設定此旗標也會 設定旗標WINHTTP_FLAG_ASYNC。

傳回值

如果成功，則傳回有效的會話控制碼，否則傳回 Null 。 若要擷取擴充的錯誤資訊，請呼叫 GetLastError。 傳回的錯誤碼如下。

錯誤碼 描述
ERROR_WINHTTP_INTERNAL_ERROR
 發生內部錯誤。
ERROR_NOT_ENOUGH_MEMORY
 記憶體不足，無法完成要求的作業。 (Windows 錯誤碼)

備註

強烈建議您在非同步模式中使用 WinHTTP (也就是在WinHttpOpen中設定WINHTTP_FLAG_ASYNC時，讓傳回的 HINTERNET使用方式變成非同步) 。 傳回值表示成功或失敗。 若要擷取擴充的錯誤資訊，請呼叫 GetLastError。

WinHttpOpen函式是應用程式所呼叫的第一個 WinHTTP 函式。 它會初始化內部 WinHTTP 資料結構，並準備未來從應用程式呼叫。 當應用程式使用 WinHTTP 函式完成時，它必須呼叫 WinHttpCloseHandle 以釋放會話控制碼和任何相關聯的資源。

應用程式可以對 WinHttpOpen進行任意數目的呼叫，但單一呼叫通常就已足夠。 每次呼叫 WinHttpOpen 都會開啟新的會話內容。 由於使用者資料不會在多個會話內容之間共用，因此代表多個使用者提出要求的應用程式應該為每個使用者建立個別的會話，以免共用使用者特定的 Cookie 和驗證狀態。 應用程式應該為每個 WinHttpOpen 實例定義不同的行為，例如為每個實例設定的不同 Proxy 伺服器。

呼叫端應用程式使用WinHttpOpen所傳回的HINTERNET控制碼完成之後，必須使用WinHttpCloseHandle函式來關閉它。

注意 如需 Windows XP 和 Windows 2000，請參閱 執行時間需求。
 

範例

下列範例程式碼示範如何擷取預設連線逾時值。


    DWORD data;
    DWORD dwSize = sizeof(DWORD);

    // Use WinHttpOpen to obtain an HINTERNET handle.
    HINTERNET hSession = WinHttpOpen(L"A WinHTTP Example Program/1.0", 
                                    WINHTTP_ACCESS_TYPE_DEFAULT_PROXY,
                                    WINHTTP_NO_PROXY_NAME, 
                                    WINHTTP_NO_PROXY_BYPASS, 0);
    if (hSession)
    {


        // Use WinHttpQueryOption to retrieve internet options.
        if (WinHttpQueryOption( hSession, 
                                WINHTTP_OPTION_CONNECT_TIMEOUT, 
                                &data, &dwSize))
        {
            printf("Connection timeout: %u ms\n\n",data);
        }
        else
        {
            printf( "Error %u in WinHttpQueryOption.\n", 
                    GetLastError());
        }        
        
        // When finished, release the HINTERNET handle.
        WinHttpCloseHandle(hSession);
    }
    else
    {
        printf("Error %u in WinHttpOpen.\n", GetLastError());
    }

規格需求

   
最低支援的用戶端 Windows XP、Windows 2000 Professional 與 SP3 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2003、具有 SP3 的 Windows 2000 Server [僅限傳統型應用程式]
目標平台 Windows
標頭 winHTTP.h
程式庫 WinHTTP.lib
Dll Winhttp.dll
可轉散發套件 Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更新版本。

另請參閱

關於 Microsoft Windows HTTP Services (WinHTTP)

WinHTTP 版本

WinHttpCloseHandle