选项标志

WinHttpQueryOption 和 WinHttpSetOption 支持以下选项标志。

WINHTTP_OPTION_ASSURED_NON_BLOCKING_CALLBACKS

默认值为 FALSE。 如果设置为 TRUE，则当客户端应用程序阻止状态回调时，WinHTTP 不能保证进度。

客户端应用程序必须特别小心，在不阻止的情况下在回调中执行最小作，并尽快返回，特别是不得等待任何后续的 WinHTTP 调用。 如果未遵循这些准则，则可能会产生负面影响或潜在的应用程序挂起。 如果按规定方式使用，此选项可能会提高性能。

WINHTTP_OPTION_AUTOLOGON_POLICY

设置一个无符号长整数值，该值指定具有以下值之一的 自动登录策略 。

WINHTTP_OPTION_BACKGROUND_CONNECTIONS

在会话句柄上设置此选项时，必须传递要打开的连接数。 然后，在首次发送请求时，WinHttp 不只打开单个连接，而是并行打开多个连接。 这可以提高对同一目标的后续请求的性能，这不会产生连接建立的开销。

WINHTTP_OPTION_CALLBACK

使用 WinHttpSetStatusCallback 检索指向回调函数集的指针。

WINHTTP_OPTION_CLIENT_CERT_CONTEXT

设置客户端证书上下文。 如果应用程序收到 ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED，则必须调用 WinHttpSetOption 才能提供证书，然后重试请求。 作为处理此选项的一部分，WinHttp 在调用方提供的证书上下文上调用 CertDuplicateCertificateContext ，以便调用方可以独立释放证书上下文。

当服务器请求客户端证书时， WinHttpSendRequest 或 WinHttpReceiveResponse 将返回 ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED 错误。 如果服务器请求证书但不需要证书，则应用程序可以指定此选项以指示它没有证书。 服务器可以选择其他身份验证方案，或允许匿名访问服务器。 应用程序在 WinHttpSetOption 的 lpBuffer 参数中提供WINHTTP_NO_CLIENT_CERT_CONTEXT宏，如以下代码示例所示。

BOOL fRet = WinHttpSetOption(hRequest,
                             WINHTTP_OPTION_CLIENT_CERT_CONTEXT,
                             WINHTTP_NO_CLIENT_CERT_CONTEXT,
                             0);

如果服务器需要客户端证书，它可能会发送 403 HTTP 状态代码来响应。 有关详细信息，请参阅 WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST 选项。

WINHTTP_OPTION_CLIENT_CERT_ISSUER_LIST

当 WinHttpSendRequest 或 WinHttpReceiveResponse 的错误ERROR_WINHTTP_CLIENT_AUTH_CERT_NEEDED时，检索SecPkgContext_IssuerListInfoEx结构。 结构中的颁发者列表包含服务器中可接受的证书颁发机构（CA）列表。 客户端应用程序可以筛选 CA 列表，以检索用于 SSL 身份验证的客户端证书。

或者，如果服务器请求客户端证书，但不要求它，应用程序可以使用 WINHTTP_OPTION_CLIENT_CERT_CONTEXT 选项调用 WinHttpSetOption。 有关详细信息，请参阅 WINHTTP_OPTION_CLIENT_CERT_CONTEXT 选项。

WINHTTP_OPTION_CODEPAGE

设置用于处理 URL（即查询字符串） 的代码页 。 默认值为 UTF8。

WINHTTP_OPTION_CONFIGURE_PASSPORT_AUTH

设置一个无符号长整数值，该值指定是否启用 WinHTTP 身份验证中的 Passport 身份验证 。 该值可以是下列值之一：

WINHTTP_OPTION_CONNECT_RETRIES

设置或检索一个无符号长整数值，该值包含WinHTTP 尝试连接到主机的次数。 Microsoft Windows HTTP 服务（WinHTTP）仅尝试每个 Internet 协议 （IP） 地址一次。 例如，如果尝试连接到具有 10 个 IP 地址且 WINHTTP_OPTION_CONNECT_RETRIES 为 7 的多宿主主机，则 WinHTTP 仅尝试连接到前七个 IP 地址。 如果同一组 10 个 IP 地址，如果 WINHTTP_OPTION_CONNECT_RETRIES 设置为 20，WinHTTP 将只尝试 10 个 IP 地址中的每一个。 如果连接尝试在指定的尝试次数后仍然失败，或者连接超时在指定次数之后过期，则会取消请求。 WINHTTP_OPTION_CONNECT_RETRIES的默认值为五次尝试。

