winHttpQueryOption 函式 (winHTTP.h)

發行項
03/15/2023

WinHttpQueryOption函式會查詢指定控制碼上的網際網路選項。

語法

WINHTTPAPI BOOL WinHttpQueryOption(
  [in]      HINTERNET hInternet,
  [in]      DWORD     dwOption,
  [out]     LPVOID    lpBuffer,
  [in, out] LPDWORD   lpdwBufferLength
);

參數

[in] hInternet

要查詢資訊的 HINTERNET 控制碼。請注意，這可以是會話控制碼或要求控制碼，視查詢的選項而定;請參閱選項旗標主題，以判斷哪一個控制碼適合用於查詢特定選項。

[in] dwOption

不帶正負號的長整數值，其中包含要查詢的網際網路選項。這可以是其中一個選項旗標值。

[out] lpBuffer

接收選項設定之緩衝區的指標。 WinHttpQueryOption函式所傳回的字串會全域配置，因此呼叫端應用程式在使用完字串時，必須全域釋放字串。將此參數設定為 Null 會導致此函式傳回 FALSE。接著，呼叫 GetLastError 會傳回 ERROR_INSUFFICIENT_BUFFER，而 lpdwBufferLength 包含保存要求資訊所需的位元組數目。

[in, out] lpdwBufferLength

無符號長整數變數的指標，其中包含 lpBuffer的長度，以位元組為單位。當函式傳回時，變數會收到放入 lpBuffer的資料長度。如果 GetLastError 傳回ERROR_INSUFFICIENT_BUFFER，此參數會收到保存要求資訊所需的位元組數目。

傳回值

如果成功，則傳回 TRUE ，否則傳回 FALSE 。若要取得特定的錯誤訊息，請呼叫 GetLastError。傳回的錯誤碼如下：

錯誤碼	描述
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	無法執行要求的作業，因為提供的控制碼不是處於正確的狀態。
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	此作業所提供的控制碼類型不正確。
ERROR_WINHTTP_INTERNAL_ERROR	發生內部錯誤。
ERROR_WINHTTP_INVALID_OPTION	指定了不正確選項值。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足，無法完成要求的作業。 (Windows 錯誤碼)

備註

即使 WinHTTP 用於非同步模式 (亦即，在WinHttpOpen) 中設定WINHTTP_FLAG_ASYNC時，此函式仍會同步運作。傳回值表示成功或失敗。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

如果指定的控制碼類型不正確選項旗標傳遞至dwOption參數，GetLastError會傳回ERROR_INVALID_PARAMETER。

注意針對 Windows XP 和 Windows 2000，請參閱 WinHttp 起始頁的執行時間需求一節。

範例

此範例示範如何擷取連線逾時值：

    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 或更新版本。