API WebSocket

WebSocket API

命名空间：wknet::websocket
头文件：wknet/websocket/WebSocket.h · 配置类型在 wknet/http/Types.h（namespace wknet::websocket）

Connect / 收发 / 关闭。依赖已有 http::Session。

ConnectConfig

ConnectConfig DefaultConnectConfig() noexcept;

struct ConnectConfig final {
    const char* Url = nullptr;
    SIZE_T UrlLength = 0;
    const char* Subprotocol = nullptr;
    SIZE_T SubprotocolLength = 0;
    const Header* Headers = nullptr;
    SIZE_T HeaderCount = 0;
    wknet::http::TlsConfig Tls = {};
    wknet::http::AddressFamily Family = wknet::http::AddressFamily::Any;
    SIZE_T MaxMessageBytes = wknet::http::DefaultMaxWebSocketMessageBytes; // 1 MiB
    bool AutoReplyPing = true;
    bool AllowWebSocketOverHttp2 = false;
    wknet::http::WebSocketTransportMode TransportMode =
        wknet::http::WebSocketTransportMode::Auto;
    PerMessageDeflateOptions PerMessageDeflate = {};
    HandshakeChallengeCallback ChallengeCallback = nullptr;
    void* ChallengeContext = nullptr;
    ULONG MaxHandshakeRetries = 0;
};

字段	说明
`Url` / `UrlLength`	`ws://` 或 `wss://`
`Subprotocol`	可选子协议
`Headers` / `HeaderCount`	调用方握手头（`Origin` 等）；库控制头（`Upgrade`/`Connection`/`Host`/`Sec-WebSocket-*`）拒收
`Tls`	`wss` TLS
`Family`	地址族
`MaxMessageBytes`	单消息上限
`AutoReplyPing`	自动 Pong
`AllowWebSocketOverHttp2`	允许 RFC 8441 路径（能力边界见能力矩阵）
`TransportMode`	`Auto` / `Http11Only` / `Http2Required` / `LegacyBoolean`
`PerMessageDeflate`	permessage-deflate 选项
`ChallengeCallback` / `Context`	3xx/认证挑战重试
`MaxHandshakeRetries`	握手重试上限

辅助类型

struct Header final {
    const char* Name = nullptr; SIZE_T NameLength = 0;
    const char* Value = nullptr; SIZE_T ValueLength = 0;
};

struct PerMessageDeflateOptions final {
    bool Enable = false;
    bool ClientNoContextTakeover = false;
    bool ServerNoContextTakeover = false;
    UCHAR ClientMaxWindowBits = 15;
    UCHAR ServerMaxWindowBits = 15;
};

struct HandshakeChallenge final {
    USHORT StatusCode = 0;
    const ResponseHeader* Headers = nullptr;
    SIZE_T HeaderCount = 0;
    bool Redirect = false;
    bool AuthenticationChallenge = false;
};

struct HandshakeRetryAction final {
    const char* RedirectPath = nullptr;
    SIZE_T RedirectPathLength = 0;
    const Header* Headers = nullptr;
    SIZE_T HeaderCount = 0;
};

typedef NTSTATUS (*HandshakeChallengeCallback)(
    void* context,
    const HandshakeChallenge* challenge,
    HandshakeRetryAction* action);

Connect

签名

NTSTATUS Connect(
    _In_ wknet::http::Session* session,
    _In_reads_bytes_(urlLength) const char* url,
    SIZE_T urlLength,
    _Out_ WebSocket** websocket) noexcept;

NTSTATUS Connect(
    _In_ wknet::http::Session* session,
    _In_ const ConnectConfig* config,
    _Out_ WebSocket** websocket) noexcept;

NTSTATUS ConnectEx(
    _In_ wknet::http::Session* session,
    _In_ const ConnectConfig* config,
    _Out_ WebSocket** websocket) noexcept;

NTSTATUS ConnectAsync(
    _In_ wknet::http::Session* session,
    _In_reads_bytes_(urlLength) const char* url,
    SIZE_T urlLength,
    _Out_ wknet::http::AsyncOp** operation) noexcept;

NTSTATUS ConnectAsync(
    _In_ wknet::http::Session* session,
    _In_ const ConnectConfig* config,
    _Out_ wknet::http::AsyncOp** operation) noexcept;