WINHTTP_OPTION_CONNECT_TIMEOUT

设置或检索包含超时值的无符号长整数值（以毫秒为单位）。 将此选项设置为无限（0xFFFFFFFF）将禁用此计时器。

如果 TCP 连接请求花费的时间超过此超时值，则会取消请求。 默认超时为 60 秒。 尝试连接到单个主机（多宿主主机）的多个 IP 地址时，超时限制针对每个单独的连接。

WINHTTP_OPTION_CONNECTION_INFO

检索 WinHttpReceiveResponse 返回时生成响应的请求的源和目标 IP 地址和端口。 应用程序使用 WINHTTP_OPTION_CONNECTION_INFO 选项调用 WinHttpQueryOption，并在 lpBuffer 参数中提供WINHTTP_CONNECTION_INFO结构。 有关详细信息，请参阅 WINHTTP_CONNECTION_INFO。

适用于：Windows XP SP2 及更高版本;Windows 2003 SP1 及更高版本。

WINHTTP_OPTION_CONNECTION_GUID

使用 GUID 标记与 WinHTTP 请求句柄关联的连接。 这允许自定义控制哪些请求使用具有 WINHTTP_OPTION_MATCH_CONNECTION_GUID 选项的连接组。

WINHTTP_OPTION_CONNECTION_STATS_V0

检索请求使用的基础连接的 TCP_INFO_v0 结构。 返回的结构可能包含通过同一连接发送的先前请求的统计信息。

WINHTTP_OPTION_CONNECTION_STATS_V1

检索请求使用的基础连接的 TCP_INFO_v1 结构。 返回的结构可能包含通过同一连接发送的先前请求的统计信息。

WINHTTP_OPTION_CONTEXT_VALUE

设置或检索包含指向与此 HINTERNET 句柄关联的上下文值的指针的DWORD_PTR。 使用缓冲区中存储的值，并为 WINHTTP_OPTION_CONTEXT_VALUE 选项标志分配一个新值。

WINHTTP_OPTION_DECOMPRESSION

设置标志的 DWORD，用于确定 WinHTTP 是否会使用压缩的内容编码自动解压缩响应正文。 WinHTTP 还将设置适当的 Accept-Encoding 标头，覆盖调用方提供的任何标头。 支持的值有：

默认情况下，WinHTTP 将向调用方提供未修改的压缩响应。

WINHTTP_OPTION_DISABLE_CERT_CHAIN_BUILDING

在 WinHttp 会话句柄上设置此选项可让你启用/禁用是否生成服务器证书链。

WINHTTP_OPTION_DISABLE_FEATURE

设置一个无符号长整数值，该值指定以下一个或多个标志禁用哪些功能。 请注意，只有在使用 WinHttpOpenRequest 创建请求句柄后，才应在请求句柄上将此功能传递给 WinHttpSetOption，并在使用 WinHttpSendRequest 发送请求之前。

WINHTTP_OPTION_DISABLE_GLOBAL_POOLING

禁用全局跨会话池。 这是建议的做法，因为出于兼容性原因，默认支持的全局跨会话池是旧行为。 这会影响以后手动设置最大连接。

WINHTTP_OPTION_DISABLE_PROXY_AUTH_SCHEMES

通过提供 OR 所有适用选项来禁用 WinHTTP 会话上的以下一个或多个代理身份验证做法。 这些方案都是方案，除了 WINHTTP_PROXY_DISABLE_AUTH_LOCAL_SERVICE，在向环回或本地地址发送请求时强制使用本地计算机帐户。 这可以防止将系统凭据泄露到本地 HTTP 代理。

WINHTTP_OPTION_DISABLE_SECURE_PROTOCOL_FALLBACK

当初始协议协商失败时，阻止 WinHTTP 重试具有较低版本安全协议的连接。

WINHTTP_OPTION_DISABLE_STREAM_QUEUE

允许新请求在达到最大并发流限制时打开额外的 HTTP/2 连接，而不是等待现有连接上的下一个可用流。

WINHTTP_OPTION_ENABLE_FEATURE

设置一个无符号长整数值，该值指定当前启用的功能。 可以是以下值之一。

WINHTTP_OPTION_ENABLE_HTTP_PROTOCOL

