WinHttpSetOption 函式 (winHTTP.h)

發行項
03/04/2024

WinHttpSetOption 函式會設定因特網選項。

語法

WINHTTPAPI BOOL WinHttpSetOption(
  [in] HINTERNET hInternet,
  [in] DWORD     dwOption,
  [in] LPVOID    lpBuffer,
  [in] DWORD     dwBufferLength
);

參數

[in] hInternet

要設定數據的 HINTERNET 句柄。請注意，這可以是會話句柄或要求句柄，視所設定的選項而定。如需有關如何判斷哪一個句柄適合用於設定特定選項的詳細資訊，請參閱選項旗標。

[in] dwOption

不帶正負號的長整數值，其中包含要設定的因特網選項。這可以是其中一個選項旗標值。

[in] lpBuffer

緩衝區的指標，其中包含選項設定。

[in] dwBufferLength

包含 lpBuffer 緩衝區長度的不帶正負號長整數值。緩衝區的長度是以下列選項的字元指定;針對所有其他選項，會以位元組為單位指定長度。

傳回值

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

錯誤碼	描述
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	無法執行要求的作業，因為提供的句柄未處於正確的狀態。
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	針對此作業提供的句柄類型不正確。
ERROR_WINHTTP_INTERNAL_ERROR	發生內部錯誤。
ERROR_WINHTTP_INVALID_OPTION	對 WinHttpQueryOption 或 WinHttpSetOption 的要求指定了無效的選項值。
ERROR_INVALID_PARAMETER	參數無效。如果 WINHTTP_OPTION_WEB_SOCKET_KEEPALIVE_INTERVAL 設定為小於 15000 的值，則會傳回此值。
ERROR_WINHTTP_OPTION_NOT_SETTABLE	無法設定要求的選項，只查詢。
ERROR_INVALID_PARAMETER	參數無效。如果 WINHTTP_OPTION_WEB_SOCKET_KEEPALIVE_INTERVAL 設定為小於 15000 的值，則會傳回此值。
ERROR_NOT_ENOUGH_MEMORY	記憶體不足，無法完成要求的作業。 (Windows 錯誤碼)

備註

傳遞至 WinHttpSetOption 的認證可能會意外以純文本傳送。強烈建議您使用 WinHttpQueryAuthSchemes 和 WinHttpSetCredentials 而非 WinHttpSetOption 來設定認證。

注意不過，使用 Passport 驗證時，回應 407 狀態代碼的 WinHTTP 應用程式必須使用 WinHttpSetOption 來提供 Proxy 認證，而不是 WinHttpSetCredentials。只有在使用 Passport 驗證時，才會發生這種情況;在其他所有情況下，請使用 WinHttpSetCredentials。

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

如果指定無法設定的選項旗標，GetLastError 會傳回錯誤ERROR_INVALID_PARAMETER。

如需顯示 WinHttpSetOption 使用方式的詳細資訊和程式代碼範例，請參閱 WinHTTP 中的驗證。

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

規格需求

需求	值
最低支援的用戶端	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 或更新版本。