WinHttpOpen 函数 (winhttp.h)

  • 项目

对于应用程序， WinHttpOpen 函数初始化 WinHTTP 函数的使用并返回 WinHTTP 会话句柄。

语法

WINHTTPAPI HINTERNET WinHttpOpen(
  [in, optional] LPCWSTR pszAgentW,
  [in]           DWORD   dwAccessType,
  [in]           LPCWSTR pszProxyW,
  [in]           LPCWSTR pszProxyBypassW,
  [in]           DWORD   dwFlags
);

参数

[in, optional] pszAgentW

指向字符串变量的指针，该变量包含调用 WinHTTP 函数的应用程序或实体的名称。 此名称用作 HTTP 协议中的 用户代理 。

[in] dwAccessType

所需的访问类型。 这可以是以下值之一。

值 含义
WINHTTP_ACCESS_TYPE_NO_PROXY
 在没有代理的情况下直接解析所有主机名。
WINHTTP_ACCESS_TYPE_DEFAULT_PROXY
重要Windows 8.1 及更新后，已弃用此选项。 请改用 WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY。
 
从注册表检索静态代理或直接配置。 WINHTTP_ACCESS_TYPE_DEFAULT_PROXY 不继承浏览器代理设置。

WinHTTP 代理配置由其中一种机制设置。
WINHTTP_ACCESS_TYPE_NAMED_PROXY
 除非提供了代理绕过列表并且要解析的名称会绕过代理，否则会将请求传递到代理。 在这种情况下，此函数使用为 pwszProxyName 和 pwszProxyBypass 传递的值。
WINHTTP_ACCESS_TYPE_AUTOMATIC_PROXY
 使用系统和每用户代理设置 (包括 Internet Explorer 代理配置) 来确定要使用的代理/代理。 自动尝试处理多个代理之间的故障转移、每个接口的不同代理配置和身份验证。 在 Windows 8.1 及更新版本中受支持。

[in] pszProxyW

指向字符串变量的指针，该变量包含通过将 dwAccessType 设置为 WINHTTP_ACCESS_TYPE_NAMED_PROXY 指定代理访问时要使用的代理服务器的名称。 WinHTTP 函数仅识别 HTTP 的 CERN 类型代理。 如果未将 dwAccessType 设置为 WINHTTP_ACCESS_TYPE_NAMED_PROXY，则必须将此参数设置为 WINHTTP_NO_PROXY_NAME。

[in] pszProxyBypassW

指向字符串变量的指针，该变量包含以分号分隔的主机名或 IP 地址的可选列表，或者两者，当 dwAccessType 设置为 WINHTTP_ACCESS_TYPE_NAMED_PROXY 时，不应通过代理路由这些名称或 IP 地址。 列表可以包含通配符。 请勿使用空字符串，因为 WinHttpOpen 函数将其用作代理绕过列表。 如果此参数将列表中的“<local>”宏指定为唯一条目，则此函数将绕过任何不包含句点的主机名。 如果未将 dwAccessType 设置为 WINHTTP_ACCESS_TYPE_NAMED_PROXY，则必须将此参数设置为 WINHTTP_NO_PROXY_BYPASS。

[in] dwFlags

无符号长整数值，其中包含指示影响此函数行为的各种选项的标志。 此参数可以具有以下值。

值 含义
WINHTTP_FLAG_ASYNC
 异步使用 WinHTTP 函数。 默认情况下，使用返回的 HINTERNET 句柄的所有 WinHTTP 函数都是同步执行的。 设置此标志后，调用方需要通过 WinHttpSetStatusCallback 指定回调函数。
WINHTTP_FLAG_SECURE_DEFAULTS
 设置此标志后，WinHttp 需要使用 TLS 1.2 或更高版本。 如果调用方尝试通过设置 WINHTTP_OPTION_SECURE_PROTOCOLS 来启用较旧的 TLS 版本，则会失败并 显示ERROR_ACCESS_DENIED。 此外，将禁用 TLS 回退。 请注意，设置此标志还会设置 标志WINHTTP_FLAG_ASYNC。

返回值

如果成功，则返回有效的会话句柄，否则返回 NULL 。 若要检索扩展的错误信息，请调用 GetLastError。 返回的错误代码如下。

错误代码 说明
ERROR_WINHTTP_INTERNAL_ERROR
 发生了内部错误。
ERROR_NOT_ENOUGH_MEMORY
 内存不足，无法完成请求的操作。 (Windows 错误代码)

注解

强烈建议在异步模式下使用 WinHTTP， (即在 WinHttpOpen 中设置了WINHTTP_FLAG_ASYNC，以便使用返回的 HINTERNET 成为异步) 。 返回值指示成功或失败。 若要检索扩展的错误信息，请调用 GetLastError。

WinHttpOpen 函数是应用程序调用的第一个 WinHTTP 函数。 它初始化内部 WinHTTP 数据结构，并准备将来从应用程序调用。 当应用程序完成使用 WinHTTP 函数时，它必须调用 WinHttpCloseHandle 以释放会话句柄和任何关联的资源。

应用程序可以对 WinHttpOpen 进行任意数量的调用，但一次调用通常就足够了。 每次调用 WinHttpOpen 都会 打开一个新的会话上下文。 由于用户数据不会在多个会话上下文之间共享，因此代表多个用户发出请求的应用程序应为每个用户创建单独的会话，以免共享特定于用户的 Cookie 和身份验证状态。 应用程序应为每个 WinHttpOpen 实例定义单独的行为，例如为每个实例配置的不同代理服务器。

调用应用程序使用 WinHttpOpen 返回的 HINTERNET 句柄后，必须使用 WinHttpCloseHandle 函数将其关闭。

注意 对于 Windows XP 和 Windows 2000，请参阅 运行时要求。
 

示例

以下示例代码演示如何检索默认连接超时值。


    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、Windows 2000 Server SP3 [仅限桌面应用]
目标平台 Windows
标头 winhttp.h
Library Winhttp.lib
DLL Winhttp.dll
可再发行组件 Windows XP 和 Windows 2000 上的 WinHTTP 5.0 和 Internet Explorer 5.01 或更高版本。

另请参阅

关于 Microsoft Windows HTTP Services (WinHTTP)

WinHTTP 版本

WinHttpCloseHandle