设置可接受的高级 HTTP 版本的 DWORD 位掩码。 可能的值为：

无法使用此选项禁用旧版 HTTP（1.1 及更早版本）。 默认值为0x0。

WINHTTP_OPTION_ENABLE_HTTP2_PLUS_CLIENT_CERT

可以在 WinHttp 会话句柄上设置此选项，以允许 WinHttp 在使用 HTTP/2 时使用调用方提供的客户端证书上下文。

WINHTTP_OPTION_ENABLETRACING

设置一个 BOOL 值，该值指定是否当前启用跟踪。 此选项只能在 NULLHINTERNET 句柄上设置。 另请参阅 收集 WinHTTP 跟踪。

WINHTTP_OPTION_ENCODE_EXTRA

为路径和查询字符串启用 URL 百分比编码。

或者，可以在调用 WinHttp 之前进行百分比编码。

WINHTTP_OPTION_EXPIRE_CONNECTION

此选项只能在仍然处于活动状态（发送或接收）的请求句柄上设置。 设置此选项将告知 WinHttp 停止在与传入的请求句柄关联的连接上处理请求。 请求句柄完成后，将关闭连接。 此选项不采用任何参数。

WINHTTP_OPTION_EXTENDED_ERROR

检索一个无符号长整数值，该值包含一个Microsoft Windows 套接字错误代码，该错误代码映射到此线程上下文中最后返回的 ERROR_WINHTTP_* 错误消息。 可以将 NULL 作为句柄值传递。

WINHTTP_OPTION_FEATURE_SUPPORTED

检查此版本的 WinHTTP 是否支持提供的选项标志。

WINHTTP_OPTION_FIRST_AVAILABLE_CONNECTION

默认情况下，当 WinHttp 发送请求时，如果没有可用的连接来为请求提供服务，WinHttp 将尝试建立新的连接，并且请求将绑定到此新连接。 设置此选项时，会在第一个可用连接上提供此类请求，不一定是正在建立的连接。

WINHTTP_OPTION_GLOBAL_PROXY_CREDS

将指针指向 WINHTTP_CREDS_EX 结构， hInternet 函数参数设置为 NULL。 此选项需要注册表项 HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings！ShareCredsWithWinHttp。 如果未设置此注册表项，WinHTTP 将返回 错误ERROR_WINHTTP_INVALID_OPTION。 默认情况下，此注册表项不存在。 设置后，WinINet 会将凭据向下发送到 WinHTTP。 每当 WinHttp 收到身份验证质询并且当前句柄上没有设置凭据时，它将使用 WinINet 提供的凭据。 为了除了代理凭据之外共享服务器凭据，用户还需要设置 WINHTTP_OPTION_USE_GLOBAL_SERVER_CREDENTIALS 。

WINHTTP_OPTION_GLOBAL_SERVER_CREDS

将指针指向 WINHTTP_CREDS_EX 结构， hInternet 函数参数设置为 NULL。 此选项需要注册表项 HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings！ShareCredsWithWinHttp。 如果未设置此注册表项，WinHTTP 将返回 错误ERROR_WINHTTP_INVALID_OPTION。 默认情况下，此注册表项不存在。 设置后，WinINet 会将凭据向下发送到 WinHTTP。 每当 WinHttp 收到身份验证质询并且当前句柄上没有设置凭据时，它将使用 WinINet 提供的凭据。 为了除了代理凭据之外共享服务器凭据，用户还需要设置 WINHTTP_OPTION_USE_GLOBAL_SERVER_CREDENTIALS 。

WINHTTP_OPTION_HANDLE_TYPE

检索包含传入的 HINTERNET 句柄类型的无符号长整数值。 返回值可以是下列值之一：

WINHTTP_OPTION_HTTP_PROTOCOL_REQUIRED

防止 WINHTTP_OPTION_ENABLE_HTTP_PROTOCOL 用于请求的协议版本以外的协议版本。

WINHTTP_OPTION_HTTP_PROTOCOL_USED

获取一个 DWORD，指示给定请求使用了哪个高级 HTTP 版本。 有关可能值的列表，请参阅 WINHTTP_OPTION_ENABLE_HTTP_PROTOCOL。

WINHTTP_OPTION_HTTP_VERSION

