WinHttpGetProxyForUrlEx 函数 (winhttp.h)

  • 项目

WinHttpGetProxyForUrlEx 函数检索指定 URL 的代理数据。

语法

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 字符串的指针，该字符串包含将为其确定代理信息的 URL。

[in] pAutoProxyOptions

指向 WINHTTP_AUTOPROXY_OPTIONS 结构的指针，该结构指定要使用的自动代理选项。

[in] pContext

将传递给完成回调函数的上下文数据。

返回值

指示操作结果的状态代码。

可能会返回以下代码。 说明
ERROR_IO_PENDING
 操作以异步方式继续。
ERROR_WINHTTP_AUTO_PROXY_SERVICE_ERROR
 当无法找到指定 URL 的代理时 ，由 WinHttpGetProxyForUrlEx 返回。
ERROR_WINHTTP_BAD_AUTO_PROXY_SCRIPT
 执行代理自动配置 (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 代理自动发现 (WPAD) 协议，用于自动为 HTTP 请求配置代理设置。 WPAD 协议下载代理自动配置 (PAC) 文件，该文件是标识要用于给定目标 URL 的代理服务器的脚本。 PAC 文件通常由 IT 部门在企业网络环境中部署。 可以显式指定 PAC 文件的 URL，也可以指示 WinHttpGetProxyForUrlEx 在本地网络上自动发现 PAC 文件的位置。

WinHttpGetProxyForUrlEx 仅支持基于 ECMAScript 的 PAC 文件。

WinHttpGetProxyForUrlEx 必须按 URL 调用，因为 PAC 文件可以为不同的 URL 返回不同的代理服务器。 这很有用，因为 PAC 文件允许 IT 部门通过将 (哈希) lpcwszUrl 参数 (指定的目标 URL) (映射到代理服务器数组中的某个代理来实现代理服务器负载均衡。

在 pAutoProxyOptions 结构的 dwFlags 成员中指定自动发现时，WinHttpGetProxyForUrlEx 将缓存 autoproxy URL 和 autoproxy 脚本。 有关详细信息，请参阅 Autoproxy 缓存。

WinHttpGetProxyForUrlEx 提供 WinHttpGetProxyForUrl 没有的完全异步且可取消的 API。 WinHttpGetProxyForUrlEx 还为应用程序提供 PAC 脚本返回的完整代理列表，使应用程序能够更好地处理到“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
Library Winhttp.lib
DLL Winhttp.dll