WinHttpQueryOption 函数 (winhttp.h)

项目
08/27/2023

WinHttpQueryOption 函数查询指定句柄上的 Internet 选项。

语法

WINHTTPAPI BOOL WinHttpQueryOption(
  [in]      HINTERNET hInternet,
  [in]      DWORD     dwOption,
  [out]     LPVOID    lpBuffer,
  [in, out] LPDWORD   lpdwBufferLength
);

参数

[in] hInternet

要查询信息的 HINTERNET 句柄。请注意，这可以是会话句柄或请求句柄，具体取决于要查询的选项;请参阅选项标志主题，确定哪个句柄适合用于查询特定选项。

[in] dwOption

包含要查询的 Internet 选项的无符号长整数值。这可以是选项标志值之一。

[out] lpBuffer

指向接收选项设置的缓冲区的指针。 WinHttpQueryOption 函数返回的字符串是全局分配的，因此调用应用程序在完成使用该字符串后必须全局释放该字符串。将此参数设置为 NULL 会导致此函数返回 FALSE。然后调用 GetLastError 将返回ERROR_INSUFFICIENT_BUFFER， lpdwBufferLength 包含保存所请求信息所需的字节数。

[in, out] lpdwBufferLength

指向包含 lpBuffer 长度（以字节为单位）的无符号长整数变量的指针。当函数返回时，变量接收放入 lpBuffer 的数据的长度。如果 GetLastError 返回ERROR_INSUFFICIENT_BUFFER，则此参数接收保存所请求信息所需的字节数。

返回值

如果成功，则返回 TRUE ，否则返回 FALSE 。若要获取特定错误消息，请调用 GetLastError。返回的错误代码如下：

错误代码	说明
ERROR_WINHTTP_INCORRECT_HANDLE_STATE	无法执行请求的操作，因为提供的句柄未处于正确的状态。
ERROR_WINHTTP_INCORRECT_HANDLE_TYPE	为此操作提供的句柄类型不正确。
ERROR_WINHTTP_INTERNAL_ERROR	发生了内部错误。
ERROR_WINHTTP_INVALID_OPTION	指定的选项值无效。
ERROR_NOT_ENOUGH_MEMORY	内存不足，无法完成请求的操作。 (Windows 错误代码)

备注

即使在异步模式下使用 WinHTTP (即在 WinHttpOpen) 中设置了WINHTTP_FLAG_ASYNC时，此函数也会同步运行。返回值指示成功或失败。要获得更多的错误信息，请调用 GetLastError。

如果将对指定句柄类型无效的选项标志传递给 dwOption 参数，GetLastError 将返回ERROR_INVALID_PARAMETER。

注意对于 Windows XP 和 Windows 2000，请参阅 WinHttp 起始页的运行时要求部分。

示例

此示例演示如何检索连接超时值：

    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 或更高版本。