设置或检索声明受支持的旧版 HTTP 版本的 HTTP_VERSION_INFO 结构。 这是一个进程范围的选项;为句柄使用 NULL 。

WINHTTP_OPTION_HTTP2_KEEPALIVE

可以在会话句柄上设置此选项，使 WinHttp 使用 HTTP/2 PING 帧作为保持机制。 调用方指定超时（以毫秒为单位），在该超时期限的连接上没有活动后，WinHttp 将开始发送 HTTP/2 PING 帧。 调用方无法设置小于 5000 毫秒的超时值。

WINHTTP_OPTION_HTTP2_PLUS_TRANSFER_ENCODING

可以在 WinHttp 请求句柄上设置此选项，以控制 HTTP/2 响应包含“Transfer-Encoding”标头时 WinHttp 的行为方式。 在这种情况下，如果此选项设置为 FALSE，WinHttp 将返回错误。

WINHTTP_OPTION_HTTP2_RECEIVE_WINDOW

使用 WINHTTP_HTTP2_RECEIVE_WINDOW 结构设置初始 HTTP/2 流接收窗口大小和发送窗口更新的阈值。

WINHTTP_OPTION_HTTP3_HANDSHAKE_TIMEOUT

使用缓冲区将 HTTP/3 握手超时设置为 PDWORD（以毫秒为单位）。

WINHTTP_OPTION_HTTP3_INITIAL_RTT

配置 msquic 使用的初始 RTT（以毫秒为单位）。

WINHTTP_OPTION_HTTP3_KEEPALIVE

为连接启用保持活动语义。 使用缓冲区将保持活动超时设置为 PDWORD，以毫秒为单位。

WINHTTP_OPTION_HTTP3_STREAM_ERROR_CODE

检索用于发送请求的 HTTP/3 流上的服务器提供的错误。

WINHTTP_OPTION_IGNORE_CERT_REVOCATION_OFFLINE

允许安全连接使用无法下载证书吊销列表的安全证书。

WINHTTP_OPTION_IPV6_FAST_FALLBACK

为连接启用 IPv6 快速回退（快乐眼球）。 此行为类似于 RFC 6555 中所述的快乐眼球行为，用于改善 IPv6 不可靠的网络上的连接时间。

• 如果给定主机同时解析 IPv6 和 IPv4 地址，WinHttp 将首先连接到具有短（300 毫秒）超时的第一个已解析 IPv6 地址。
• 如果连接失败，WinHttp 将尝试使用标准超时连接到第一个解析的 IPv4 地址。
• 如果第二个连接失败，WinHttp 将使用标准超时重试第一个解析的 IPv6 地址。
• 如果第三个连接失败，WinHttp 将还原为任何剩余地址的默认行为，尝试与每个地址建立连接，直到建立连接或未保留任何地址。

WINHTTP_OPTION_IS_PROXY_CONNECT_RESPONSE

获取是否可以检索代理返回连接响应。

WINHTTP_OPTION_MATCH_CONNECTION_GUID

采用 WINHTTP_MATCH_CONNECTION_GUID 结构，告知 WinHTTP 在匹配的连接上为请求提供服务。 如果设置了 WINHTTP_MATCH_CONNECTION_GUID_FLAG_REQUIRED ，则只能使用具有匹配 GUID 的连接。 否则，可以使用具有匹配 GUID 的连接和未使用任何 GUID 标记的连接。

WINHTTP_OPTION_MAX_CONNS_PER_1_0_SERVER

设置或检索一个无符号长整数值，该值包含每个 HTTP/1.0 服务器允许的最大连接数。 默认值为 INFINITE。

适用于：Windows Vista SP1 及更高版本;Windows Server 2008 及更高版本。

WINHTTP_OPTION_MAX_CONNS_PER_SERVER

设置或检索包含每个服务器允许的最大连接数的无符号长整数值。 默认值为 INFINITE。

如果此选项设置为零，WinHTTP 将连接数设置为 2 的限制。

WINHTTP_OPTION_MAX_HTTP_AUTOMATIC_REDIRECTS

设置 WinHTTP 遵循的最大重定向数;默认值为 10。 此限制可防止未经授权的站点在大量重定向后使 WinHTTP 客户端暂停。

适用于：具有 SP1 及更高版本的 Windows XP;Windows 2000 SP3 及更高版本。

WINHTTP_OPTION_MAX_HTTP_STATUS_CONTINUE

