Better docstrings

This commit is contained in:
cpq committed 2026-06-20 13:48:09 +01:00
1 parent 9802a165df
commit 3706742614
10 files changed
+612 -152

No files matched your search

+48 -17
View File
@@ -19,30 +19,61 @@ struct mg_ws_message {
uint8_t flags; // First byte of the WS frame header: FIN (bit7) | opcode (bits3:0)
};
// Opens an outbound WebSocket connection to url (e.g. "ws://host/path" or
// "wss://host/path" for TLS). Sends the HTTP Upgrade request immediately.
// fmt is a printf-style format string for extra HTTP request headers
// (each header must end with \r\n); pass NULL for no extra headers.
// Fires MG_EV_WS_OPEN when the handshake completes (ev_data: struct mg_http_message *).
// Fires MG_EV_WS_MSG for each complete incoming message (ev_data: struct mg_ws_message *).
// Fires MG_EV_WS_CTL for control frames: PING (auto-replied), PONG, CLOSE.
// Returns NULL on error.
// Opens an outbound WebSocket connection.
//
// Returns:
// Client connection, or NULL on error.
// Example:
// mg_ws_connect(&mgr, "ws://localhost:8000/websocket", fn, NULL, NULL);
// Full examples:
// tutorials/websocket/websocket-client, tutorials/mqtt/mqtt-over-ws-client
// Related APIs:
// mg_ws_send(), mg_ws_printf(), mg_tls_init(), mg_ws_upgrade()
// Notes:
// url may use ws:// or wss://. Sends the HTTP Upgrade request immediately.
// fmt is a printf-style string for extra HTTP request headers; each header
// must end with "\r\n". The user-supplied fn event handler receives
// MG_EV_WS_OPEN on handshake success, MG_EV_WS_MSG for messages, and
// MG_EV_WS_CTL for control frames.
struct mg_connection *mg_ws_connect(struct mg_mgr *, const char *url,
mg_event_handler_t fn, void *fn_data,
const char *fmt, ...);
// Server-side: upgrades an existing HTTP connection to WebSocket.
// Call from an MG_EV_HTTP_MSG handler, passing the received hm.
// fmt is a printf-style format string for extra response headers
// (each header must end with \r\n); pass NULL for none.
// Fires MG_EV_WS_OPEN immediately on success (ev_data: struct mg_http_message *).
// Sends HTTP 426 and drains the connection if the request lacks Sec-WebSocket-Key.
// Upgrades a server-side HTTP connection to WebSocket.
//
// Example:
// if (mg_match(hm->uri, mg_str("/websocket"), NULL)) {
// mg_ws_upgrade(c, hm, NULL);
// }
// Full examples:
// tutorials/websocket/websocket-server,
// tutorials/websocket/json-rpc-over-websocket, tutorials/core/timers
// Related APIs:
// mg_http_listen(), mg_match(), mg_ws_send(), mg_ws_printf()
// Notes:
// Call from an MG_EV_HTTP_MSG handler and pass that event's hm. fmt is a
// printf-style string for extra response headers; each header must end with
// "\r\n". Fires MG_EV_WS_OPEN immediately on success. Sends HTTP 426 and
// drains the connection if the request lacks Sec-WebSocket-Key.
void mg_ws_upgrade(struct mg_connection *, struct mg_http_message *,
const char *fmt, ...);
// Sends a WebSocket frame containing buf/len with opcode op (WEBSOCKET_OP_*).
// Client connections are automatically masked per RFC 6455.
// Returns total bytes appended to c->send (header + payload), or 0 on OOM.
// Sends one WebSocket frame.
//
// Returns:
// Number of bytes appended to c->send; 0 if the frame header cannot be
// appended.
// Example:
// mg_ws_send(c, "hello", 5, WEBSOCKET_OP_TEXT);
// Full examples:
// tutorials/websocket/websocket-server, tutorials/websocket/websocket-client,
// tutorials/core/timers
// Related APIs:
// mg_ws_connect(), mg_ws_upgrade(), mg_ws_printf(), mg_ws_wrap()
// Notes:
// op is one of WEBSOCKET_OP_*. Client connections are automatically masked
// per RFC 6455. On OOM, the return value can be smaller than header + len.
// Data is appended to c->send and sent by a later mg_mgr_poll() call.
size_t mg_ws_send(struct mg_connection *, const void *buf, size_t len, int op);
// Wraps the last len bytes already in c->send with a WebSocket frame header