NTSTATUS ConnectAsyncEx(
    _In_ wknet::http::Session* session,
    _In_ const ConnectConfig* config,
    _Out_ wknet::http::AsyncOp** operation) noexcept;

NTSTATUS AsyncGetWebSocket(
    _In_ wknet::http::AsyncOp* operation,
    _Out_ WebSocket** websocket) noexcept;

返回

STATUS_SUCCESS 或参数/握手/网络失败状态。异步路径完成后 AsyncGetWebSocket 取句柄。

Send

NTSTATUS SendText(_In_ WebSocket* websocket,
    _In_reads_bytes_(textLength) const char* text, SIZE_T textLength) noexcept;
NTSTATUS SendTextEx(..., _In_opt_ const SendOptions* options) noexcept;

NTSTATUS SendBinary(_In_ WebSocket* websocket,
    _In_reads_bytes_(dataLength) const UCHAR* data, SIZE_T dataLength) noexcept;
NTSTATUS SendBinaryEx(..., _In_opt_ const SendOptions* options) noexcept;

NTSTATUS SendContinuation(_In_ WebSocket* websocket,
    _In_reads_bytes_(dataLength) const UCHAR* data, SIZE_T dataLength) noexcept;
NTSTATUS SendContinuationEx(..., _In_opt_ const SendOptions* options) noexcept;

NTSTATUS SendPing(_In_ WebSocket* websocket,
    _In_reads_bytes_opt_(payloadLength) const UCHAR* payload, SIZE_T payloadLength) noexcept;
NTSTATUS SendPong(_In_ WebSocket* websocket,
    _In_reads_bytes_opt_(payloadLength) const UCHAR* payload, SIZE_T payloadLength) noexcept;

struct SendOptions final {
    bool FinalFragment = true;
};

分片：首帧 SendText/SendBinary 且 FinalFragment=false，后续 SendContinuation，最后一帧 FinalFragment=true。

Receive

struct ReceiveOptions final {
    SIZE_T MaxMessageBytes = 0;
    bool AutoAllocate = true;
    MessageCallback OnMessage = nullptr;
    void* CallbackContext = nullptr;
    bool DeliverFragments = false;
};

struct Message final {
    MsgType Type = MsgType::Binary;
    const UCHAR* Data = nullptr;
    SIZE_T DataLength = 0;
    bool Final = true;
    bool FinalFragment = true;
};

enum class MsgType : ULONG {
    Text = 0, Binary = 1, Close = 2,
    Continuation = 3, Ping = 4, Pong = 5
};

typedef NTSTATUS (*MessageCallback)(
    void* context, MsgType type,
    const UCHAR* data, SIZE_T dataLength, bool finalFragment);

NTSTATUS Receive(_In_ WebSocket* websocket, _Out_ Message* message) noexcept;
NTSTATUS ReceiveEx(
    _In_ WebSocket* websocket,
    _In_opt_ const ReceiveOptions* options,
    _Out_opt_ Message* message) noexcept;

字段	说明
`MaxMessageBytes`	`0` 时用连接配置上限
`AutoAllocate`	库分配消息缓冲
`OnMessage`	可选流式回调
`DeliverFragments`	按分片交付

Close / 查询

NTSTATUS Close(_In_opt_ WebSocket* websocket) noexcept;
NTSTATUS CloseEx(
    _In_opt_ WebSocket* websocket,
    USHORT statusCode,
    _In_reads_bytes_opt_(reasonLength) const UCHAR* reason,
    SIZE_T reasonLength) noexcept;

NTSTATUS SelectedSubprotocol(
    _In_ WebSocket* websocket,
    _Outptr_result_bytebuffer_(*subprotocolLength) const char** subprotocol,
    _Out_ SIZE_T* subprotocolLength) noexcept;

Close / CloseEx 释放句柄；接受 nullptr。

备注

全部入口 PASSIVE_LEVEL。
依赖有效 http::Session；关闭顺序：先 WebSocket，再 session（或确保无并发使用）。
异步连接完成后用 AsyncGetWebSocket，再 AsyncRelease。

English

WebSocket API

Namespace: wknet::websocket
Headers: wknet/websocket/WebSocket.h · config types in wknet/http/Types.h (namespace wknet::websocket)