在将最终状态代码返回到 WinHTTP 客户端之前，忽略信息 100-199 状态代码响应的最大数目。 在最终状态代码之前，服务器可以发送信息 100-199 状态代码，并在 HTTP/1.1 规范中介绍（有关详细信息，请参阅 RFC 2616）。 默认值是10。

适用于：具有 SP1 及更高版本的 Windows XP;Windows 2000 SP3 及更高版本。

WINHTTP_OPTION_MAX_RESPONSE_DRAIN_SIZE

对从响应中排出的数据量进行绑定，以便重复使用以字节为单位指定的连接。 默认值为 1MB。

适用于：具有 SP1 及更高版本的 Windows XP;Windows 2000 SP3 及更高版本。

WINHTTP_OPTION_MAX_RESPONSE_HEADER_SIZE

服务器响应标头部分的最大大小（以字节为单位）上设置的绑定集。 此绑定通过发送具有无限数量的标头数据的响应来保护客户端免受未经授权的服务器尝试停止客户端。 默认值为 64KB。

适用于：具有 SP1 及更高版本的 Windows XP;Windows 2000 SP3 及更高版本。

WINHTTP_OPTION_PARENT_HANDLE

检索此句柄的父句柄。

WINHTTP_OPTION_PASSPORT_COBRANDING_TEXT

检索包含 Passport 登录服务器提供 的共同品牌 文本的字符串。 登录服务器响应 401 状态代码后，应立即检索此选项。 应用程序应传入足够大的缓冲区大小（以字节为单位）来保存返回的字符串。

WINHTTP_OPTION_PASSPORT_COBRANDING_URL

检索一个字符串，其中包含 Passport 登录服务器提供的 联合品牌 图形的 URL。 登录服务器响应 401 状态代码后，应立即检索此选项。 应用程序应传入足够大的缓冲区大小（以字节为单位）来保存返回的字符串。

WINHTTP_OPTION_PASSPORT_RETURN_URL

在检索 Passport 返回 URL 的请求句柄上设置只读选项。

WINHTTP_OPTION_PASSPORT_SIGN_OUT

设置会话句柄上用于注销任何 Passport 登录名的选项。 应用程序应传入使用 WINHTTP_OPTION_PASSPORT_RETURN_URL 检索的 Passport 返回 URL。 清除与返回 URL 相关的所有 Cookie。

WINHTTP_OPTION_PASSWORD

设置或检索包含与请求句柄关联的密码的字符串值。

WINHTTP_OPTION_PROXY

设置或检索包含现有会话句柄或请求句柄上的代理数据的 WINHTTP_PROXY_INFO 结构。 检索代理数据时，应用程序必须使用 GlobalFree 函数释放此结构中包含的 lpszProxyProxy 和 lpszProxyBypass 字符串（如果它们为非 NULL）。 应用程序可以通过传递 NULL 句柄来查询全局代理数据（默认代理）。

WINHTTP_OPTION_PROXY_PASSWORD

设置或检索包含用于访问代理的密码的字符串值。

WINHTTP_OPTION_PROXY_SPN_USED

获取在身份验证期间 WinHTTP 提供给 SSPI 的代理服务器主体名称。 此字符串值用于在身份验证失败后传递给 SspiPromptForCredentials 。

WINHTTP_OPTION_PROXY_USERNAME

设置或检索包含用于访问代理的用户名的字符串值。

WINHTTP_OPTION_QUIC_STATS

检索包含连接信息（如 RTT 和发送和接收的字节） 的QUIC_STATISTICS 结构。

WINHTTP_OPTION_READ_BUFFER_SIZE

此选项已弃用;它不起作用。

WINHTTP_OPTION_RECEIVE_PROXY_CONNECT_RESPONSE

设置是否可以检索代理响应实体。 默认情况下，此选项处于禁用状态。

WINHTTP_OPTION_RECEIVE_RESPONSE_TIMEOUT

设置或检索包含超时值（以毫秒为单位）的无符号长整数值，等待接收请求的所有响应标头。 如果 WinHTTP 在此超时期内未能接收所有标头，则会取消请求。 默认超时值为 90 秒。

仅当从套接字接收数据时，才会检查此超时。 因此，当超时过期时，在从服务器收到更多数据之前，不会通知客户端应用程序。 如果服务器未收到任何数据，则客户端应用程序超时过期和通知之间的延迟可能与使用 WinHttpSetTimeouts 函数的 dwReceiveTimeout 参数设置的超时值一样大。

