WinHttpSetTimeouts 函式 (winHTTP.h)

發行項
01/12/2024

WinHttpSetTimeouts 函式會設定與 HTTP 交易相關的逾時。

語法

WINHTTPAPI BOOL WinHttpSetTimeouts(
  [in] HINTERNET hInternet,
  [in] int       nResolveTimeout,
  [in] int       nConnectTimeout,
  [in] int       nSendTimeout,
  [in] int       nReceiveTimeout
);

參數

[in] hInternet

WinHttpOpen 或 WinHttpOpenRequest 所傳回的 HINTERNET 句柄。

[in] nResolveTimeout

整數類型的值，指定用於名稱解析的逾時值，以毫秒為單位。如果解決時間超過這個逾時值，則會取消要求。初始值為零，這表示沒有逾時 (無限) 。

Windows Vista 和 Windows XP： 如果使用 NAME_RESOLUTION_TIMEOUT指定 DNS 逾時，則每個要求會有一個線程的額外負荷。

[in] nConnectTimeout

整數類型的值，指定用於伺服器連接要求的逾時值，以毫秒為單位。如果連線要求花費的時間超過這個逾時值，則會取消要求。初始值為 60,000 (60 秒) 。

不論此參數的值為何，TCP/IP 在三次 SYN/ACK 交換期間設定套接字時可能會逾時。

[in] nSendTimeout

整數類型的值，指定用於傳送要求的逾時值，以毫秒為單位。如果傳送要求的時間超過這個逾時值，則會取消傳送。初始值為 30,000 (30 秒) 。

[in] nReceiveTimeout

整數類型的值，指定以毫秒為單位的逾時值，以接收要求的回應。如果回應花費的時間超過這個逾時值，則會取消要求。初始值為 30,000 (30 秒) 。

傳回值

如果成功，則傳回 TRUE ，否則傳回 FALSE 。如需擴充錯誤資訊，請呼叫 GetLastError。傳回的錯誤碼如下。

錯誤碼	描述
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	無法執行要求的作業，因為提供的句柄未處於正確的狀態。
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	針對此作業提供的句柄類型不正確。
ERROR_WINHTTP_INTERNAL_ERROR	發生內部錯誤。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足，無法完成要求的作業。 (Windows 錯誤碼)
ERROR_INVALID_PARAMETER	一或多個逾時參數具有 -1 以外的負值。

備註

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

值為 0 或 -1 會將逾時設定為無限等候。大於 0 的值會以毫秒為單位設定逾時值。例如，30,000 會將逾時設定為30秒。 -1 以外的所有負值都會導致函式失敗，並出現ERROR_INVALID_PARAMETER。

重要如果使用 WinHttpSetOption 和 WINHTTP_OPTION_RECEIVE_TIMEOUT設定小型逾時，它可以覆寫以 dwReceiveTimeout 參數設定的值，導致回應早於預期結束。若要避免這種情況，請勿使用小於使用 dwReceiveTimeout 設定值的 WINHTTP_OPTION_RECEIVE_TIMEOUT 選項來設定逾時。

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

範例

此範例示範如何使用 WinHttpSetTimeouts 來設定新的逾時值。

    // 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 WinHttpSetTimeouts to set a new time-out values.
        if (!WinHttpSetTimeouts( hSession, 10000, 10000, 10000, 10000))
            printf( "Error %u in WinHttpSetTimeouts.\n", GetLastError());
              
        // PLACE ADDITIONAL CODE HERE.
    
        // 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、Windows 2000 Server 與 SP3 [僅限桌面應用程式]
目標平台	Windows
標頭	winhttp.h
程式庫	Winhttp.lib
Dll	Winhttp.dll
可轉散發套件	Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更新版本。