Connect / send / receive / close on an existing http::Session.

ConnectConfig

ConnectConfig DefaultConnectConfig() noexcept;

struct ConnectConfig final {
    const char* Url = nullptr;
    SIZE_T UrlLength = 0;
    const char* Subprotocol = nullptr;
    SIZE_T SubprotocolLength = 0;
    const Header* Headers = nullptr;
    SIZE_T HeaderCount = 0;
    wknet::http::TlsConfig Tls = {};
    wknet::http::AddressFamily Family = wknet::http::AddressFamily::Any;
    SIZE_T MaxMessageBytes = wknet::http::DefaultMaxWebSocketMessageBytes; // 1 MiB
    bool AutoReplyPing = true;
    bool AllowWebSocketOverHttp2 = false;
    wknet::http::WebSocketTransportMode TransportMode =
        wknet::http::WebSocketTransportMode::Auto;
    PerMessageDeflateOptions PerMessageDeflate = {};
    HandshakeChallengeCallback ChallengeCallback = nullptr;
    void* ChallengeContext = nullptr;
    ULONG MaxHandshakeRetries = 0;
};

Field	Notes
`Url` / `UrlLength`	`ws://` or `wss://`
`Subprotocol`	Optional subprotocol
`Headers` / `HeaderCount`	Caller handshake headers; library-controlled headers (`Upgrade`/`Connection`/`Host`/`Sec-WebSocket-*`) are rejected
`Tls`	TLS for `wss`
`Family`	Address family
`MaxMessageBytes`	Per-message cap
`AutoReplyPing`	Auto pong
`AllowWebSocketOverHttp2`	RFC 8441 path (see capability matrix)
`TransportMode`	`Auto` / `Http11Only` / `Http2Required` / `LegacyBoolean`
`PerMessageDeflate`	permessage-deflate options
`ChallengeCallback` / `Context`	3xx / auth challenge retry
`MaxHandshakeRetries`	Handshake retry cap

Helper types

struct Header final {
    const char* Name = nullptr; SIZE_T NameLength = 0;
    const char* Value = nullptr; SIZE_T ValueLength = 0;
};

struct PerMessageDeflateOptions final {
    bool Enable = false;
    bool ClientNoContextTakeover = false;
    bool ServerNoContextTakeover = false;
    UCHAR ClientMaxWindowBits = 15;
    UCHAR ServerMaxWindowBits = 15;
};

struct HandshakeChallenge final {
    USHORT StatusCode = 0;
    const ResponseHeader* Headers = nullptr;
    SIZE_T HeaderCount = 0;
    bool Redirect = false;
    bool AuthenticationChallenge = false;
};

struct HandshakeRetryAction final {
    const char* RedirectPath = nullptr;
    SIZE_T RedirectPathLength = 0;
    const Header* Headers = nullptr;
    SIZE_T HeaderCount = 0;
};

typedef NTSTATUS (*HandshakeChallengeCallback)(
    void* context,
    const HandshakeChallenge* challenge,
    HandshakeRetryAction* action);

Connect

Signatures

NTSTATUS Connect(
    _In_ wknet::http::Session* session,
    _In_reads_bytes_(urlLength) const char* url,
    SIZE_T urlLength,
    _Out_ WebSocket** websocket) noexcept;

NTSTATUS Connect(
    _In_ wknet::http::Session* session,
    _In_ const ConnectConfig* config,
    _Out_ WebSocket** websocket) noexcept;

NTSTATUS ConnectEx(
    _In_ wknet::http::Session* session,
    _In_ const ConnectConfig* config,
    _Out_ WebSocket** websocket) noexcept;

NTSTATUS ConnectAsync(
    _In_ wknet::http::Session* session,
    _In_reads_bytes_(urlLength) const char* url,
    SIZE_T urlLength,
    _Out_ wknet::http::AsyncOp** operation) noexcept;

NTSTATUS ConnectAsync(
    _In_ wknet::http::Session* session,
    _In_ const ConnectConfig* config,
    _Out_ wknet::http::AsyncOp** operation) noexcept;

NTSTATUS ConnectAsyncEx(
    _In_ wknet::http::Session* session,
    _In_ const ConnectConfig* config,
    _Out_ wknet::http::AsyncOp** operation) noexcept;