WINHTTP_OPTION_RECEIVE_TIMEOUT

设置或检索包含超时值的无符号长整数值（以毫秒为单位），以接收对请求的部分响应或读取某些数据。 如果响应花费的时间超过此超时值，则会取消请求。 默认超时值为 30 秒。

WINHTTP_OPTION_REDIRECT_POLICY

设置 WinHTTP 关于处理 30x HTTP 重定向状态代码的行为。 可以在会话或请求句柄上将此选项设置为以下值之一：

WINHTTP_OPTION_REJECT_USERPWD_IN_URL

拒绝包含用户名和密码的 URL。 即使未指定用户名或密码，此选项也拒绝包含 用户名：密码 语义的 URL。 例如，“u：p@hostname”、“：@hostname”、“u：@hostname”和“:p@hostname”都将标记为无效。 如果传递给函数的 URL 无效，它将返回 ERROR_WINHTTP_INVALID_URL。 此选项默认处于关闭状态。

WINHTTP_OPTION_REQUEST_ANNOTATION

启用获取和设置提供的批注名称的请求批注。 这样，调用方就可以将字符串附加到请求，以便以后检索，以便通过调用方找到的任何自定义逻辑来标识请求。

WINHTTP_OPTION_REQUEST_PRIORITY

此选项已弃用;它不起作用。

WINHTTP_OPTION_REQUEST_STATS

检索请求的统计信息。 有关可用统计信息的列表，请参阅 WINHTTP_REQUEST_STATS。

WINHTTP_OPTION_REQUEST_TIMES

检索请求的计时信息。 有关可用计时的列表，请参阅 WINHTTP_REQUEST_TIMES。

WINHTTP_OPTION_REQUIRE_STREAM_END

此选项告知 WinHttp 忽略“Content-Length”响应标头，并继续在流上接收，直到收到END_STREAM标志。

WINHTTP_OPTION_RESOLUTION_HOSTNAME

可以在发送 WinHttp 请求句柄之前对此选项进行设置。 如果已设置，WinHttp 将使用调用方提供的字符串作为 DNS 解析的主机名。

WINHTTP_OPTION_RESOLVE_TIMEOUT

设置或检索包含超时值的无符号长整数值（以毫秒为单位）以解析主机名。 默认超时值为 INFINITE。 如果指定了非默认值，则每个名称解析都有一个线程创建开销。

WINHTTP_OPTION_REVERT_IMPERSONATION_SERVER_CERT

在生成服务器证书链时还原任何线程模拟，强制改用进程令牌。

WINHTTP_OPTION_SECURE_PROTOCOLS

设置一个无符号长整数值，该值指定哪些 Secure （HTTPS） 协议是可接受的。 此设置的默认值因作系统版本而异，可能会受到已安装更新的影响。

• Windows 11。 默认情况下，仅启用 TLS1.2 和 TLS1.3。
• Windows 10 和 Windows 8.1。 默认情况下，仅启用 SSL3、TLS1.0、TLS1.1 和 TLS1.2。
• Windows 8 和 Windows 7。 默认情况下，仅启用 SSL3 和 TLS1。

该值可以是以下一个或多个值的组合。

如果需要启用对较新的协议的支持，但无法重新编译应用程序以使用 适当的WINHTTP_OPTION_SECURE_PROTOCOLS值，则可以改为添加 DefaultSecureProtocols 注册表项。 该注册表项允许指定未设置 WINHTTP_OPTION_SECURE_PROTOCOLS 选项时应使用哪个安全协议。

如果应用程序未调用 WinHttpSetOption（WINHTTP_OPTION_SECURE_PROTOCOLS），系统将检查 DefaultSecureProtocols 注册表项，如果存在，则使用注册表项中指定的 DefaultSecureProtocols 协议替代现有作系统默认值。 WinHTTP 指定的协议可由可能禁用协议的安全通道（Schannel）配置设置推翻。

可以在以下路径中添加 DefaultSecureProtocols 注册表项：

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Internet Settings\WinHttp

在基于 x64 的计算机上，还必须添加到DefaultSecureProtocolsWow6432Node路径：

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\Microsoft\Windows\CurrentVersion\Internet Settings\WinHttp

注册表值为 DWORD 位图。 要使用的值是通过添加与所需协议相对应的值来确定的。

