mirror/mongoose
1
0
Fork 0
mirror of https://github.com/cesanta/mongoose.git synced 2024-12-03 00:59:02 +08:00
Code Issues Actions 6 Packages Projects Releases Wiki Activity

Merge pull request #1821 from cesanta/docs

Browse Source 
Augment WS documentation
This commit is contained in:
Sergey Lyubka 2022-10-27 23:09:47 +01:00 committed by GitHub
commit 9a1e41e1fa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 44 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
docs/README.md
View File

@ -1404,18 +1404,50 @@ static void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
```
## Websocket
## WebSocket
### struct mg\_ws\_message
```c
struct mg_ws_message {
struct mg_str data; // Websocket message data
uint8_t flags; // Websocket message flags
struct mg_str data; // WebSocket message data
uint8_t flags; // WebSocket message flags
};
```
Structure represents the WebSocket message.
This structure represents the WebSocket message, the `flags` element corresponds to the first byte as described in [RFC 6455 section 5.2](https://www.rfc-editor.org/rfc/rfc6455#section-5.2).
#### WebSocket message type:
To extract the message type from an incoming message, check the four LSBs in the `flags` element of the `struct mg_ws_message`.
Possible WebSocket message types:
```c
#define WEBSOCKET_OP_CONTINUE 0
#define WEBSOCKET_OP_TEXT 1
#define WEBSOCKET_OP_BINARY 2
#define WEBSOCKET_OP_CLOSE 8
#define WEBSOCKET_OP_PING 9
#define WEBSOCKET_OP_PONG 10
```
```c
// Mongoose events handler
void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
if (ev == MG_EV_WS_MSG) {
struct mg_ws_message *wm = (struct mg_ws_message *) ev_data;
msgtype = wm->flags & 0x0F;
if (msgtype == WEBSOCKET_OP_BINARY) {
// This is a binary data message
} else if (msgtype == WEBSOCKET_OP_TEXT) {
// This is a text data message
}
}
}
```
To send a message, use the proper message type as described in [RFC 6455 section 5.6](https://www.rfc-editor.org/rfc/rfc6455#section-5.6) for data frames. when calling [mg_ws_send()](#mg_ws_send) or [mg_ws_printf()](#mg_ws_printf-mg_ws_vprintf) below
### mg\_ws\_connect()
@ -1425,7 +1457,7 @@ struct mg_connection *mg_ws_connect(struct mg_mgr *mgr, const char *url,
const char *fmt, ...);
```
Create client Websocket connection.
Create client WebSocket connection.
Note: this function does not connect to peer, it allocates required resources and
starts the connect process. Once peer is really connected, the `MG_EV_CONNECT` event is
@ -1434,7 +1466,6 @@ Note: this function does not connect to peer, it allocates required resources an
Parameters:
- `mgr` - Event manager to use
- `url` - Specifies remote URL, e.g. `http://google.com`
- `opts` - MQTT options, with client ID, QoS, etc
- `fn` - An event handler function
- `fn_data` - An arbitrary pointer, which will be passed as `fn_data` when an
event handler is called. This pointer is also stored in a connection
@ -1458,9 +1489,9 @@ void mg_ws_upgrade(struct mg_connection *c, struct mg_http_message *,
const char *fmt, ...);
```
Upgrade given HTTP connection to Websocket. The `fmt` is a printf-like
Upgrade given HTTP connection to WebSocket. The `fmt` is a printf-like
format string for the extra HTTP headers returned to the client in a
Websocket handshake. Set `fmt` to `NULL` if no extra headers need to be passed.
WebSocket handshake. Set `fmt` to `NULL` if no extra headers need to be passed.
Parameters:
- `c` - Connection to use
@ -1487,27 +1518,16 @@ void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
size_t mg_ws_send(struct mg_connection *c, const void *buf, size_t len, int op);
```
Send data to websocket peer
Send data to WebSocket peer
Parameters:
- `c` - Connection to use
- `buf` - Data to send
- `len` - Data size
- `op` - Websocket message type
- `op` - WebSocket message type, see [WebSocket message type](#websocket-message-type) above
Return value: sent bytes count
Possible Websocket message type:
```c
#define WEBSOCKET_OP_CONTINUE 0
#define WEBSOCKET_OP_TEXT 1
#define WEBSOCKET_OP_BINARY 2
#define WEBSOCKET_OP_CLOSE 8
#define WEBSOCKET_OP_PING 9
#define WEBSOCKET_OP_PONG 10
```
Usage example:
```c
@ -1529,16 +1549,11 @@ size_t mg_ws_vprintf(struct mg_connection *, int op, const char *fmt, va_list *)
Same as `mg_ws_send()`, but formats data using `printf()` semantics.
<span class="badge bg-danger">NOTE: </span> See [mg\_ws\_send](#mg_ws_send)
for the list of possible Websocket message types
<span class="badge bg-danger">NOTE: </span> See [mg\_snprintf](#mg_snprintf-mg_vsnprintf)
for the list of supported format specifiers
Parameters:
- `c` - Connection to use
- `op` - Websocket message type
- `fmt` - format string in `printf` semantics
- `op` - WebSocket message type, see [WebSocket message type](#websocket-message-type) above
- `fmt` - format string in `printf` semantics. see [mg\_snprintf](#mg_snprintf-mg_vsnprintf)
for the list of supported format specifiers
Return value: sent bytes count