NTSTATUS AsyncGetWebSocket(
    _In_ wknet::http::AsyncOp* operation,
    _Out_ WebSocket** websocket) noexcept;

Returns

STATUS_SUCCESS or parameter/handshake/network failure. After async completion, take the handle with AsyncGetWebSocket.

Send

NTSTATUS SendText(_In_ WebSocket* websocket,
    _In_reads_bytes_(textLength) const char* text, SIZE_T textLength) noexcept;
NTSTATUS SendTextEx(..., _In_opt_ const SendOptions* options) noexcept;

NTSTATUS SendBinary(_In_ WebSocket* websocket,
    _In_reads_bytes_(dataLength) const UCHAR* data, SIZE_T dataLength) noexcept;
NTSTATUS SendBinaryEx(..., _In_opt_ const SendOptions* options) noexcept;

NTSTATUS SendContinuation(_In_ WebSocket* websocket,
    _In_reads_bytes_(dataLength) const UCHAR* data, SIZE_T dataLength) noexcept;
NTSTATUS SendContinuationEx(..., _In_opt_ const SendOptions* options) noexcept;

NTSTATUS SendPing(_In_ WebSocket* websocket,
    _In_reads_bytes_opt_(payloadLength) const UCHAR* payload, SIZE_T payloadLength) noexcept;
NTSTATUS SendPong(_In_ WebSocket* websocket,
    _In_reads_bytes_opt_(payloadLength) const UCHAR* payload, SIZE_T payloadLength) noexcept;

struct SendOptions final {
    bool FinalFragment = true;
};

Fragmentation: first SendText/SendBinary with FinalFragment=false, then SendContinuation, last frame FinalFragment=true.

Receive

struct ReceiveOptions final {
    SIZE_T MaxMessageBytes = 0;
    bool AutoAllocate = true;
    MessageCallback OnMessage = nullptr;
    void* CallbackContext = nullptr;
    bool DeliverFragments = false;
};

struct Message final {
    MsgType Type = MsgType::Binary;
    const UCHAR* Data = nullptr;
    SIZE_T DataLength = 0;
    bool Final = true;
    bool FinalFragment = true;
};

enum class MsgType : ULONG {
    Text = 0, Binary = 1, Close = 2,
    Continuation = 3, Ping = 4, Pong = 5
};

typedef NTSTATUS (*MessageCallback)(
    void* context, MsgType type,
    const UCHAR* data, SIZE_T dataLength, bool finalFragment);

NTSTATUS Receive(_In_ WebSocket* websocket, _Out_ Message* message) noexcept;
NTSTATUS ReceiveEx(
    _In_ WebSocket* websocket,
    _In_opt_ const ReceiveOptions* options,
    _Out_opt_ Message* message) noexcept;

Field	Notes
`MaxMessageBytes`	`0` uses connection config cap
`AutoAllocate`	Library allocates message buffer
`OnMessage`	Optional streaming callback
`DeliverFragments`	Deliver per fragment

Close / query

NTSTATUS Close(_In_opt_ WebSocket* websocket) noexcept;
NTSTATUS CloseEx(
    _In_opt_ WebSocket* websocket,
    USHORT statusCode,
    _In_reads_bytes_opt_(reasonLength) const UCHAR* reason,
    SIZE_T reasonLength) noexcept;

NTSTATUS SelectedSubprotocol(
    _In_ WebSocket* websocket,
    _Outptr_result_bytebuffer_(*subprotocolLength) const char** subprotocol,
    _Out_ SIZE_T* subprotocolLength) noexcept;

Close / CloseEx free the handle; nullptr is accepted.

Notes

All entry points at PASSIVE_LEVEL.
Requires a live http::Session; close WebSocket before or without concurrent session teardown.
After async connect, AsyncGetWebSocket then AsyncRelease.

API WebSocket

WebSocket API

ConnectConfig

辅助类型

Connect

签名

返回

Send

Receive

Close / 查询

备注

相关链接

English

WebSocket API

ConnectConfig

Helper types

Connect

Signatures

Returns

Send

Receive

Close / query

Notes

See also

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

wknet Wiki

Clone this wiki locally