例如，如果要重写 WINHTTP_OPTION_SECURE_PROTOCOLS 的默认值，以指定 TLS 1.1 和 TLS 1.2。 在这种情况下，采用 TLS 1.1（0x00000200）的值和 TLS 1.2（0x00000800）的值，将它们加在计算器（在程序员模式下），生成的注册表值将0x00000A00。

WINHTTP_OPTION_SECURITY_CERTIFICATE_STRUCT

将 SSL/TLS 服务器的证书检索到 WINHTTP_CERTIFICATE_INFO 结构中。 应用程序必须使用 LocalFree 释放 lpszSubjectInfo 和 lpszIssuerInfo 成员。

WINHTTP_OPTION_SECURITY_FLAGS

设置或检索包含句柄安全标志的无符号长整数值。 它可以是以下值的组合：

WINHTTP_OPTION_SECURITY_INFO

检索请求的 SChannel 连接和密码信息。

WINHTTP_OPTION_SECURITY_KEY_BITNESS

检索包含加密密钥密码强度的无符号长整数值。 较大的数字表示更强的密码强度加密。

WINHTTP_OPTION_SEND_TIMEOUT

设置或检索包含超时值（以毫秒为单位）的无符号长整数值，以发送请求或写入某些数据。 如果发送请求的时间超过超时时间，则会取消发送作。 默认超时值为 30 秒。

WINHTTP_OPTION_SERVER_CBT

获取指向指定通道绑定令牌（CBT ）的SecPkgContext_Bindings 结构的指针。

通道绑定令牌是安全传输通道的属性，用于将身份验证通道绑定到安全传输通道。 只有在建立 SSL 连接后，此选项才能获取此令牌。

WINHTTP_OPTION_SERVER_CERT_CHAIN_CONTEXT

检索服务器认证链上下文。 可以传递WINHTTP_OPTION_SERVER_CERT_CHAIN_CONTEXT以获取指向协商 SSL 连接期间收到的服务器证书链CERT_CHAIN_CONTEXT的重复指针。 客户端必须在填充到缓冲区中的返回PCCERT_CONTEXT指针上调用 CertFreeCertificateContext 。

WINHTTP_OPTION_SERVER_CERT_CONTEXT

检索服务器认证上下文。 WINHTTP_OPTION_SERVER_CERT_CONTEXT可以 传递给获取在协商 SSL 连接期间收到的服务器证书 的证书上下文 的重复指针。 客户端必须在填充到缓冲区中的返回PCCERT_CONTEXT指针上调用 CertFreeCertificateContext 。

WINHTTP_OPTION_SERVER_SPN_USED

获取在身份验证期间 WinHTTP 提供给 SSPI 的服务器服务器主体名称。 身份验证失败后，此字符串值可以传递给 SspiPromptForCredentials 。

WINHTTP_OPTION_SPN

在为 Kerberos 或协商 Kerberos 身份验证生成 SPN（服务主体名称）时，包括或删除服务器端口号。 此标志是以下值之一：

WINHTTP_OPTION_STREAM_ERROR_CODE

可以在 WinHttp 请求句柄上查询此选项，并返回 HTTP 流上收到的RST_STREAM帧指示的错误代码。

WINHTTP_OPTION_TCP_FAST_OPEN

为连接启用 TCP 快速打开。

WINHTTP_OPTION_TCP_KEEPALIVE

可以在 WinHttp 会话句柄上设置此选项，以便在基础套接字上启用 TCP 保持活动行为。 采用 tcp_keepalive 结构。

WINHTTP_OPTION_TLS_FALSE_START

为连接启用 TLS False Start。

WINHTTP_OPTION_TCP_PRIORITY_STATUS

使用 WINHTTP_OPTION_TCP_PRIORITY_HINT 查询 TCP 套接字集的提示优先级。 有关更多详细信息，请参阅 SIO_SET_PRIORITY_HINT 的文档。

WINHTTP_OPTION_TLS_PROTOCOL_INSECURE_FALLBACK

可以在 WinHttp 会话句柄上设置此选项，以控制是否允许回退到 TLS 1.0（如果 TLS 握手失败且协议版本较新）。

WINHTTP_OPTION_UNLOAD_NOTIFY_EVENT

获取一个事件，该事件将在上次回调完成特定会话时设置。 必须在会话句柄上使用此标志。 在 WinHTTP 设置事件之后，该事件才能关闭。

