mirror of
https://github.com/cesanta/mongoose.git
synced 2026-11-19 19:40:56 +00:00
Better docstrings
This commit is contained in:
1 parent
9802a165df
commit
3706742614
10 files changed
+612
-152
No files matched your search
@@ -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
|
||||
|
||||
Reference in new issue
Block a user