WinHttpGetProxyForUrlEx 函式 (winHTTP.h)

  • 發行項

WinHttpGetProxyForUrlEx 函式會擷取指定 URL 的 Proxy 數據。

語法

WINHTTPAPI DWORD WinHttpGetProxyForUrlEx(
  [in] HINTERNET                 hResolver,
  [in] PCWSTR                    pcwszUrl,
  [in] WINHTTP_AUTOPROXY_OPTIONS *pAutoProxyOptions,
  [in] DWORD_PTR                 pContext
);

參數

[in] hResolver

WinHttpCreateProxyResolver 函式所傳回的 WinHTTP 解析程式句柄。

[in] pcwszUrl

Null 終止 Unicode 字串的指標，其中包含將決定 Proxy 資訊的 URL。

[in] pAutoProxyOptions

WINHTTP_AUTOPROXY_OPTIONS 結構的指標，指定要使用的自動 Proxy 選項。

[in] pContext

將傳遞至完成回呼函式的內容數據。

傳回值

狀態代碼，指出作業的結果。

可能會傳回下列程序代碼。 Description
ERROR_IO_PENDING
 作業會以異步方式繼續。
ERROR_WINHTTP_AUTO_PROXY_SERVICE_ERROR
 當找不到指定 URL 的 Proxy 時， WinHttpGetProxyForUrlEx 傳 回。
ERROR_WINHTTP_BAD_AUTO_PROXY_SCRIPT
 在 Proxy 自動設定 (PAC) 檔案中執行腳本程式代碼時發生錯誤。
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE
 針對此作業提供的句柄類型不正確。
ERROR_WINHTTP_INVALID_URL
 URL 無效。
ERROR_WINHTTP_OPERATION_CANCELLED
 作業已取消，通常是因為要求在作業完成之前關閉的句柄。
ERROR_WINHTTP_UNABLE_TO_DOWNLOAD_SCRIPT
 無法下載 PAC 檔案。 例如，PAC URL 所參考的伺服器可能尚未連線，或伺服器傳回 404 NOT FOUND 回應。
ERROR_WINHTTP_UNRECOGNIZED_SCHEME
 PAC 檔案的 URL 指定了 “HTTP：” 或 “https：” 以外的配置。
ERROR_NOT_ENOUGH_MEMORY
 記憶體不足，無法完成要求的作業。 (Windows 錯誤碼)

備註

此函式會實作 Web Proxy 自動探索 (WPAD) 通訊協定，以自動設定 HTTP 要求的 Proxy 設定。 WPAD 通訊協定會下載 Proxy 自動設定 (PAC) 檔案，這是識別要用於指定目標 URL 之 Proxy 伺服器的腳本。 PAC 檔案通常是由公司網路環境內的IT部門所部署。 您可以明確指定 PAC 檔案的 URL，也可以指示 WinHttpGetProxyForUrlEx 自動探索局域網路上 PAC 檔案的位置。

WinHttpGetProxyForUrlEx 僅支援以 ECMAScript 為基礎的 PAC 檔案。

WinHttpGetProxyForUrlEx 必須以每個 URL 為基礎呼叫，因為 PAC 檔案可以針對不同的 URL 傳回不同的 Proxy 伺服器。 這很有用，因為 PAC 檔案可讓 IT 部門透過將 (哈希) lpcwszUrl) 參數指定的目標 URL (對應至 Proxy 伺服器陣列中的特定 Proxy，藉此實作 Proxy 伺服器負載平衡。

WinHttpGetProxyForUrlEx 會在 pAutoProxyOptions 結構的 dwFlags 成員中指定自動探索時快取 autoproxy URL 和 autoproxy 腳本。 如需詳細資訊，請參閱 Autoproxy 快取。

WinHttpGetProxyForUrlEx 提供 WinHttpGetProxyForUrl 未提供完全異步且可取消的 API。 WinHttpGetProxyForUrlEx 也會為應用程式提供 PAC 腳本所傳回的完整 Proxy 列表，讓應用程式能夠更妥善地處理故障轉移至 “DIRECT”，並視需要瞭解 SOCKS。

WinHttpGetProxyForUrlEx 一律會以異步方式執行，並在成功時立即傳回 ERROR_IO_PENDING 。 回呼是藉由在 WinHttpOpen 提供的 hSession 上呼叫 WinHttpSetStatusCallback 來設定。 或者，在 WinHttpCreateProxyResolver 所提供的 hResolver 上呼叫 WinHttpSetStatusCallback，以為每個呼叫指定回呼。

您必須在 WinHttpCreateProxyResolver 之前呼叫 WinHttpSetStatusCallback。 呼叫 WinHttpSetStatusCallback 時，請使用 WINHTTP_CALLBACK_FLAG_REQUEST_ERROR |WINHTTP_CALLBACK_FLAG_GETPROXYFORURL_COMPLETE。 如需使用回呼的資訊 ，請參閱WINHTTP_STATUS_CALLBACK 。

傳回狀態WINHTTP_CALLBACK_STATUS_GETPROXYFORURL_COMPLETE回呼之後，應用程式可以在用來發出 WinHttpGetProxyForUrlEx 的解析程式句柄上呼叫 WinHttpGetProxyResult，以接收該呼叫的結果。

如果在傳回ERROR_IO_PENDING之後呼叫失敗 ， 則會發出 WINHTTP_CALLBACK_STATUS_REQUEST_ERROR 的回呼。

此函式一律會執行跨進程。

規格需求

需求 值
最低支援的用戶端 Windows 8 [僅限傳統型應用程式]
最低支援的伺服器 Windows Server 2012 [僅限傳統型應用程式]
目標平台 Windows
標頭 winhttp.h
程式庫 Winhttp.lib
Dll Winhttp.dll