WINHTTP_OPTION_UNSAFE_HEADER_PARSING

此选项保留供内部使用，不应调用。

WINHTTP_OPTION_UPGRADE_TO_WEB_SOCKET

指示堆栈使用 WinHttpSendRequest 启动 WebSocket 握手过程。 此选项不采用任何参数。

WINHTTP_OPTION_URL

检索包含已下载资源的完整 URL 的字符串值。 如果原始 URL 包含任何额外的数据，例如搜索字符串或定位点，或者调用已重定向，则返回的 URL 与原始 URL 不同。 应用程序应传入一个缓冲区（以字节为单位），大小足以将返回的 URL 保存在宽字符中。

WINHTTP_OPTION_USE_GLOBAL_SERVER_CREDENTIALS

采用 BOOL ，只能设置会话句柄。 只有在设置选项后，它才会传播到从会话句柄创建的句柄。 如果 为 TRUE，则此选项会导致使用从 WinInet 向下推送的全局服务器凭据。 此选项的默认值为 FALSE。 此选项需要注册表项 HKLM\Software\Microsoft\Windows\CurrentVersion\Internet Settings！ShareCredsWithWinHttp。 默认情况下，此注册表项不存在。 设置后，WinINet 会将凭据向下发送到 WinHTTP。 每当 WinHttp 收到身份验证质询并且当前句柄上没有设置凭据时，它将使用 WinINet 提供的凭据。

WINHTTP_OPTION_USE_SESSION_SCH_CRED

允许将单个凭据设置为默认用于会话中的所有终结点，而不是使用每终结点的默认凭据。 这可以通过减少凭据管理开销来提高性能。 请注意，显式提供客户端证书时，此默认凭据将不起作用。

WINHTTP_OPTION_USER_AGENT

在 WinHttpOpen 提供的句柄上设置或检索用户代理字符串，并在后续 WinHttpSendRequest 函数中使用，前提是它不会被 WinHttpAddRequestHeaders 或 WinHttpSendRequest 添加的标头重写。 检索用户代理时，应用程序应传入缓冲区（大小为字节），足以将返回的 URL 保存在宽字符中。 设置用户代理时，缓冲区大小为字符串长度（以字符为单位）加上 NULL 终止符。

WINHTTP_OPTION_USERNAME

设置或检索包含用户名的字符串。

WINHTTP_OPTION_WEB_SOCKET_CLOSE_TIMEOUT

设置 WinHttpWebSocketClose 应等待完成关闭握手的时间（以毫秒为单位）。 默认值为 10 秒。

WINHTTP_OPTION_WEB_SOCKET_KEEPALIVE_INTERVAL

设置间隔（以毫秒为单位），以通过连接发送保持活动数据包。 默认间隔为 30000 （30 秒）。 最小间隔为 15000 （15 秒）。 使用 WinHttpSetOption 设置小于 15000 的值将返回 ERROR_INVALID_PARAMETER。

WINHTTP_OPTION_WEB_SOCKET_RECEIVE_BUFFER_SIZE

设置或检索一个 DWORD，该 DWORD 指定要在 WebSocket 连接中使用的接收缓冲区大小。

WINHTTP_OPTION_WEB_SOCKET_SEND_BUFFER_SIZE

设置或检索 DWORD，该 DWORD 指定要在 WebSocket 连接上使用的发送缓冲区大小。

WINHTTP_OPTION_WORKER_THREAD_COUNT

设置一个无符号长整数值，该值指定线程池应用于异步完成的工作线程数。 此选项的默认值为零，它指定工作线程数等于系统上的 CPU 数。 只有在异步作发生之前，才能在 NULLHINTERNET 句柄上设置此选项。 此选项只能设置一次。

适用于：Windows 7 及更高版本;Windows Server 2008 R2 及更高版本。

WINHTTP_OPTION_WRITE_BUFFER_SIZE

此选项已弃用;它不起作用。

注解

下表列出了选项标志，方法是指定可对其执行作的句柄、是否可以查询和设置它们以及所使用的数据类型。 “X”表示选项标志可用于函数或句柄，而“-”则指定选项标志无效。

尝试在不支持选项的 Windows 版本上设置或查询选项标志将导致 ERROR_WINHTTP_INVALID_OPTION。

要求

另请参阅

• WinHTTP 版本