求HttpSendHttpResponse使用HTTP_SEND_RESPONSE_FLAG_OPAQUE标志的示例（WebSocket支持）

我完全理解你的困扰——用HTTP_SEND_RESPONSE_FLAG_OPAQUE配合WebSocket握手时触发ERROR_INVALID_PARAMETER，而且清楚不用这个标志的话，HTTP.SYS会继续解析后续流量，导致WebSocket帧无法正常传输。下面是正确的使用示例和关键注意事项，帮你搞定这个问题：

常见错误原因 #

触发ERROR_INVALID_PARAMETER通常是因为以下几点：

• 传递的HTTP_RESPONSE结构初始化不全，尤其是响应头部分
• 给pEntityChunk参数传了非NULL值（101响应本身无实体内容，且OPAQUE标志要求后续流量独立于HTTP响应）
• WebSocketBeginServerHandshake生成的握手头无效
• 状态码未设置为101（Switching Protocols）

正确的代码示例 #

以下是C++环境下的完整示例片段，涵盖握手准备、响应初始化和HttpSendHttpResponse的正确调用：

// 假设已完成前置初始化：请求队列句柄hReqQueue、当前请求ID requestId
// 且已成功调用WebSocketBeginServerHandshake生成握手信息handshakeInfo
HANDLE hReqQueue = ...;
HTTP_REQUEST_ID requestId = ...;
PWEB_SOCKET_HANDSHAKE_INFORMATION handshakeInfo = ...;

// 初始化HTTP_RESPONSE结构，必须清零避免未定义行为
HTTP_RESPONSE response = {0};
response.StatusCode = 101;
response.pReason = "Switching Protocols";
response.ReasonLength = static_cast<USHORT>(strlen(response.pReason));

// 复制WebSocket握手生成的响应头到HTTP_RESPONSE
response.Headers = handshakeInfo->HttpResponseHeaders;

// 调用HttpSendHttpResponse，使用OPAQUE标志
DWORD bytesSent = 0;
DWORD win32Error = HttpSendHttpResponse(
    hReqQueue,
    requestId,
    HTTP_SEND_RESPONSE_FLAG_OPAQUE,
    &response,
    NULL,          // pEntityChunk必须为NULL，101响应无实体
    &bytesSent,
    NULL,
    0,
    NULL,
    NULL
);

if (win32Error != NO_ERROR) {
    printf("HttpSendHttpResponse failed: %lu\n", win32Error);
    // 可进一步检查握手信息是否有效，或结构初始化是否正确
} else {
    // 成功！此时HTTP.SYS会将后续流量直接转发，不再解析HTTP帧
    // 后续可通过WebSocketReceive/WebSocketSend收发WebSocket数据
}

关键注意事项 #

• OPAQUE标志的作用：告诉HTTP.SYS，此响应完成后，连接上的所有后续数据都不属于HTTP协议，需直接透传，这样WebSocket的二进制/文本帧就能正常传输。
• 握手头有效性：确保WebSocketBeginServerHandshake已成功执行，生成的HttpResponseHeaders包含正确的Sec-WebSocket-Accept等握手字段。如果这个步骤失败，后续的响应头会无效，导致参数错误。
• 禁止实体内容：101 Switching Protocols响应本身没有实体内容，所以pEntityChunk必须设为NULL，否则会触发参数错误。
• 状态码必须为101：这是WebSocket协议要求的握手响应状态码，与OPAQUE标志搭配才能让HTTP.SYS正确切换到透明传输模式。

内容的提问来源于stack exchange，提问作者AndyX