mirror/mongoose
1
0
Fork 0
mirror of https://github.com/cesanta/mongoose.git synced 2024-11-28 21:59:02 +08:00
Code Issues Actions 5 Packages Projects Releases Wiki Activity
c6a5a64e64
mongoose/docs/README.md

4173 lines
110 KiB
Markdown
Raw Normal View History

More docs
2020-12-09 00:26:17 +08:00
# User Guide
Add docs
2020-12-07 05:12:05 +08:00
Update READMEs
2020-12-09 00:53:35 +08:00
Add docs
2020-12-07 05:12:05 +08:00
## Introduction
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Mongoose is a networking library for C/C++. It implements event-driven,
non-blocking APIs for TCP, UDP, HTTP, WebSocket, MQTT. It connects devices
Fix links and typos
2021-11-16 20:30:40 +08:00
and brings them online. Since 2004, a number of open source and commercial
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
products have utilized it. It even runs on the
Fixed typos
2021-03-11 21:01:45 +08:00
International Space Station! Mongoose makes embedded network programming fast,
Add docs
2020-12-07 05:12:05 +08:00
robust, and easy.
Update docs
2021-08-28 15:52:41 +08:00
Mongoose has two basic data structures:
Add docs
2020-12-07 05:12:05 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `struct mg_mgr` - An event manager that holds all active connections
- `struct mg_connection` - A single connection descriptor
Add docs
2020-12-07 05:12:05 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Connections could be listening, outbound, or inbound. Outbound
Add docs
2020-12-07 05:12:05 +08:00
connections are created by the `mg_connect()` call. Listening connections are
created by the `mg_listen()` call. Inbound connections are those accepted by a
listening connection. Each connection is described by a `struct mg_connection`
structure, which has a number of fields. All fields are exposed to the
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
application by design, to give an application full visibility into
Add docs
2020-12-07 05:12:05 +08:00
Mongoose's internals.
Fix links and typos
2021-11-16 20:30:40 +08:00
## 2-minute integration guide
Add docs
2020-12-07 05:12:05 +08:00
Fix links and typos
2021-11-16 20:30:40 +08:00
In order to integrate Mongoose into an existing C/C++ application or firmware,
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
please use the following steps:
Add docs
2020-12-07 05:12:05 +08:00
Update docs
2021-09-17 22:59:15 +08:00
**Step 1.** Copy
[mongoose.c](https://raw.githubusercontent.com/cesanta/mongoose/master/mongoose.c)
and
[mongoose.h](https://raw.githubusercontent.com/cesanta/mongoose/master/mongoose.h)
into the source code tree
Add docs
2020-12-07 05:12:05 +08:00
Update docs
2021-09-17 22:59:15 +08:00
**Step 2.** Add the following lines in your `main.c` file:
Add docs
2020-12-07 05:12:05 +08:00
Update docs
2021-09-15 14:43:24 +08:00
```c
Update docs
2021-09-17 22:59:15 +08:00
#include "mongoose.h"
...
Update docs
2021-09-15 14:43:24 +08:00
static void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
Update docs
2021-09-17 22:59:15 +08:00
struct mg_http_serve_opts opts = {.root_dir = "."}; // Serve local dir
Update README.md
2022-12-05 06:16:34 +08:00
if (ev == MG_EV_HTTP_MSG) mg_http_serve_dir(c, (struct mg_http_message *)ev_data, &opts);
Update docs
2021-09-15 14:43:24 +08:00
}
Update docs
2021-09-17 22:59:15 +08:00
...
int main() {
...
Update docs
2021-09-15 14:43:24 +08:00
Update docs
2021-09-17 22:59:15 +08:00
struct mg_mgr mgr;
mg_mgr_init(&mgr);
mg_http_listen(&mgr, "0.0.0.0:8000", fn, NULL); // Create listening connection
for (;;) mg_mgr_poll(&mgr, 1000); // Block forever
}
Update docs
2021-09-15 14:43:24 +08:00
```
Add docs
2020-12-07 05:12:05 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
**Step 3.** Add `mongoose.c` to the build and recompile - and that is it!
Add docs
2020-12-07 05:12:05 +08:00
Update docs
2021-09-15 14:43:24 +08:00
`mg_mgr_poll()` iterates over all connections, accepts new connections, sends and
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
receives data, closes connections, and calls event handler functions for the
Update docs
2021-09-15 14:43:24 +08:00
respective events.
Add docs
2020-12-07 05:12:05 +08:00
Docs spelling
2021-09-22 18:51:16 +08:00
Each connection has two event handler functions: `c->fn` and `c->pfn`. The
`c->fn` is a user-specified event handler function. The `c->pfn` is a
protocol-specific handler function that is set implicitly. For example, a
`mg_http_listen()` sets `c->pfn` to a Mongoose's HTTP event handler. A
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
protocol-specific handler is called before a user-specific handler. It parses
Docs spelling
2021-09-22 18:51:16 +08:00
incoming data and may invoke protocol-specific events like `MG_EV_HTTP_MSG`.
Update docs
2021-09-17 22:59:15 +08:00
<span class="badge bg-danger">NOTE:</span>
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Since Mongoose's core is not protected against concurrent accesses, make
Update docs
2021-09-17 22:59:15 +08:00
sure that all `mg_*` API functions are called from the same thread or RTOS
task.
Add docs
2020-12-07 05:12:05 +08:00
## Send and receive buffers
Each connection has a send and receive buffer:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `struct mg_connection::send` - Data to be sent to a peer
- `struct mg_connection::recv` - Data received from a peer
Add docs
2020-12-07 05:12:05 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
When data arrives, Mongoose appends received data to the `recv` and triggers a
Fix #1286
2021-05-19 07:19:21 +08:00
`MG_EV_READ` event. The user may send data back by calling one of the output
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
functions, like `mg_send()`, `mg_printf()` or a protocol-specific function like
Update docs
2021-09-15 14:43:24 +08:00
`mg_ws_send`. Output functions append data to the `send` buffer. When Mongoose
successfully writes data to the socket, it discards data from struct `mg_connection::send`
Update README.md after sending buffer to socket, MG_EV_WRITE will generated.
2022-06-01 18:06:17 +08:00
and sends an `MG_EV_WRITE` event.
Add docs
2020-12-07 05:12:05 +08:00
## Event handler function
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Each connection has an event handler function associated with it, which
must be implemented by the user. Event handler is the key element of
Mongoose, since it defines the connection's behavior. See below
Fix links and typos
2021-11-16 20:30:40 +08:00
for an example of an event handler function:
Add docs
2020-12-07 05:12:05 +08:00
```c
Docs nitpicks
2021-08-21 03:31:32 +08:00
// Event handler function defines connection's behavior
Add docs
2020-12-07 05:12:05 +08:00
static void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
Docs nitpicks
2021-08-21 03:31:32 +08:00
if (ev == MG_EV_READ) {
mg_send(c, c->recv.buf, c->recv.len); // Implement echo server
c->recv.len = 0; // Delete received data
Add docs
2020-12-07 05:12:05 +08:00
}
}
```
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `struct mg_connection *c` - A connection that received an event
- `int ev` - An event number, defined in mongoose.h. For example, when data
Fix links and typos
2021-11-16 20:30:40 +08:00
arrives on an inbound connection, `ev` would be `MG_EV_READ`
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `void *ev_data` - Points to the event-specific data, and it has a different
Fix #1286
2021-05-19 07:19:21 +08:00
meaning for different events. For example, for an `MG_EV_READ` event,
Add docs
2020-12-07 05:12:05 +08:00
`ev_data`
is an `int *` pointing to the number of bytes received from a remote
peer and saved into the `c->recv` IO buffer. The exact meaning of `ev_data` is
described for each event. Protocol-specific events usually have `ev_data`
Add restful and client example
2020-12-10 21:26:05 +08:00
pointing to structures that hold protocol-specific information
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `void *fn_data` - A user-defined pointer for the connection, which is a
Update docs
2021-08-28 18:16:45 +08:00
placeholder for application-specific data. This `fn_data` pointer is set
during the `*_listen()` or `*_connect()` call, and it is stored in the
`c->fn_data`. Listening connections copy the value of `c->fn_data` to the
newly accepted connection, so all accepted connections initially share the
same `fn_data` pointer. It is fine to update/replace that pointer for
any connection at any time by setting `c->fn_data = new_value;`
Add docs
2020-12-07 05:12:05 +08:00
## Events
Fixed typos
2021-03-11 21:01:45 +08:00
Below is the list of events triggered by Mongoose, taken as-is from `mongoose.h`.
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
For each event, a comment describes the meaning of the `ev_data` pointer passed
Add docs
2020-12-07 05:12:05 +08:00
to an event handler:
```c
enum {
Update event enum
2021-12-22 06:20:42 +08:00
MG_EV_ERROR, // Error char *error_message
MG_EV_OPEN, // Connection created NULL
Use uint64_t for uptime in millis, not int64_t
2022-04-07 20:50:25 +08:00
MG_EV_POLL, // mg_mgr_poll iteration uint64_t *milliseconds
Update event enum
2021-12-22 06:20:42 +08:00
MG_EV_RESOLVE, // Host name is resolved NULL
MG_EV_CONNECT, // Connection established NULL
MG_EV_ACCEPT, // Connection accepted NULL
Update README.md
2022-09-20 21:52:45 +08:00
MG_EV_TLS_HS, // TLS handshake succeeded NULL
Update README.md
2022-09-10 01:10:48 +08:00
MG_EV_READ, // Data received from socket long *bytes_read
Update event enum
2021-12-22 06:20:42 +08:00
MG_EV_WRITE, // Data written to socket long *bytes_written
MG_EV_CLOSE, // Connection closed NULL
MG_EV_HTTP_MSG, // HTTP request/response struct mg_http_message *
MG_EV_HTTP_CHUNK, // HTTP chunk (partial msg) struct mg_http_message *
MG_EV_WS_OPEN, // Websocket handshake done struct mg_http_message *
MG_EV_WS_MSG, // Websocket msg, text or bin struct mg_ws_message *
MG_EV_WS_CTL, // Websocket control msg struct mg_ws_message *
MG_EV_MQTT_CMD, // MQTT low-level command struct mg_mqtt_message *
MG_EV_MQTT_MSG, // MQTT PUBLISH received struct mg_mqtt_message *
MG_EV_MQTT_OPEN, // MQTT CONNACK received int *connack_status_code
Use uint64_t for uptime in millis, not int64_t
2022-04-07 20:50:25 +08:00
MG_EV_SNTP_TIME, // SNTP time received uint64_t *milliseconds
Update event enum
2021-12-22 06:20:42 +08:00
MG_EV_USER, // Starting ID for user events
Add docs
2020-12-07 05:12:05 +08:00
};
```
## Connection flags
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
`struct mg_connection` has a bitfield with connection flags. Flags are binary:
Add docs
2020-12-07 05:12:05 +08:00
they can be either 0 or 1. Some flags are set by Mongoose and must be not
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
changed by an application code. For example, the `is_udp` flag tells the application if
Add docs
2020-12-07 05:12:05 +08:00
that connection is UDP or not. Some flags can be changed by application, for
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
example, the `is_draining` flag, if set by an application, tells Mongoose to send
the remaining data to a peer, and when everything is sent, close the connection.
Add docs
2020-12-07 05:12:05 +08:00
Docs nitpick
2021-12-19 18:53:17 +08:00
<span class="badge bg-danger me-1"> NOTE: </span>User-changeable flags are:
`is_hexdumping`, `is_draining`, `is_closing`.
Add docs
2020-12-07 05:12:05 +08:00
This is taken from `mongoose.h` as-is:
```c
struct mg_connection {
...
unsigned is_listening : 1; // Listening connection
unsigned is_client : 1; // Outbound (client) connection
unsigned is_accepted : 1; // Accepted (server) connection
unsigned is_resolving : 1; // Non-blocking DNS resolv is in progress
unsigned is_connecting : 1; // Non-blocking connect is in progress
unsigned is_tls : 1; // TLS-enabled connection
unsigned is_tls_hs : 1; // TLS handshake is in progress
unsigned is_udp : 1; // UDP connection
unsigned is_websocket : 1; // WebSocket connection
unsigned is_hexdumping : 1; // Hexdump in/out traffic
unsigned is_draining : 1; // Send remaining data, then close and free
unsigned is_closing : 1; // Close and free the connection immediately
Fix #1476 - introduce c->is_full to cap the recv buf len for streaming connections
2022-06-03 18:37:35 +08:00
unsigned is_full : 1; // Stop reads, until cleared
Add c->is_resp note
2022-08-06 02:27:56 +08:00
unsigned is_resp : 1; // Response is still being generated
Add docs
2020-12-07 05:12:05 +08:00
unsigned is_readable : 1; // Connection is ready to read
unsigned is_writable : 1; // Connection is ready to write
};
```
docs
2022-04-24 18:26:25 +08:00
## Best practices
Add more on logging
2022-12-21 19:31:14 +08:00
- Debug log. To increase debug verbosity, call `mg_log_set()`:
```c
mg_log_set(MG_LL_DEBUG);
mg_mgr_init(&mgr);
```
The `MG_INFO()`, `MG_DEBUG()` logging macros use `putchar()` by default,
i.e. they use standard C `stdout` stream. That works fine on the traditional
OS. In the embedded environment, in order to see debug output, two ways
are possible: IO retargeting or Mongoose log redirection. IO retargeting
can already be implemented by an embedded SDK - for example ESP32 SDK
redirects `printf()` to the UART0. Otherwise, IO retargeting can be
implemented manually, see
[guide](https://github.com/cpq/bare-metal-programming-guide#redirect-printf-to-uart)
for more details.
The alternative way is to redirect Mongoose logs:
```c
void log_fn(char ch, void *param) {
output_a_single_character_to_UART(ch);
}
...
mg_log_set_fn(log_fn, param); // Use our custom log function
```
docs
2022-04-24 18:26:25 +08:00
- If you need to perform any sort of initialisation of your connection,
do it by catching `MG_EV_OPEN` event. That event is sent immediately
after a connection has been allocated and added to the event manager,
but before anything else:
```c
docs
2022-04-24 18:33:47 +08:00
static void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
docs
2022-04-24 18:26:25 +08:00
if (ev == MG_EV_OPEN) {
... // Do your initialisation
}
```
- If you need to keep some connection-specific data, you have two options.
First, use `c->fn_data` pointer. That pointer is passed to the event handler
docs
2022-04-24 18:33:47 +08:00
as last parameter:
```c
static void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
if (ev == MG_EV_OPEN) {
c->fn_data = malloc(123); // Change our fn_data
} else if (ev == MG_EV_CLOSE) {
free(fn_data); // Don't forget to free!
}
...
}
docs
2022-04-24 18:37:23 +08:00
// Every accepted connection inherit NULL pointer as c->fn_data, but we change
docs
2022-04-24 18:33:47 +08:00
// it per-connection to something else
docs
2022-04-24 18:37:23 +08:00
mg_http_listen(&mgr, "http://localhost:1234", fn, NULL);
docs
2022-04-24 18:33:47 +08:00
```
Another option is to use `c->label` buffer, which can
hold some amount of connection-specific data without extra memory allocation:
```c
static void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
if (ev == MG_EV_WS_OPEN) {
c->label[0] = 'W'; // Established websocket connection, store something
...
```
docs
2022-04-24 18:39:54 +08:00
- If you need to close the connection, set `c->is_draining = 1;` in your
docs
2022-04-24 18:26:25 +08:00
event handler function. That tells the event manager to send all remaining
docs
2022-04-24 18:39:54 +08:00
data in a send buffer ("drain" the connection), then close the connection.
If you need to close
the connection immediately without draining, use `c->is_closing = 1;`
docs
2022-04-24 18:26:25 +08:00
- Use `mg_http_reply()` function to create HTTP responses. That function
properly sets the `Content-Length` header, which is important. Of course
you can create responses manually, e.g. with `mg_printf()` function,
but be sure to set the `Content-Length` header:
```c
mg_printf(c, "HTTP/1.1 200 OK\r\Content-Length: %d\r\n\r\n%s", 2, "hi");
```
Alternatively, use chunked transfer enconding:
```c
mg_printf(c, "HTTP/1.1 200 OK\r\nTransfer-Encoding: chunked\r\n\r\n");
mg_http_printf_chunk(c, "%s", "foo");
mg_http_printf_chunk(c, "%s", "bar");
mg_http_printf_chunk(c, ""); // Don't forget the last empty chunk
```
Add c->is_resp note
2022-08-06 02:27:56 +08:00
<span class="badge bg-danger">NOTE:</span> if you are not using
`mg_http_reply()` or `mg_http_*_chunk()`, make sure to set
`c->is_resp = 0;` when your event handler finished writing response.
MG_ARCH_RTX nits
2022-05-12 22:07:02 +08:00
- On embedded environment, make sure that serving task has enough stack:
give it 2k for simple RESTful serving, or 4-8k for complex dynamic/static
serving. In certain environments, it is necessary to adjust heap size, too.
By default, IO buffer allocation size `MG_IO_SIZE` is 2048: change it to 512
to trim run-time per-connection memory consumption.
docs
2022-04-24 18:26:25 +08:00
Add diagrams
2022-12-21 19:18:50 +08:00
## Architecture diagram
In the Operating System environment, Mongoose uses BSD sockets API provided
by the OS's TCP/IP stack:
![](images/arch2.svg)
In the embedded bare metal environment, Mongoose can utilise its own built-in
stack with network drivers - i.e. it can run directly on top of the hardware:
![](images/arch1.svg)
Add docs
2020-12-07 05:12:05 +08:00
## Build options
Mongoose source code ships in two files:
- [mongoose.h](https://github.com/cesanta/mongoose/blob/master/mongoose.h) - API definitions
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- [mongoose.c](https://github.com/cesanta/mongoose/blob/master/mongoose.c) - Implementation
Add docs
2020-12-07 05:12:05 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Therefore, to integrate Mongoose into an application, simply copy these two
stm32f7 example starts on real h/w, with plus-TCP driver
2021-05-18 00:36:57 +08:00
files to the application's source tree. The `mongoose.c` and `mongoose.h` files
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
are actually an amalgamation - non-amalgamated sources can be found at
stm32f7 example starts on real h/w, with plus-TCP driver
2021-05-18 00:36:57 +08:00
https://github.com/cesanta/mongoose/tree/master/src
Add docs
2020-12-07 05:12:05 +08:00
Create MG_ARCH_FREERTOS, MG_ENABLE_LWIP, MG_ENABLE_FREERTOS_TCP. Remove MG_ARCH_FREERTOS_TCP, MG_ARCH_RTX_LWIP
2022-11-06 09:03:33 +08:00
Mongoose has 3 types of build constants (preprocessor definitions) that affect
the build: a target architecture/OS, target network stack, and tunables. In
order to set the option during build time, use the `-D OPTION` compiler flag:
Add docs
2020-12-07 05:12:05 +08:00
```sh
Create MG_ARCH_FREERTOS, MG_ENABLE_LWIP, MG_ENABLE_FREERTOS_TCP. Remove MG_ARCH_FREERTOS_TCP, MG_ARCH_RTX_LWIP
2022-11-06 09:03:33 +08:00
$ cc app.c mongoose.c # Use defaults!
$ cc app.c mongoose.c -D MG_ENABLE_IPV6=1 # Build with IPv6 enabled
$ cc app.c mongoose.c -D MG_ARCH=MG_ARCH_RTX # Set architecture
$ cc app.c mongoose.c -D MG_ENABLE_SSI=0 -D MG_IO_SIZE=8192 # Multiple options
Add docs
2020-12-07 05:12:05 +08:00
```
Create MG_ARCH_FREERTOS, MG_ENABLE_LWIP, MG_ENABLE_FREERTOS_TCP. Remove MG_ARCH_FREERTOS_TCP, MG_ARCH_RTX_LWIP
2022-11-06 09:03:33 +08:00
The list of supported architectures is defined in the
[arch.h](https://github.com/cesanta/mongoose/blob/master/src/arch.h) header
file. Normally, there is no need to explicitly specify the architecture. The
architecture is guessed during the build, so setting it is not usually
required.
stm32f7 example starts on real h/w, with plus-TCP driver
2021-05-18 00:36:57 +08:00
| Name | Description |
| ---- | ----------- |
|MG_ARCH_UNIX | All UNIX-like systems like Linux, MacOS, FreeBSD, etc |
|MG_ARCH_WIN32 | Windows systems |
|MG_ARCH_ESP32 | Espressif's ESP32 |
|MG_ARCH_ESP8266 | Espressif's ESP8266 |
Create MG_ARCH_FREERTOS, MG_ENABLE_LWIP, MG_ENABLE_FREERTOS_TCP. Remove MG_ARCH_FREERTOS_TCP, MG_ARCH_RTX_LWIP
2022-11-06 09:03:33 +08:00
|MG_ARCH_FREERTOS | All systems with FreeRTOS kernel|
Document all supported MG_ARCH choices
2022-08-20 10:44:17 +08:00
|MG_ARCH_AZURERTOS | Microsoft Azure RTOS |
Create MG_ARCH_FREERTOS, MG_ENABLE_LWIP, MG_ENABLE_FREERTOS_TCP. Remove MG_ARCH_FREERTOS_TCP, MG_ARCH_RTX_LWIP
2022-11-06 09:03:33 +08:00
|MG_ARCH_RTX | Keil RTX |
Document all supported MG_ARCH choices
2022-08-20 10:44:17 +08:00
|MG_ARCH_ZEPHYR | Zephyr RTOS |
|MG_ARCH_TIRTOS | TI RTOS |
|MG_ARCH_RP2040 | RP2040 SDK |
|MG_ARCH_NEWLIB | Bare ARM GCC |
stm32f7 example starts on real h/w, with plus-TCP driver
2021-05-18 00:36:57 +08:00
|MG_ARCH_CUSTOM | A custom architecture, discussed in the next section |
Create MG_ARCH_FREERTOS, MG_ENABLE_LWIP, MG_ENABLE_FREERTOS_TCP. Remove MG_ARCH_FREERTOS_TCP, MG_ARCH_RTX_LWIP
2022-11-06 09:03:33 +08:00
The network stack constants are listed below. Note that if a network stack
is not specified, then it is assumed that the target architecture supports
standard BSD socket API.
| Name | Default | Description |
| ---- | -------- | ----------- |
|MG_ENABLE_LWIP | 0 | lwIP network stack |
|MG_ENABLE_FREERTOS_TCP | 0 | Amazon FreeRTOS-Plus-TCP network stack |
|MG_ENABLE_RL | 0 | Keil MDK network stack |
|MG_ENABLE_MIP | 0 | Built-in Mongoose network stack |
stm32f7 example starts on real h/w, with plus-TCP driver
2021-05-18 00:36:57 +08:00
The other class of build constants is defined in
[src/config.h](https://github.com/cesanta/mongoose/blob/master/src/config.h)
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
together with their default values. These are tunables that include/exclude
stm32f7 example starts on real h/w, with plus-TCP driver
2021-05-18 00:36:57 +08:00
a certain functionality or change relevant parameters.
Add docs
2020-12-07 05:12:05 +08:00
Here is a list of build constants and their default values:
More docs
2020-12-09 00:26:17 +08:00
Add docs
2020-12-07 05:12:05 +08:00
| Name | Default | Description |
| ---- | ------- | ----------- |
stm32f7 example starts on real h/w, with plus-TCP driver
2021-05-18 00:36:57 +08:00
|MG_ENABLE_SOCKET | 1 | Use BSD socket low-level API |
Fix links and typos
2021-11-16 20:30:40 +08:00
|MG_ENABLE_MBEDTLS | 0 | Enable mbedTLS library |
stm32f7 example starts on real h/w, with plus-TCP driver
2021-05-18 00:36:57 +08:00
|MG_ENABLE_OPENSSL | 0 | Enable OpenSSL library |
|MG_ENABLE_IPV6 | 0 | Enable IPv6 |
|MG_ENABLE_MD5 | 0 | Use native MD5 implementation |
Implement FS virtualization
2021-07-29 21:21:20 +08:00
|MG_ENABLE_SSI | 1 | Enable serving SSI files by `mg_http_serve_dir()` |
Better packed test
2021-07-30 20:19:20 +08:00
|MG_ENABLE_CUSTOM_RANDOM | 0 | Provide custom RNG function `mg_random()` |
Introduce MG_ENABLE_CUSTOM_MILLIS
2022-04-05 01:14:59 +08:00
|MG_ENABLE_CUSTOM_TLS | 0 | Enable custom TLS library |
|MG_ENABLE_CUSTOM_MILLIS | 0 | Enable custom `mg_millis()` function |
Better packed test
2021-07-30 20:19:20 +08:00
|MG_ENABLE_PACKED_FS | 0 | Enable embedded FS support |
Add Fat FS support
2022-01-18 15:44:30 +08:00
|MG_ENABLE_FATFS | 0 | Enable embedded FAT FS support |
Remove mg_log_set_callback. Use MG_PUTCHAR macro instead
2022-05-20 16:45:17 +08:00
|MG_ENABLE_LINES | undefined | If defined, show source file names in logs |
Implement FS virtualization
2021-07-29 21:21:20 +08:00
|MG_IO_SIZE | 2048 | Granularity of the send/recv IO buffer growth |
Change MG_MAX_RECV_BUF_SIZE -> MG_MAX_RECV_SIZE
2022-06-02 20:50:44 +08:00
|MG_MAX_RECV_SIZE | (3 * 1024 * 1024) | Maximum recv buffer size |
stm32f7 example starts on real h/w, with plus-TCP driver
2021-05-18 00:36:57 +08:00
|MG_MAX_HTTP_HEADERS | 40 | Maximum number of HTTP headers |
Split TLS files and introduce MG_ENABLE_CUSTOM_TLS
2021-12-14 20:42:41 +08:00
|MG_HTTP_INDEX | "index.html" | Index file for HTML directory |
Add Fat FS support
2022-01-18 15:44:30 +08:00
|MG_FATFS_ROOT | "/" | FAT FS root directory |
Add docs
2020-12-07 05:12:05 +08:00
Docs nitpicks
2021-08-21 03:31:32 +08:00
<span class="badge bg-danger">NOTE:</span> the `MG_IO_SIZE` constant also sets
maximum UDP message size, see
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
[issues/907](https://github.com/cesanta/mongoose/issues/907) for details. If the
Docs nitpicks
2021-08-21 03:31:32 +08:00
application uses large UDP messages, increase the `MG_IO_SIZE` limit
accordingly.
Note on UDP
2020-12-17 19:19:13 +08:00
Add more docs
2021-01-20 19:28:47 +08:00
## Custom build
mongoose_custom.h not pulled in when MG_ARCH=MG_ARCH_CUSTOM
2022-11-02 08:01:33 +08:00
A custom build should be used for cases not covered by the
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
existing architecture options (e.g., an embedded architecture that
uses some proprietary RTOS and network stack). In order to build on such
systems, follow the outline below:
docs
2021-05-12 18:39:46 +08:00
1. Add `-DMG_ARCH=MG_ARCH_CUSTOM` to your build flags.
2. Create a file called `mongoose_custom.h`, with defines and includes that
Add diagrams
2022-12-21 19:18:50 +08:00
are relevant to your platform. Mongoose uses `bool` type, `MG_DIRSEP` define,
and optionally other structures like `DIR *` depending on the functionality
you have enabled - see previous section. Below is an example:
```c
#include <stdbool.h>
#include <stdarg.h>
#define MG_DIRSEP '/'
#define MG_INT64_FMT "%lld"
```
You can also add a `MG_ARCH` definition:
```c
#define MG_ARCH MG_ARCH_CUSTOM
```
Update custom build instructions
2022-05-26 09:10:28 +08:00
3. This step is optional, and only required if you intend to use a custom
TCP/IP stack. To do that, you should:
* Disable BSD socket API: in the `mongoose_custom.h`, add
Add diagrams
2022-12-21 19:18:50 +08:00
```c
#define MG_ENABLE_SOCKET 0
```
Update custom build instructions
2022-05-26 09:10:28 +08:00
* Add an implementation of several internal API functions, like
`mg_send()`, `mg_mgr_poll()`, etc. For the reference, take
a look at the stub
"do nothing" implementation at
[test/mongoose_custom.c](https://github.com/cesanta/mongoose/blob/master/test/mongoose_custom.c)
and the experimental builtin bare metal TCP/IP stack implementation
at
[src/mip.c](https://github.com/cesanta/mongoose/blob/master/src/mip.c)
Add more docs
2021-01-20 19:28:47 +08:00
More docs
2020-12-09 00:26:17 +08:00
## Minimal HTTP server
Add docs
2020-12-07 05:12:05 +08:00
Add MG_ARCH_RTX
2022-05-12 15:07:51 +08:00
This example is a simple HTTP server that serves both static and dynamic content:
Add docs
2020-12-07 05:12:05 +08:00
```c
#include "mongoose.h"
Docs nits
2021-08-22 17:51:40 +08:00
static void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
Add MG_ARCH_RTX
2022-05-12 15:07:51 +08:00
if (ev == MG_EV_HTTP_MSG) {
struct mg_http_message *hm = (struct mg_http_message *) ev_data;
docs
2022-09-05 19:29:06 +08:00
if (mg_http_match_uri(hm, "/api/hello")) { // On /api/hello requests,
mg_http_reply(c, 200, "", "{%Q:%d}\n", "status", 1); // Send dynamic JSON response
} else { // For all other URIs,
struct mg_http_serve_opts opts = {.root_dir = "."}; // Serve files
mg_http_serve_dir(c, hm, &opts); // From root_dir
Add MG_ARCH_RTX
2022-05-12 15:07:51 +08:00
}
}
Add docs
2020-12-07 05:12:05 +08:00
}
int main(int argc, char *argv[]) {
struct mg_mgr mgr;
Add MG_ARCH_RTX
2022-05-12 15:07:51 +08:00
mg_mgr_init(&mgr); // Init manager
mg_http_listen(&mgr, "http://0.0.0.0:8000", fn, &mgr); // Setup listener
for (;;) mg_mgr_poll(&mgr, 1000); // Event loop
mg_mgr_free(&mgr); // Cleanup
Add docs
2020-12-07 05:12:05 +08:00
return 0;
}
```
More docs
2020-12-09 00:26:17 +08:00
## Minimal TCP echo server
This example is a simple TCP echo server that listens on port 1234:
```c
#include "mongoose.h"
static void cb(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
Fix #1286
2021-05-19 07:19:21 +08:00
if (ev == MG_EV_READ) {
More docs
2020-12-09 00:26:17 +08:00
mg_send(c, c->recv.buf, c->recv.len); // Echo received data back
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
mg_iobuf_del(&c->recv, 0, c->recv.len); // And discard it
More docs
2020-12-09 00:26:17 +08:00
}
}
int main(int argc, char *argv[]) {
struct mg_mgr mgr;
Update docs
2021-09-15 14:43:24 +08:00
mg_mgr_init(&mgr); // Init manager
mg_listen(&mgr, "tcp://0.0.0.0:1234", cb, &mgr); // Setup listener
for (;;) mg_mgr_poll(&mgr, 1000); // Event loop
mg_mgr_free(&mgr); // Cleanup
More docs
2020-12-09 00:26:17 +08:00
return 0;
}
```
# API Reference
## Core
Update docs
2021-09-15 14:43:24 +08:00
### struct mg\_addr
```c
struct mg_addr {
uint16_t port; // TCP or UDP port in network byte order
uint32_t ip; // IP address in network byte order
uint8_t ip6[16]; // IPv6 address
bool is_ip6; // True when address is IPv6 address
};
```
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
This structure contains network address; it can be considered as a Mongoose equivalent for sockets `sockaddr` structure.
Update docs
2021-09-15 14:43:24 +08:00
### struct mg\_mgr
More docs
2020-12-09 00:26:17 +08:00
```c
Update READMEs
2020-12-09 00:53:35 +08:00
struct mg_mgr {
More docs
2020-12-09 00:26:17 +08:00
struct mg_connection *conns; // List of active connections
docs
2021-08-12 19:24:28 +08:00
struct mg_dns dns4; // DNS for IPv4
struct mg_dns dns6; // DNS for IPv6
More docs
2020-12-09 00:26:17 +08:00
int dnstimeout; // DNS resolve timeout in milliseconds
docs
2021-08-12 19:24:28 +08:00
unsigned long nextid; // Next connection ID
void *userdata; // Arbitrary user data pointer
More docs
2020-12-09 00:26:17 +08:00
};
```
Event management structure that holds a list of active connections, together
with some housekeeping information.
### struct mg\_connection
```c
struct mg_connection {
struct mg_connection *next; // Linkage in struct mg_mgr :: connections
struct mg_mgr *mgr; // Our container
Introduce local address
2022-02-23 06:00:55 +08:00
struct mg_addr loc; // Local address
struct mg_addr rem; // Remote address
More docs
2020-12-09 00:26:17 +08:00
void *fd; // Connected socket, or LWIP data
Fix #1286
2021-05-19 07:19:21 +08:00
unsigned long id; // Auto-incrementing unique connection ID
More docs
2020-12-09 00:26:17 +08:00
struct mg_iobuf recv; // Incoming data
struct mg_iobuf send; // Outgoing data
mg_event_handler_t fn; // User-specified event handler function
Fixed typos
2021-03-11 21:01:45 +08:00
void *fn_data; // User-specified function parameter
More docs
2020-12-09 00:26:17 +08:00
mg_event_handler_t pfn; // Protocol-specific handler function
void *pfn_data; // Protocol-specific function parameter
Fix #1286
2021-05-19 07:19:21 +08:00
char label[50]; // Arbitrary label
More docs
2020-12-09 00:26:17 +08:00
void *tls; // TLS specific data
unsigned is_listening : 1; // Listening connection
unsigned is_client : 1; // Outbound (client) connection
unsigned is_accepted : 1; // Accepted (server) connection
Fixed typos
2021-03-11 21:01:45 +08:00
unsigned is_resolving : 1; // Non-blocking DNS resolve is in progress
More docs
2020-12-09 00:26:17 +08:00
unsigned is_connecting : 1; // Non-blocking connect is in progress
unsigned is_tls : 1; // TLS-enabled connection
unsigned is_tls_hs : 1; // TLS handshake is in progress
unsigned is_udp : 1; // UDP connection
unsigned is_websocket : 1; // WebSocket connection
unsigned is_hexdumping : 1; // Hexdump in/out traffic
unsigned is_draining : 1; // Send remaining data, then close and free
unsigned is_closing : 1; // Close and free the connection immediately
Fix #1476 - introduce c->is_full to cap the recv buf len for streaming connections
2022-06-03 18:37:35 +08:00
unsigned is_full : 1; // Stop reads, until cleared
Add c->is_resp note
2022-08-06 02:27:56 +08:00
unsigned is_resp : 1; // Response is still being generated
More docs
2020-12-09 00:26:17 +08:00
unsigned is_readable : 1; // Connection is ready to read
unsigned is_writable : 1; // Connection is ready to write
};
```
A connection - either a listening connection, or an accepted connection,
Fixed typos
2021-03-11 21:01:45 +08:00
or an outbound connection.
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
### mg\_mgr\_init()
More docs
2020-12-09 00:26:17 +08:00
```c
docs
2021-08-12 19:24:28 +08:00
void mg_mgr_init(struct mg_mgr *mgr);
```
Initialize event manager structure:
- Set a list of active connections to NULL
- Set default DNS servers for IPv4 and IPv6
- Set default DNS lookup timeout
Parameters:
Add params and retvals
2021-09-15 20:37:57 +08:00
- `mgr` - a pointer to `mg_mgr` structure that needs to be initialized
docs
2021-08-12 19:24:28 +08:00
Return value: none
Usage example:
```c
struct mg_mgr mgr;
mg_mgr_init(&mgr);
More docs
2020-12-09 00:26:17 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
### mg\_mgr\_poll()
More docs
2020-12-09 00:26:17 +08:00
```c
void mg_mgr_poll(struct mg_mgr *mgr, int ms);
```
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Perform a single poll iteration. For each connection in the `mgr->conns` list:
- See if there is incoming data. If there is, read it into the `c->recv` buffer, send `MG_EV_READ` event
More docs
2020-12-09 00:26:17 +08:00
- See if there is data in the `c->send` buffer, and write it, send `MG_EV_WRITE` event
- If a connection is listening, accept an incoming connection if any, and send `MG_EV_ACCEPT` event to it
- Send `MG_EV_POLL` event
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Docs spelling
2021-09-22 18:51:16 +08:00
- `mgr` - an event manager to use
- `ms` - a timeout in milliseconds
Add params and retvals
2021-09-15 20:37:57 +08:00
Return value: none
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
while (running == true) mg_mgr_poll(&mgr, 1000 /* 1 sec */);
```
More docs
2020-12-09 00:26:17 +08:00
Fix README.md mg_mgr_free
2021-01-23 15:49:55 +08:00
### mg\_mgr\_free()
More docs
2020-12-09 00:26:17 +08:00
```c
void mg_mgr_free(struct mg_mgr *mgr);
```
Close all connections, and free all resources.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Docs spelling
2021-09-22 18:51:16 +08:00
- `mgr` - an event manager to cleanup
Add params and retvals
2021-09-15 20:37:57 +08:00
Return value: none
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
struct mg_mgr mgr;
mg_mgr_init(&mgr);
while (running == true) mg_mgr_poll(&mgr, 1000); // Event loop
mg_mgr_free(&mgr);
```
More docs
2020-12-09 00:26:17 +08:00
### mg\_listen()
```c
struct mg_connection *mg_listen(struct mg_mgr *mgr, const char *url,
mg_event_handler_t fn, void *fn_data);
```
Create a listening connection, append this connection to `mgr->conns`.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Docs spelling
2021-09-22 18:51:16 +08:00
- `mgr` - an event manager to use
- `url` - a URL. Specifies local IP address and port to listen on, e.g.
More docs
2020-12-09 00:26:17 +08:00
`tcp://127.0.0.1:1234` or `udp://0.0.0.0:9000`
- `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
structure as `c->fn_data`
Return value: created connection, or `NULL` on error.
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
struct mg_connection *c = mg_listen(&mgr, "tcp://127.0.0.1:8080", fn, NULL);
```
More docs
2020-12-09 00:26:17 +08:00
### mg\_connect()
```c
struct mg_connection *mg_connect(struct mg_mgr *mgr, const char *url,
mg_event_handler_t fn, void *fn_data);
```
Fixed typos
2021-03-11 21:01:45 +08:00
Create an outbound connection, append this connection to `mgr->conns`.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `mgr` - An event manager to use
- `url` - A URL, specifies remote IP address/port to connect to, e.g. `http://a.com`
- `fn` - An event handler function
- `fn_data` - An arbitrary pointer, which will be passed as `fn_data` when an
More docs
2020-12-09 00:26:17 +08:00
event handler is called. This pointer is also stored in a connection
structure as `c->fn_data`
Return value: created connection, or `NULL` on error.
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Note: This function does not connect to peer, it allocates required resources and
starts connect process. Once peer is really connected, `MG_EV_CONNECT` event is sent
Update docs
2021-09-15 14:43:24 +08:00
to connection event handler.
Usage example:
```c
struct mg_connection *c = mg_connect(&mgr, "http://example.org", fn, NULL);
```
More docs
2020-12-09 00:26:17 +08:00
### mg\_send()
```c
int mg_send(struct mg_connection *c, const void *data, size_t size);
```
Append `data` of size `size` to the `c->send` buffer. Return number of bytes
appended.
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Note: This function does not push data to the network. It only appends data to
More docs
2020-12-09 00:26:17 +08:00
the output buffer. The data is being sent when `mg_mgr_poll()` is called. If
`mg_send()` is called multiple times, the output buffer grows.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - A connection pointer
- `data` - A pointer to data to append to the send buffer
- `size` - A data size
Add params and retvals
2021-09-15 20:37:57 +08:00
Return value: `true` if data appended successfully and `false` otherwise
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
mg_send(c, "hi", 2); // Append string "hi" to the output buffer
```
More docs
2020-12-09 00:26:17 +08:00
Using mg_snprintf() everywhere
2022-02-11 01:11:03 +08:00
### mg\_printf(), mg\_vprintf()
More docs
2020-12-09 00:26:17 +08:00
```c
int mg_printf(struct mg_connection *, const char *fmt, ...);
Get rid of va_copy
2022-09-23 15:59:02 +08:00
int mg_vprintf(struct mg_connection *, const char *fmt, va_list *ap);
More docs
2020-12-09 00:26:17 +08:00
```
Same as `mg_send()`, but formats data using `printf()` semantics. Return
number of bytes appended to the output buffer.
Change argument of %M handler to mg_pfn_t plus some cosmetic changes
2022-08-09 03:01:04 +08:00
Using mg_snprintf() everywhere
2022-02-11 01:11:03 +08:00
<span class="badge bg-danger">NOTE: </span> See [mg\_snprintf](#mg_snprintf-mg_vsnprintf)
for the list of supported format specifiers
More docs
2020-12-09 00:26:17 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Docs spelling
2021-09-22 18:51:16 +08:00
- `c` - a connection pointer
- `fmt` - a format string in `printf` semantics
Add params and retvals
2021-09-15 20:37:57 +08:00
Return value: number of bytes appended to the output buffer.
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
mg_printf(c, "Hello, %s!", "world"); // Add "Hello, world!" to output buffer
```
More docs
2020-12-09 00:26:17 +08:00
Refactor multithreading API
2022-04-22 21:42:07 +08:00
### mg\_wrapfd()
More docs
2020-12-09 00:26:17 +08:00
```c
Refactor multithreading API
2022-04-22 21:42:07 +08:00
struct mg_connection *mg_wrapfd(struct mg_mgr *mgr, int fd,
mg_event_handler_t fn, void *fn_data);
More docs
2020-12-09 00:26:17 +08:00
```
Refactor multithreading API
2022-04-22 21:42:07 +08:00
Wrap a given file descriptor `fd` into a connection, and add that connection
Change argument of %M handler to mg_pfn_t plus some cosmetic changes
2022-08-09 03:01:04 +08:00
to the event manager. An `fd` descriptor must support `send()`, `recv()`,
Refactor multithreading API
2022-04-22 21:42:07 +08:00
`select()` syscalls, and be non-blocking. Mongoose will treat it as a TCP
socket. The `c->rem` and `c->loc` addresses will be empty.
Update readme
2021-08-09 16:43:21 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Refactor multithreading API
2022-04-22 21:42:07 +08:00
- `fd` - A file descriptor to wrap
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `mgr` - An event manager
- `fn` - A pointer to event handler function
- `ud` - A user data pointer. It will be passed to `fn` as `fn_data` parameter
Add params and retvals
2021-09-15 20:37:57 +08:00
Refactor multithreading API
2022-04-22 21:42:07 +08:00
Return value: Pointer to the created connection or `NULL` in case of error
### mg\_mkpipe()
```c
Handle #1562 - add udp/tcp extra param to mg_mkpipe()
2022-06-01 01:23:32 +08:00
int mg_mkpipe(struct mg_mgr *mgr, mg_event_handler_t fn, void *fn_data, bool udp);
Refactor multithreading API
2022-04-22 21:42:07 +08:00
```
Create two interconnected sockets for inter-thread communication. One socket
is wrapped into a Mongoose connection and is added to the event manager.
Another socket is returned, and supposed to be passed to a worker thread.
When a worker thread `send()`s to socket any data, that wakes up `mgr` and
`fn` event handler reveives `MG_EV_READ` event. Also, `fn` can send any
data to a worker thread, which can be `recv()`ed by a worker thread.
Handle #1562 - add udp/tcp extra param to mg_mkpipe()
2022-06-01 01:23:32 +08:00
If a socketpair is UDP, then it is guaranteed to send a
Refactor multithreading API
2022-04-22 21:42:07 +08:00
Parameters:
Handle #1562 - add udp/tcp extra param to mg_mkpipe()
2022-06-01 01:23:32 +08:00
- `mgr` - an event manager
- `fn` - a pointer to event handler function
- `fn_data` - a user data pointer. It will be passed to `fn` as `fn_data` parameter
- `udp` - tells to create UDP or TCP socketpair.
Refactor multithreading API
2022-04-22 21:42:07 +08:00
Return value: created socket, or `-1` on error
Add params and retvals
2021-09-15 20:37:57 +08:00
Fix links and typos
2021-11-16 20:30:40 +08:00
Usage example: see [examples/multi-threaded](https://github.com/cesanta/mongoose/tree/master/examples/multi-threaded).
Better multithreading support: remove mg_socketpair, add mg_mkpipe() and mg_rmpipe()
2021-08-08 00:22:47 +08:00
Add mg_hello()
2022-10-28 17:57:06 +08:00
### mg\_hello()
```c
void mg_hello(const char *url);
```
A convenience function that starts a simple web server on a given listening
URL. This function does not return until a "/quit" request is received. A
server handles the following URIs:
- `/quit` - quit the server, and exit the function
- `/debug` - set debug level, expect `{"level": 3}` as a POST payload
- For all other URIs, `hi` is returned as a response
Parameters:
- `url` - a listening URL, for example `http://0.0.0.0:8000`
More docs
2020-12-09 00:26:17 +08:00
## HTTP
### struct mg\_http\_header
```c
struct mg_http_header {
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str name; // Header name
struct mg_str value; // Header value
More docs
2020-12-09 00:26:17 +08:00
};
```
Update docs
2021-09-15 14:43:24 +08:00
Structure represents HTTP header, like `Content-Type: text/html`.
`Content-Type` is a header name and `text/html` is a header value.
More docs
2020-12-09 00:26:17 +08:00
### struct mg\_http\_message
```c
struct mg_http_message {
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str method, uri, query, proto; // Request/response line
More docs
2020-12-09 00:26:17 +08:00
struct mg_http_header headers[MG_MAX_HTTP_HEADERS]; // Headers
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str body; // Body
struct mg_str message; // Request line + headers + body
More docs
2020-12-09 00:26:17 +08:00
};
```
Update docs
2021-09-15 14:43:24 +08:00
Structure represents the HTTP message.
Docs - amend images
2022-06-02 19:02:26 +08:00
<img src="images/mg_http_message.svg" alt="HTTP message" />
Update docs
2021-09-15 14:43:24 +08:00
More docs
2020-12-09 00:26:17 +08:00
### mg\_http\_listen()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
struct mg_connection *mg_http_listen(struct mg_mgr *mgr, const char *url,
More docs
2020-12-09 00:26:17 +08:00
mg_event_handler_t fn, void *fn_data);
```
Create HTTP listener.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `mgr` - An event manager
- `url` - A URL, specifies local IP address and port to listen on, e.g. `http://0.0.0.0:8000`
- `fn` - An event handler function
- `fn_data` - An arbitrary pointer, which will be passed as `fn_data` when an
More docs
2020-12-09 00:26:17 +08:00
event handler is called. This pointer is also stored in a connection
structure as `c->fn_data`
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Pointer to created connection or `NULL` in case of error
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
struct mg_connection *c = mg_http_listen(&mgr, "0.0.0.0:8000", fn, arg);
if (c == NULL) fatal_error("Cannot create listener");
```
More docs
2020-12-09 00:26:17 +08:00
### mg\_http\_connect()
```c
struct mg_connection *mg_http_connect(struct mg_mgr *, const char *url,
mg_event_handler_t fn, void *fn_data);
```
Create HTTP client connection.
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Note: This function does not connect to peer; it allocates required resources and
Add params and retvals
2021-09-15 20:37:57 +08:00
starts connect process. Once peer is really connected `MG_EV_CONNECT` event is
sent to connection event handler.
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `mgr` - An event manager
- `url` - A URL, specifies remote URL, e.g. `http://google.com`
- `fn` - An event handler function
- `fn_data` - An arbitrary pointer, which will be passed as `fn_data` when an
More docs
2020-12-09 00:26:17 +08:00
event handler is called. This pointer is also stored in a connection
structure as `c->fn_data`
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Pointer to created connection or `NULL` in case of error
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
```c
struct mg_connection *c = mg_http_connect(&mgr, "http://google.com", fn, NULL);
if (c == NULL) fatal_error("Cannot create connection");
```
More docs
2020-12-09 00:26:17 +08:00
Fix #1462 - add helper function for getting HTTP response status code.
2022-02-13 00:51:37 +08:00
### mg\_http\_status()
```c
int mg_http_status(const struct mg_http_message *hm);
```
Get status code of the HTTP response.
Parameters:
- `hm` - Parsed HTTP response
Return value: status code, e.g. `200` for success.
More docs
2020-12-09 00:26:17 +08:00
### mg\_http\_get\_request\_len()
```c
int mg_http_get_request_len(const unsigned char *buf, size_t buf_len);
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Get length of request.
Update docs
2021-09-15 14:43:24 +08:00
The length of request is a number of bytes till the end of HTTP headers. It does
not include length of HTTP body.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `buf` - A pointer to a buffer with request
- `buf_len` - Buffer length
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: -1 on error, 0 if a message is incomplete, or the length of request
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
const char *buf = "GET /test \n\nGET /foo\n\n";
int req_len = mg_http_get_request_len(buf, strlen(buf)); // req_len == 12
```
More docs
2020-12-09 00:26:17 +08:00
Docs - amend images
2022-06-02 19:02:26 +08:00
<img src="images/mg_http_get_request_len.svg" alt="Function mg_http_get_request_len()" />
More docs
2020-12-09 00:26:17 +08:00
### mg\_http\_parse()
```c
int mg_http_parse(const char *s, size_t len, struct mg_http_message *hm);
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Parse string request into `mg_http_message` structure
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `s` - A request string
- `len` - A request string length
- `hm` - A pointer to a structure to store parsed request
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: request length (see `mg_http_get_request_len()`)
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
```c
struct mg_http_message hm;
const char *buf = "GET / HTTP/1.0\n\n";
if (mg_http_parse(buf, strlen(buf), &hm) > 0) { /* success */ }
```
More docs
2020-12-09 00:26:17 +08:00
### mg\_http\_printf\_chunk()
Update docs
2021-09-15 14:43:24 +08:00
```c
void mg_http_printf_chunk(struct mg_connection *c, const char *fmt, ...);
More docs
2020-12-09 00:26:17 +08:00
```
Write a chunk of data in chunked encoding format, using `printf()` semantic.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - A connection pointer
- `fmt` - A string, format specified in `printf` semantics
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
mg_http_printf_chunk(c, "Hello, %s!", "world");
```
More docs
2020-12-09 00:26:17 +08:00
### mg\_http\_write\_chunk()
```c
void mg_http_write_chunk(struct mg_connection *c, const char *buf, size_t len);
```
Write a chunk of data in chunked encoding format.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - A connection pointer
- `buf` - Data to write
- `len` - Data length
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
mg_http_write_chunk(c, "hi", 2);
```
### mg\_http\_delete\_chunk()
```c
void mg_http_delete_chunk(struct mg_connection *c, struct mg_http_message *hm);
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Remove chunk specified from input buffer.
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - A connection pointer
- `hm` - Chunk to delete
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
// Mongoose events handler
void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
if (ev == MG_EV_HTTP_CHUNK) {
struct mg_http_message *hm = (struct mg_http_message *) ev_data;
mg_http_delete_chunk(c, hm); // Remove received chunk
}
}
```
More docs
2020-12-09 00:26:17 +08:00
Add mg_http_serve_opts.page404
2022-06-01 06:44:03 +08:00
### struct mg\_http\_serve\_opts
More docs
2020-12-09 00:26:17 +08:00
```c
Add SSI include file=, include virtual=
2021-01-03 01:57:51 +08:00
struct mg_http_serve_opts {
Add struct mg_http_serve_opts::extra_headers
2021-03-10 15:56:14 +08:00
const char *root_dir; // Web root directory, must be non-NULL
Fixed typos
2021-03-11 21:01:45 +08:00
const char *ssi_pattern; // SSI file name pattern, e.g. #.shtml
Add struct mg_http_serve_opts::extra_headers
2021-03-10 15:56:14 +08:00
const char *extra_headers; // Extra HTTP headers to add in responses
Add mg_http_serve_opts.page404
2022-06-01 06:44:03 +08:00
const char *mime_types; // Extra mime types, ext1=type1,ext2=type2,..
const char *page404; // Path to the 404 page, or NULL by default
struct mg_fs *fs; // Filesystem implementation. Use NULL for POSIX
Add SSI include file=, include virtual=
2021-01-03 01:57:51 +08:00
};
Add mg_http_serve_opts.page404
2022-06-01 06:44:03 +08:00
```
A structure passed to `mg_http_serve_dir()` and `mg_http_serve_file()`, which
drives the behavior of those two functions.
### mg\_http\_serve\_dir()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
void mg_http_serve_dir(struct mg_connection *c, struct mg_http_message *hm,
Add SSI include file=, include virtual=
2021-01-03 01:57:51 +08:00
const struct mg_http_serve_opts *opts);
More docs
2020-12-09 00:26:17 +08:00
```
Update README.md
2022-12-15 20:52:19 +08:00
Serve static files according to the given options. Files can also be gzip compressed, including the directory index. All compressed files must end in `.gz` and there must not exist a file with the same name without the extension, otherwise it will take precedence; see [mg_http_serve_file()](#mg_http_serve_file)
<span class="badge bg-warning">NOTE: </span> In order to enable SSI, you need to set the `-DMG_ENABLE_SSI=1` build flag.
More docs
2020-12-09 00:26:17 +08:00
Add note for mg_http_serve_dir()
2021-11-25 20:29:45 +08:00
<span class="badge bg-danger">NOTE: </span> Avoid double dots `..` in
the `root_dir`. If you need to
Update README.md
2022-12-15 20:52:19 +08:00
reference an upper-level directory, use an absolute path.
Add note for mg_http_serve_dir()
2021-11-25 20:29:45 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to use
- `hm` - HTTP message, that should be served
- `opts` - Serve options. Note that `opts.root_dir` can optionally accept
Support multiple web roots
2021-09-20 19:24:44 +08:00
extra comma-separated `uri=path` pairs, see example below
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
// Mongoose events handler
void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
if (ev == MG_EV_HTTP_MSG) {
struct mg_http_message *hm = (struct mg_http_message *) ev_data;
struct mg_http_serve_opts opts;
memset(&opts, 0, sizeof(opts));
Support multiple web roots
2021-09-20 19:24:44 +08:00
opts.root_dir = "/var/www,/conf=/etc"; // Serve /var/www. URIs starting with /conf are served from /etc
Update docs
2021-09-15 14:43:24 +08:00
mg_http_serve_dir(c, hm, &opts);
}
}
```
More docs
2020-12-09 00:26:17 +08:00
FIX README mg_http_serve*
2021-01-12 18:28:41 +08:00
### mg\_http\_serve\_file()
More docs
2020-12-09 00:26:17 +08:00
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
void mg_http_serve_file(struct mg_connection *c, struct mg_http_message *hm,
Implement FS virtualization
2021-07-29 21:21:20 +08:00
const char *path, struct mg_http_serve_opts *opts);
More docs
2020-12-09 00:26:17 +08:00
```
Update README.md
2022-12-15 20:52:19 +08:00
Serve a static file. If a file with the filename specified in `path` does not exist, Mongoose tries appending `.gz`; and if such a file exists, it will serve it with a `Content-Encoding: gzip` header
Change argument of %M handler to mg_pfn_t plus some cosmetic changes
2022-08-09 03:01:04 +08:00
Fix #1647 - add note in the doc that opts->root_dir is ignored by the mg_http_serve_file()
2022-08-05 00:47:48 +08:00
<span class="badge bg-danger">NOTE: </span> `opts->root_dir` settings
is ignored by this function.
Change argument of %M handler to mg_pfn_t plus some cosmetic changes
2022-08-09 03:01:04 +08:00
Fix #1647 - add note in the doc that opts->root_dir is ignored by the mg_http_serve_file()
2022-08-05 00:47:48 +08:00
<span class="badge bg-danger">NOTE: </span> `opts->extra_headers`
must end with `\r\n`.
Update docs
2021-09-15 14:43:24 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to use
- `hm` - HTTP message to serve
- `path` - Path to file to serve
- `opts` - Serve options
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
Update mg_http_serve_file() doc
2021-01-08 00:21:01 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
// Mongoose events handler
void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
if (ev == MG_EV_HTTP_MSG) {
struct mg_http_message *hm = (struct mg_http_message *) ev_data;
Fix #1647 - add note in the doc that opts->root_dir is ignored by the mg_http_serve_file()
2022-08-05 00:47:48 +08:00
struct mg_http_serve_opts opts = {
.mime_types = "png=image/png",
.extra_headers = "AA: bb\r\nCC: dd\r\n"
};
mg_http_serve_file(c, hm, "a.png", &opts);
Update docs
2021-09-15 14:43:24 +08:00
}
}
Update mg_http_serve_file() doc
2021-01-08 00:21:01 +08:00
```
More docs
2020-12-09 00:26:17 +08:00
### mg\_http\_reply()
```c
Update docs
2021-09-15 14:43:24 +08:00
void mg_http_reply(struct mg_connection *c, int status_code,
const char *headers, const char *body_fmt, ...);
More docs
2020-12-09 00:26:17 +08:00
```
Add extra param to http_reply()
2020-12-18 06:45:22 +08:00
Send simple HTTP response using `printf()` semantic. This function formats
response body according to a `body_fmt`, and automatically appends a correct
Update docs
2021-09-15 14:43:24 +08:00
`Content-Length` header. Extra headers could be passed via `headers` parameter.
Add extra param to http_reply()
2020-12-18 06:45:22 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to use
- `status_code` - An HTTP response code
- `headers` - Extra headers, default NULL. If not NULL, must end with `\r\n`
- `fmt` - A format string for the HTTP body, in a printf semantics
More docs
2020-12-09 00:26:17 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Docs - amend images
2022-06-02 19:02:26 +08:00
<img src="images/mg_http_reply.svg" alt="Function mg_http_reply()" />
Better packed test
2021-07-30 20:19:20 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage examples:
Better packed test
2021-07-30 20:19:20 +08:00
Fix links and typos
2021-11-16 20:30:40 +08:00
Send a simple JSON response:
Update docs
2021-09-15 14:43:24 +08:00
```c
mg_http_reply(c, 200, "Content-Type: application/json\r\n", "{\"result\": %d}", 123);
```
Better packed test
2021-07-30 20:19:20 +08:00
docs nits
2022-06-24 21:24:14 +08:00
Send JSON response:
Update docs
2021-09-15 14:43:24 +08:00
```c
docs nits
2022-06-24 21:24:14 +08:00
char *json = mg_mprintf("{%Q:%d}", "name", 123);
mg_http_reply(c, 200, "Content-Type: application/json\r\n", "%s\n", json);
Update docs
2021-09-15 14:43:24 +08:00
free(json);
```
Send a 302 redirect:
```c
mg_http_reply(c, 302, "Location: /\r\n", "");
```
Send error:
```c
mg_http_reply(c, 403, "", "%s", "Not Authorized\n");
```
More docs
2020-12-09 00:26:17 +08:00
Corrected small typo in docs
2021-04-30 00:16:33 +08:00
### mg\_http\_get\_header()
More docs
2020-12-09 00:26:17 +08:00
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
struct mg_str *mg_http_get_header(struct mg_http_message *hm, const char *name);
More docs
2020-12-09 00:26:17 +08:00
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Get HTTP header value
Parameters:
- `hm` - HTTP message to look for header
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `name` - Header name
Add params and retvals
2021-09-15 20:37:57 +08:00
Return value: HTTP header value or `NULL` if not found
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
// Mongoose event handler
void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
if (ev == MG_EV_HTTP_MSG) {
struct mg_http_message *hm = (struct mg_http_message *) ev_data;
struct mg_str *s = mg_http_get_header(hm, "X-Extra-Header");
if (s != NULL) {
mg_http_reply(c, 200, "", "Holly molly! Header value: %.*s", (int) s->len, s->ptr);
} else {
mg_http_reply(c, 200, "", "Oh no, header is not set...");
}
}
}
```
More docs
2020-12-09 00:26:17 +08:00
Add mg_http_get_header_var()
2021-12-03 17:54:03 +08:00
### mg\_http\_get\_header\_var()
```c
struct mg_str mg_http_get_header_var(struct mg_str s, struct mg_str v);
```
Parse HTTP header (e.g. Cookie header) which has form
`name1=value1; name2=value2; ...` and fetch a given variable.
Parameters:
- `s` - HTTP header
- `name` - variable name name
Return value: a requested variable, or an empty string.
Usage example:
```c
struct mg_str *cookie = mg_http_get_header(hm, "Cookie");
struct mg_str token = mg_str("");
if (cookie != NULL) {
token = mg_http_get_header_var(*cookie, mg_str("access_token"));
}
```
Add mg_http_var
2022-06-18 11:23:56 +08:00
### mg\_http\_var()
```c
struct mg_str mg_http_var(struct mg_str buf, struct mg_str name);
```
Fetch an undecoded HTTP variable. Parameters:
- `buf` - a url-encoded string: HTTP request body or query string
- `name` - a variable name to fetch
Return value: variable's value. If not found, it it a NULL string.
```c
// We have received a request to /my/uri?a=b&c=d%20
// The hm->query points to "a=b&c=d%20"
struct mg_str v = mg_http_var(hm->query, mg_str("c")); // v = "d%20"
```
Add mg_http_get_header_var()
2021-12-03 17:54:03 +08:00
More docs
2020-12-09 00:26:17 +08:00
### mg\_http\_get\_var()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
int mg_http_get_var(const struct mg_str *var, const char *name, char *buf, int len);
More docs
2020-12-09 00:26:17 +08:00
```
Add mg_http_var
2022-06-18 11:23:56 +08:00
Fetch and decode an HTTP variable
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `var` - HTTP request body
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `name` - Variable name
- `buf` - Buffer to write decoded variable
- `len` - Buffer size
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Length of decoded variable. A zero or negative value means error
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
More docs
2020-12-09 00:26:17 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
char buf[100] = "";
mg_http_get_var(&hm->body, "key1", buf, sizeof(buf)) {
Add mg_http_var
2022-06-18 11:23:56 +08:00
...
}
More docs
2020-12-09 00:26:17 +08:00
```
### mg\_http\_creds()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
void mg_http_creds(struct mg_http_message *hm, char *user, size_t userlen,
Update docs
2021-09-15 14:43:24 +08:00
char *pass, size_t passlen);
More docs
2020-12-09 00:26:17 +08:00
```
Fetch authentication credential from the request, and store into the
`user`, `userlen` and `pass`, `passlen` buffers. The credentials are looked
up in the following order:
- from the `Authorization` HTTP header,
- Basic auth fills both user and pass
- Bearer auth fills only pass
- from the `access_token` cookie, fills pass
- from the `?access_token=...` query string parameter, fills pass
If none is found, then both user and pass are set to empty nul-terminated strings.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `hm` - HTTP message to look for credentials
- `user` - buffer to receive user name
- `userlen` - size of `user` buffer
- `pass` - buffer to receive password
- `passlen` - size of `pass` buffer
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
// Mongoose events handler
void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
if (ev == MG_EV_HTTP_MSG) {
struct mg_http_message *hm = (struct mg_http_message *) ev_data;
char user[100], pass[100];
mg_http_creds(hm, user, sizeof(user), pass, sizeof(pass)); // "user" is now user name and "pass" is now password from request
}
}
```
More docs
2020-12-09 00:26:17 +08:00
### mg\_http\_match\_uri()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
bool mg_http_match_uri(const struct mg_http_message *hm, const char *glob);
More docs
2020-12-09 00:26:17 +08:00
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Check if HTTP request matches a given glob pattern.
Parameters:
- `hm` - HTTP message to match
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `glob` - Pattern
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: True if HTTP request matches a given glob pattern; false otherwise
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
// Mongoose events handler
void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
if (ev == MG_EV_HTTP_MSG) {
struct mg_http_message *hm = (struct mg_http_message *) ev_data;
if (mg_http_match_uri(hm, "/secret")) {
mg_http_reply(c, 200, NULL, "Very big secret!");
} else {
mg_http_reply(c, 200, NULL, "hello world..");
}
}
}
```
More docs
2020-12-09 00:26:17 +08:00
### mg\_http\_bauth()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
void mg_http_bauth(struct mg_connection *c, const char *user, const char *pass);
More docs
2020-12-09 00:26:17 +08:00
```
Write a Basic `Authorization` header to the output buffer.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to use
- `user` - User name
- `pass` - Password
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Example for mg_http_bauth
2021-12-13 23:08:05 +08:00
Usage example which uses Basic auth to create Stripe subscription:
Update docs
2021-09-15 14:43:24 +08:00
```c
Example for mg_http_bauth
2021-12-13 23:08:05 +08:00
mg_printf(c, "POST /v1/subscriptions HTTP/1.1\r\n"
"Host: api.stripe.com\r\n"
"Transfer-Encoding: chunked\r\n");
mg_http_bauth(c, stripe_private_key, NULL); // Add Basic auth header
mg_printf(c, "%s", "\r\n"); // End HTTP headers
mg_http_printf_chunk(c, "&customer=%s", customer_id); // Set customer
mg_http_printf_chunk(c, "&items[0][price]=%s", price); // And price
Example for mg_http_bauth
2021-12-13 23:14:29 +08:00
mg_http_printf_chunk(c, ""); // End request
Update docs
2021-09-15 14:43:24 +08:00
```
Docs images
2022-05-31 18:38:03 +08:00
### struct mg\_http\_part
Add mg_http_next_multipart()
2021-03-17 15:43:29 +08:00
```c
// Parameter for mg_http_next_multipart
struct mg_http_part {
struct mg_str name; // Form field name
struct mg_str filename; // Filename for file uploads
struct mg_str body; // Part contents
};
Update docs
2021-09-15 14:43:24 +08:00
```
Add mg_http_next_multipart()
2021-03-17 15:43:29 +08:00
Docs images
2022-05-31 18:38:03 +08:00
Structure that describes a single part of a HTTP multipart message.
Docs - amend images
2022-06-02 19:02:26 +08:00
<img src="images/mg_http_part.svg" alt="HTTP part" />
Docs images
2022-05-31 18:38:03 +08:00
### mg\_http\_next\_multipart()
Update docs
2021-09-15 14:43:24 +08:00
```c
Add mg_http_next_multipart()
2021-03-17 15:43:29 +08:00
size_t mg_http_next_multipart(struct mg_str body, size_t offset, struct mg_http_part *part);
```
Parse the multipart chunk in the `body` at a given `offset`. An initial
`offset` should be 0. Fill up parameters in the provided `part`, which could be
NULL. Return offset to the next chunk, or 0 if there are no more chunks.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `body`- Message body
- `offset` - Start offset
- `part` - Pointer to `struct mg_http_part` to fill
Add params and retvals
2021-09-15 20:37:57 +08:00
Return value: offset to the next chunk, or 0 if there are no more chunks.
Fix broken link
2022-10-05 18:49:06 +08:00
Usage example (or see [form upload tutorial](../tutorials/file-uploads/) ):
Update docs
2021-09-15 14:43:24 +08:00
```c
struct mg_http_part part;
docs
2022-06-04 15:29:03 +08:00
size_t pos = 0;
while ((pos = mg_http_next_multipart(body, pos, &part)) != 0) {
Update docs
2021-09-15 14:43:24 +08:00
// Use part
}
```
More docs
2020-12-09 00:26:17 +08:00
docs
2022-06-04 15:29:03 +08:00
A diagram below shows how `mg_http_next_multipart()` in action:
<img src="images/mg_http_next_multipart.svg" alt="Function mg_http_next_multipart()" />
Change mg_http_upload API
2022-07-01 04:54:50 +08:00
### mg\_http\_upload()
```c
int mg_http_upload(struct mg_connection *c, struct mg_http_message *hm,
struct mg_fs *fs, const char *path, size_t max_size);
```
This is a helper utility function that is used to upload large files by small
chunks.
Append HTTP POST data to a file in a specified directory. A file name and
file offset are specified by the query string parameters:
`POST /upload?name=firmware.bin&offset=2048 HTTP/1.1`. If the offset is 0, then the
file is truncated. It is a client's responsibility to divide a file into a
smaller chunks and send a sequence of POST requests that will be handled by
this function.
Parameters:
- `c`- a connection
- `hm` - a parsed HTTP message
- `fs` - a filesystem where to write a file, e.g. `&mg_fs_posix`
- `path` - a filename
- `max_size` - a maximum allowed file size
Return value: file size after write, or negative number on error
Usage example:
```c
static void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
if (ev == MG_EV_HTTP_MSG) {
struct mg_http_message *hm = (struct mg_http_message *) ev_data;
if (mg_http_match_uri(hm, "/upload")) {
mg_http_upload(c, hm, &mg_fs_posix, "/tmp/myfile.bin", 99999);
} else {
struct mg_http_serve_opts opts = {.root_dir = "."}; // Serve
mg_http_serve_dir(c, ev_data, &opts); // static content
}
}
}
```
Augment WS documentation
2022-10-27 23:01:47 +08:00
## WebSocket
More docs
2020-12-09 00:26:17 +08:00
### struct mg\_ws\_message
```c
struct mg_ws_message {
Augment WS documentation
2022-10-27 23:01:47 +08:00
struct mg_str data; // WebSocket message data
uint8_t flags; // WebSocket message flags
More docs
2020-12-09 00:26:17 +08:00
};
```
Augment WS documentation
2022-10-27 23:01:47 +08:00
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
Update docs
2021-09-15 14:43:24 +08:00
More docs
2020-12-09 00:26:17 +08:00
### mg\_ws\_connect()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
struct mg_connection *mg_ws_connect(struct mg_mgr *mgr, const char *url,
More docs
2020-12-09 00:26:17 +08:00
mg_event_handler_t fn, void *fn_data,
const char *fmt, ...);
```
Augment WS documentation
2022-10-27 23:01:47 +08:00
Create client WebSocket connection.
Add params and retvals
2021-09-15 20:37:57 +08:00
Note: this function does not connect to peer, it allocates required resources and
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
starts the connect process. Once peer is really connected, the `MG_EV_CONNECT` event is
Add params and retvals
2021-09-15 20:37:57 +08:00
sent to connection event handler.
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `mgr` - Event manager to use
- `url` - Specifies remote URL, e.g. `http://google.com`
- `fn` - An event handler function
- `fn_data` - An arbitrary pointer, which will be passed as `fn_data` when an
More docs
2020-12-09 00:26:17 +08:00
event handler is called. This pointer is also stored in a connection
structure as `c->fn_data`
- `fmt` - printf-like format string for additional HTTP headers, or NULL
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Pointer to created connection or `NULL` on error
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
struct mg_connection *c = mg_ws_connect(&mgr, "ws://test_ws_server.com:1000",
handler, NULL, "%s", "Sec-WebSocket-Protocol: echo\r\n");
if(c == NULL) fatal("Cannot create connection");
```
More docs
2020-12-09 00:26:17 +08:00
### mg\_ws\_upgrade()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
void mg_ws_upgrade(struct mg_connection *c, struct mg_http_message *,
Add extra headers param to mg_ws_upgrade()
2021-01-17 06:48:43 +08:00
const char *fmt, ...);
More docs
2020-12-09 00:26:17 +08:00
```
Augment WS documentation
2022-10-27 23:01:47 +08:00
Upgrade given HTTP connection to WebSocket. The `fmt` is a printf-like
Add extra headers param to mg_ws_upgrade()
2021-01-17 06:48:43 +08:00
format string for the extra HTTP headers returned to the client in a
Augment WS documentation
2022-10-27 23:01:47 +08:00
WebSocket handshake. Set `fmt` to `NULL` if no extra headers need to be passed.
More docs
2020-12-09 00:26:17 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to use
Add params and retvals
2021-09-15 20:37:57 +08:00
- `hm` - HTTP message
- `fmt` - printf-like format string for additional HTTP headers, or NULL
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
// Mongoose events handler
void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
if (ev == MG_EV_HTTP_MSG) {
struct mg_http_message *hm = (struct mg_http_message *) ev_data;
mg_ws_upgrade(c, hm, NULL); // Upgrade HTTP to WS
}
}
```
More docs
2020-12-09 00:26:17 +08:00
### mg\_ws\_send()
```c
Get rid of mg_*asprintf
2022-08-13 22:37:55 +08:00
size_t mg_ws_send(struct mg_connection *c, const void *buf, size_t len, int op);
More docs
2020-12-09 00:26:17 +08:00
```
Augment WS documentation
2022-10-27 23:01:47 +08:00
Send data to WebSocket peer
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to use
- `buf` - Data to send
- `len` - Data size
Augment WS documentation
2022-10-27 23:01:47 +08:00
- `op` - WebSocket message type, see [WebSocket message type](#websocket-message-type) above
Add params and retvals
2021-09-15 20:37:57 +08:00
Return value: sent bytes count
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
// Mongoose events handler
void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
if (ev == MG_EV_WS_OPEN) {
struct mg_http_message *hm = (struct mg_http_message *) ev_data;
mg_ws_send(c, "opened", 6, WEBSOCKET_OP_BINARY); // Send "opened" to web socket connection
}
}
```
Add mg_ws_printf()/vprintf() doc
2022-07-21 22:46:50 +08:00
### mg\_ws\_printf(), mg\_ws\_vprintf()
```c
size_t mg_ws_printf(struct mg_connection *, int op, const char *fmt, ...);
Get rid of mg_*asprintf
2022-08-13 22:37:55 +08:00
size_t mg_ws_vprintf(struct mg_connection *, int op, const char *fmt, va_list *);
Add mg_ws_printf()/vprintf() doc
2022-07-21 22:46:50 +08:00
```
Same as `mg_ws_send()`, but formats data using `printf()` semantics.
Change argument of %M handler to mg_pfn_t plus some cosmetic changes
2022-08-09 03:01:04 +08:00
Add mg_ws_printf()/vprintf() doc
2022-07-21 22:46:50 +08:00
Parameters:
- `c` - Connection to use
Augment WS documentation
2022-10-27 23:01:47 +08:00
- `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
Add mg_ws_printf()/vprintf() doc
2022-07-21 22:46:50 +08:00
Return value: sent bytes count
Usage example:
```c
mg_ws_printf(c, WEBSOCKET_OP_TEXT, "Hello, %s!", "world");
```
Update docs
2021-09-15 14:43:24 +08:00
### mg\_ws\_wrap()
```c
size_t mg_ws_wrap(struct mg_connection *c, size_t len, int op)
```
Convert data in output buffer to WebSocket format. Useful then implementing protocol over WebSocket
Fix links
2021-11-16 17:54:36 +08:00
See [examples/mqtt-over-ws-client](https://github.com/cesanta/mongoose/tree/master/examples/mqtt-over-ws-client) for full example.
Update docs
2021-09-15 14:43:24 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to use
- `len` - Bytes count to convert
Add params and retvals
2021-09-15 20:37:57 +08:00
- `op` - Websocket message type (see `mg_ws_send`)
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: New size of connection output buffer
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
size_t len = c->send.len; // Store output buffer len
mg_mqtt_login(c, s_url, &opts); // Write MQTT login message
mg_ws_wrap(c, c->send.len - len, WEBSOCKET_OP_BINARY); // Wrap it into WS
```
## SNTP
### mg_sntp_connect()
```c
struct mg_connection *mg_sntp_connect(struct mg_mgr *mgr, const char *url,
mg_event_handler_t fn, void *fn_data)
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Connect SNTP server.
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `mgr` - Event manager to use
- `url` - Specifies remote URL, `time.google.com` if NULL.
- `fn` - An event handler function
- `fn_data` - An arbitrary pointer, which will be passed as `fn_data` when an
Add params and retvals
2021-09-15 20:37:57 +08:00
event handler is called. This pointer is also stored in a connection
structure as `c->fn_data`
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Pointer to created connection or `NULL` on error
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
static void sntp_cb(struct mg_connection *c, int ev, void *evd, void *fnd) {
if (ev == MG_EV_SNTP_TIME) {
// Time received
struct timeval *tv = (struct timeval *tv)evd;
}
}
...
mg_sntp_connect(mgr&, NULL /* connect to time.google.com */, sntp_cb, NULL);
```
Increate SNTP timeout 3s->5s. Change mg_sntp_send() to mg_sntp_request(), remove one unnecessary parameter
2022-05-16 01:41:01 +08:00
### mg_sntp_request()
Update docs
2021-09-15 14:43:24 +08:00
```c
Increate SNTP timeout 3s->5s. Change mg_sntp_send() to mg_sntp_request(), remove one unnecessary parameter
2022-05-16 01:41:01 +08:00
void mg_sntp_request(struct mg_connection *c)
Update docs
2021-09-15 14:43:24 +08:00
```
Increate SNTP timeout 3s->5s. Change mg_sntp_send() to mg_sntp_request(), remove one unnecessary parameter
2022-05-16 01:41:01 +08:00
Send time request to SNTP server
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to use
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
Increate SNTP timeout 3s->5s. Change mg_sntp_send() to mg_sntp_request(), remove one unnecessary parameter
2022-05-16 01:41:01 +08:00
mg_sntp_request(c);
Update docs
2021-09-15 14:43:24 +08:00
```
More docs
2020-12-09 00:26:17 +08:00
## MQTT
### struct mg\_mqtt\_opts
```c
struct mg_mqtt_opts {
Update mqtt docs
2022-08-05 01:50:20 +08:00
struct mg_str user; // Username, can be empty
struct mg_str pass; // Password, can be empty
struct mg_str client_id; // Client ID
struct mg_str will_topic; // Will topic
struct mg_str will_message; // Will message
uint8_t will_qos; // Will message quality of service
uint8_t version; // Can be 4 (3.1.1), or 5. If 0, assume 4.
uint16_t keepalive; // Keep-alive timer in seconds
bool will_retain; // Retain last will
bool clean; // Use clean session, 0 or 1
More docs
2020-12-09 00:26:17 +08:00
};
```
Update docs
2021-09-15 14:43:24 +08:00
Structure used to specify MQTT connection options.
More docs
2020-12-09 00:26:17 +08:00
### struct mg\_mqtt\_message
```c
struct mg_mqtt_message {
Update mqtt docs
2022-08-05 01:50:20 +08:00
struct mg_str topic; // Parsed topic
struct mg_str data; // Parsed message
struct mg_str dgram; // Whole MQTT datagram, including headers
uint16_t id; // Set for PUBACK, PUBREC, PUBREL, PUBCOMP, SUBACK, PUBLISH
uint8_t cmd; // MQTT command, one of MQTT_CMD_*
uint8_t qos; // Quality of service
uint8_t ack; // Connack return code. 0 - success
More docs
2020-12-09 00:26:17 +08:00
};
```
Update docs
2021-09-15 14:43:24 +08:00
Structure represents the MQTT message.
More docs
2020-12-09 00:26:17 +08:00
### mg\_mqtt\_connect()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
struct mg_connection *mg_mqtt_connect(struct mg_mgr *mgr, const char *url,
More docs
2020-12-09 00:26:17 +08:00
struct mg_mqtt_opts *opts,
mg_event_handler_t fn, void *fn_data);
```
Create client MQTT connection.
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Note: This function does not connect to peer; it allocates required resources and
Add params and retvals
2021-09-15 20:37:57 +08:00
starts connect process. Once peer is really connected `MG_EV_CONNECT` event is
sent to connection event handler.
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `mgr` - Event manager to use
- `url` - Specifies remote URL, e.g. `http://google.com`
More docs
2020-12-09 00:26:17 +08:00
- `opts` - MQTT options, with client ID, qos, etc
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `fn` - An event handler function
- `fn_data` - An arbitrary pointer, which will be passed as `fn_data` when an
More docs
2020-12-09 00:26:17 +08:00
event handler is called. This pointer is also stored in a connection
structure as `c->fn_data`
Add params and retvals
2021-09-15 20:37:57 +08:00
Return value: pointer to created connection or `NULL` on error
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
More docs
2020-12-09 00:26:17 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
void fn(struct mg_connection *c, int ev, void *evd, void *fnd) {
char *buf = (char *) fnd;
if (ev == MG_EV_MQTT_OPEN) {
// Connection ready
}
}
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
mg_mqtt_connect(&mgr, "mqtt://test.org:1883", NULL, handler, NULL);
```
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
### mg\_mqtt\_listen()
More docs
2020-12-09 00:26:17 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
struct mg_connection *mg_mqtt_listen(struct mg_mgr *mgr, const char *url,
mg_event_handler_t fn, void *fn_data);
More docs
2020-12-09 00:26:17 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
Create MQTT listener.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `mgr` - Event manager to use
- `url` - Specifies local IP address and port to listen on, e.g. `mqtt://0.0.0.0:1883`
- `fn` - An event handler function
- `fn_data` - An arbitrary pointer, which will be passed as `fn_data` when an
Update docs
2021-09-15 14:43:24 +08:00
event handler is called. This pointer is also stored in a connection
structure as `c->fn_data`
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Pointer to created connection or `NULL` on error
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
struct mg_connection *c = mg_mqtt_listen(&mgr, "0.0.0.0:1883", fn, arg);
if (c == NULL) fatal("Cannot create connection");
```
### mg\_mqtt\_login
```c
void mg_mqtt_login(struct mg_connection *c, const char *url,
struct mg_mqtt_opts *opts);
```
Send MQTT login request.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to use
- `url` - URL, containing user name and password to use
- `opts` - Request options
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
// Mongoose events handler
void fn(struct mg_connection *c, int ev, void *evd, void *fnd) {
char *buf = (char *) fnd;
if (ev == MG_EV_MQTT_OPEN) {
struct mg_mqtt_opts opts = {.qos = 1,
.will_topic = mg_str("my topic"),
.will_message = mg_str("goodbye")};
mg_mqtt_login(c, s_url, &opts);
}
}
```
### mg\_mqtt\_pub()
```c
Use mg_str, not pointers, in mg_mqtt_{sub,pub}
2022-01-19 17:57:27 +08:00
void mg_mqtt_pub(struct mg_connection *c, struct mg_str topic,
struct mg_str data, int qos, bool retain);
Update docs
2021-09-15 14:43:24 +08:00
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Publish message.
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to use
- `topic` - Topic to publish data
- `data` - Data to publish
- `qos` - Required QoS
- `retain` - Retain flag
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
Use mg_str, not pointers, in mg_mqtt_{sub,pub}
2022-01-19 17:57:27 +08:00
mg_mqtt_pub(c, mg_str("topic"), mg_str("my data"), 1, false);
Update docs
2021-09-15 14:43:24 +08:00
```
### mg\_mqtt\_sub()
```c
Use mg_str, not pointers, in mg_mqtt_{sub,pub}
2022-01-19 17:57:27 +08:00
void mg_mqtt_sub(struct mg_connection *c, struct mg_str topic, int qos);
Update docs
2021-09-15 14:43:24 +08:00
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Subscribe to topic.
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to use
- `topic` - Topic to subscribe
Fix links and typos
2021-11-16 20:30:40 +08:00
- `qos` - Required QoS
Add params and retvals
2021-09-15 20:37:57 +08:00
Small fix to mg_timer_add() documentation The return value was not documented.
2022-05-27 04:43:56 +08:00
Return value: None
Update docs
2021-09-15 14:43:24 +08:00
```c
Use mg_str, not pointers, in mg_mqtt_{sub,pub}
2022-01-19 17:57:27 +08:00
mg_mqtt_sub(c, mg_str("my/topic"), 1);
Update docs
2021-09-15 14:43:24 +08:00
```
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
### mg\_mqtt\_send_header()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
void mg_mqtt_send_header(struct mg_connection *c, uint8_t cmd, uint8_t flags, uint32_t len);
Update docs
2021-09-15 14:43:24 +08:00
```
Send MQTT command header. Useful in MQTT server implementation. Command can be one of the following value:
```c
#define MQTT_CMD_CONNECT 1
#define MQTT_CMD_CONNACK 2
#define MQTT_CMD_PUBLISH 3
#define MQTT_CMD_PUBACK 4
#define MQTT_CMD_PUBREC 5
#define MQTT_CMD_PUBREL 6
#define MQTT_CMD_PUBCOMP 7
#define MQTT_CMD_SUBSCRIBE 8
#define MQTT_CMD_SUBACK 9
#define MQTT_CMD_UNSUBSCRIBE 10
#define MQTT_CMD_UNSUBACK 11
#define MQTT_CMD_PINGREQ 12
#define MQTT_CMD_PINGRESP 13
#define MQTT_CMD_DISCONNECT 14
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to use
- `cmd` - Command (see above)
- `flags` - Command flags
- `len` - Size of the following command
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
// Mongoose events handler
void fn(struct mg_connection *c, int ev, void *ev_data, void *fn_data) {
if (ev == MG_EV_MQTT_CMD) {
struct mg_mqtt_message *mm = (struct mg_mqtt_message *) ev_data;
if (mm->cmd == MQTT_CMD_CONNECT) {
uint8_t response[] = {0, 0};
mg_mqtt_send_header(c, MQTT_CMD_CONNACK, 0, sizeof(response)); // Send acknowledgement
mg_send(c, response, sizeof(response));
}
}
}
```
### mg\_mqtt\_ping()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
void mg_mqtt_ping(struct mg_connection *c);
Update docs
2021-09-15 14:43:24 +08:00
```
Send `MQTT_CMD_PINGREQ` command via `mg_mqtt_send_header`
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to use
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
// Send periodic pings to all WS connections
static void timer_fn(void *arg) {
struct mg_mgr *mgr = (struct mg_mgr *) arg;
for (struct mg_connection *c = mgr->conns; c != NULL; c = c->next) {
if (c->is_websocket) mg_mqtt_ping(c);
}
}
```
### mg_mqtt_parse
```c
int mg_mqtt_parse(const uint8_t *buf, size_t len, struct mg_mqtt_message *m);
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Parse buffer and fill `mg_mqtt_message` structure if buffer contain MQTT message.
Parameters:
- `buf` - buffer with MQTT message to parse
- `len` - buffer size
- `m` - pointer to `mg_mqtt_message` structure to receive parsed message
Return value: `MQTT_OK` if message successfully parsed, `MQTT_INCOMPLETE` if message
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
isn't fully received and `MQTT_MALFORMED` if message has wrong format.
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
// Iterate over all MQTT frames contained in buf, len
struct mg_mqtt_message mm;
updated docs and example to recently exported MQTT result codes
2022-07-05 01:32:12 +08:00
while ((mg_mqtt_parse(buf, len, &mm)) == MQTT_OK) {
Update docs
2021-09-15 14:43:24 +08:00
switch (mm.cmd) {
case MQTT_CMD_CONNACK:
...
}
buf += mm.dgram.len;
len -= mm.dgram.len;
}
```
More docs
2020-12-09 00:26:17 +08:00
## TLS
Update docs
2021-08-28 15:21:29 +08:00
### struct mg\_tls\_opts
More docs
2020-12-09 00:26:17 +08:00
```c
struct mg_tls_opts {
const char *ca; // CA certificate file. For both listeners and clients
mbedtls CRL support Certificate revocation checking when using mbedtls
2021-10-14 23:32:48 +08:00
const char *crl; // Certificate Revocation List. For clients
More docs
2020-12-09 00:26:17 +08:00
const char *cert; // Certificate
const char *certkey; // Certificate key
const char *ciphers; // Cipher list
Improve SNI
2021-01-30 21:03:11 +08:00
struct mg_str srvname; // If not empty, enables server name verification
Add fs arg to mg_file* and mg_http_upload API
2022-01-19 01:11:02 +08:00
struct mg_fs *fs; // FS API for reading certificate files
More docs
2020-12-09 00:26:17 +08:00
};
Update docs
2021-08-28 15:21:29 +08:00
```
TLS initialisation structure:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `ca` - Certificate Authority. Can be a filename or a string. Used to verify
a certificate that the other end sends to us. If NULL, then certificate checking
Update docs
2021-08-28 15:21:29 +08:00
is disabled
mbedtls CRL support Certificate revocation checking when using mbedtls
2021-10-14 23:32:48 +08:00
- `crl` - Certificate Revocation List. Can be a filename or a string. Used to
verify a certificate that the other end sends to us. If NULL, then certificate
revocation checking is disabled
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `cert` - Our own certificate. Can be a filename, or a string. If NULL, then
Update docs
2021-08-28 15:21:29 +08:00
we don't authenticate with the other peer
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `certkey` - A key for a `cert`. Sometimes, a certificate and its key are
Update docs
2021-08-28 15:21:29 +08:00
bundled in a single .pem file, in which case the values for `cert` and
`certkey` could be the same
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `ciphers` - A list of allowed ciphers
- `srvname` - Enable server name verification
Update docs
2021-08-28 15:21:29 +08:00
NOTE: if both `ca` and `cert` are set, then so-called two-way TLS is enabled,
when both sides authenticate with each other. Usually, server-side connections
set both `ca` and `cert`, whilst client-side - only `ca`.
### mg\_tls\_init()
```c
Update docs
2021-09-15 14:43:24 +08:00
void mg_tls_init(struct mg_connection *c, struct mg_tls_opts *opts);
More docs
2020-12-09 00:26:17 +08:00
```
Improve SNI
2021-01-30 21:03:11 +08:00
Initialise TLS on a given connection.
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
<span class="badge bg-danger">NOTE:</span> mbedTLS implementation uses `mg_random`
as RNG. The `mg_random` can be overridden by setting `MG_ENABLE_CUSTOM_RANDOM`
and defining your own `mg_random()` implementation.
Make mg_random() weak, see #1269
2021-04-29 16:09:21 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection, for which TLS should be initialized
Add params and retvals
2021-09-15 20:37:57 +08:00
- `opts` - TLS initialization parameters
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
```c
struct mg_tls_opts opts = {.cert = "ca.pem"};
mg_tls_init(c, &opts);
```
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
## Timer
More docs
2020-12-09 00:26:17 +08:00
Fix #1520 - move state to struct mg_mgr
2022-04-12 21:14:55 +08:00
### mg\_timer\_add()
```c
Small fix to mg_timer_add() documentation The return value was not documented.
2022-05-27 04:43:56 +08:00
struct mg_timer *mg_timer_add(struct mg_mgr *mgr,
Fix #1520 - move state to struct mg_mgr
2022-04-12 21:14:55 +08:00
uint64_t period_ms, unsigned flags,
void (*fn)(void *), void *fn_data);
```
Setup a timer. This is a high-level timer API that allows to add a software
timer to the event manager. This function `calloc()`s a new timer and
adds it to the `mgr->timers` list. All added timers are polled when
`mg_mgr_poll()` is called, and called if expired.
<span class="badge bg-danger">NOTE: </span> Make sure that the timer
interval is equal or more to the `mg_mgr_poll()` timeout.
Parameters:
- `mgr` - Pointer to `mg_mgr` event manager structure
- `ms` - An interval in milliseconds
- `flags` - Timer flags bitmask, `MG_TIMER_REPEAT` and `MG_TIMER_RUN_NOW`
- `fn` - Function to invoke
- `fn_data` - Function argument
Small fix to mg_timer_add() documentation The return value was not documented.
2022-05-27 04:43:56 +08:00
Return value: Pointer to created timer
Fix #1520 - move state to struct mg_mgr
2022-04-12 21:14:55 +08:00
Usage example:
```c
void timer_fn(void *data) {
// ...
}
mg_timer_add(mgr, 1000, MG_TIMER_REPEAT, timer_fn, NULL);
```
More docs
2020-12-09 00:26:17 +08:00
### struct mg\_timer
```c
struct mg_timer {
Use uint64_t for uptime in millis, not int64_t
2022-04-07 20:50:25 +08:00
uint64_t period_ms; // Timer period in milliseconds
uint64_t expire; // Expiration timestamp in milliseconds
Use int64_t for timers and mg_millis()
2021-12-22 05:50:18 +08:00
unsigned flags; // Possible flags values below
Address #1551 - better timers handling
2022-05-15 21:29:34 +08:00
#define MG_TIMER_ONCE 0 // Call function once
#define MG_TIMER_REPEAT 1 // Call function periodically
Use int64_t for timers and mg_millis()
2021-12-22 05:50:18 +08:00
#define MG_TIMER_RUN_NOW 2 // Call immediately when timer is set
More docs
2020-12-09 00:26:17 +08:00
void (*fn)(void *); // Function to call
Fixed typos
2021-03-11 21:01:45 +08:00
void *arg; // Function argument
Address #1551 - better timers handling
2022-05-15 21:29:34 +08:00
struct mg_timer *next; // Linkage
More docs
2020-12-09 00:26:17 +08:00
};
```
Docs nits
2021-08-22 17:51:40 +08:00
Timer structure. Describes a software timer. Timer granularity is the same
as the `mg_mgr_poll()` timeout argument in the main event loop.
More docs
2020-12-09 00:26:17 +08:00
### mg\_timer\_init()
```c
Fix #1520 - move state to struct mg_mgr
2022-04-12 21:14:55 +08:00
void mg_timer_init(struct mg_timer **head,
struct mg_timer *t, uint64_t period_ms, unsigned flags,
Update docs
2021-09-15 14:43:24 +08:00
void (*fn)(void *), void *fn_data);
More docs
2020-12-09 00:26:17 +08:00
```
Setup a timer.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Fix #1520 - move state to struct mg_mgr
2022-04-12 21:14:55 +08:00
- `head` - Pointer to `mg_timer` list head
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `t` - Pointer to `mg_timer` that should be initialized
- `ms` - An interval in milliseconds
- `flags` - Timer flags bitmask, `MG_TIMER_REPEAT` and `MG_TIMER_RUN_NOW`
- `fn` - Function to invoke
- `fn_data` - Function argument
More docs
2020-12-09 00:26:17 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
More docs
2020-12-09 00:26:17 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
void timer_fn(void *data) {
// ...
}
Fix #1520 - move state to struct mg_mgr
2022-04-12 21:14:55 +08:00
struct mg_timer timer, *head = NULL;
mg_timer_init(&head, &timer, 1000, MG_TIMER_REPEAT, timer_fn, NULL);
More docs
2020-12-09 00:26:17 +08:00
```
### mg\_timer\_free()
```c
Fix #1520 - move state to struct mg_mgr
2022-04-12 21:14:55 +08:00
void mg_timer_free(struct mg_timer **head, struct mg_timer *t);
More docs
2020-12-09 00:26:17 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
Free timer, remove it from the internal timers list.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Fix #1520 - move state to struct mg_mgr
2022-04-12 21:14:55 +08:00
- `head` - Pointer to `mg_timer` list head
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `t` - Timer to free
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
struct mg_timer timer;
// ...
mg_timer_free(&timer);
```
More docs
2020-12-09 00:26:17 +08:00
### mg\_timer\_poll()
```c
Fix #1520 - move state to struct mg_mgr
2022-04-12 21:14:55 +08:00
void mg_timer_poll(struct mg_timer **head, uint64_t uptime_ms);
More docs
2020-12-09 00:26:17 +08:00
```
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Traverse list of timers and call them if current timestamp `uptime_ms` is
More docs
2020-12-09 00:26:17 +08:00
past the timer's expiration time.
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Note, that `mg_mgr_poll` function internally calls `mg_timer_poll`; therefore,
Update docs
2021-09-15 14:43:24 +08:00
in most cases it is unnecessary to call it explicitly.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Fix #1520 - move state to struct mg_mgr
2022-04-12 21:14:55 +08:00
- `head` - Pointer to `mg_timer` list head
Add params and retvals
2021-09-15 20:37:57 +08:00
- `uptime_ms` - current timestamp
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
Use uint64_t for uptime in millis, not int64_t
2022-04-07 20:50:25 +08:00
mg_timer_poll(mg_millis());
Update docs
2021-09-15 14:43:24 +08:00
```
## Time
Update docs
2021-08-28 15:46:01 +08:00
### mg\_millis()
```c
Use int64_t for timers and mg_millis()
2021-12-22 05:50:18 +08:00
int64_t mg_millis(void);
Update docs
2021-08-28 15:46:01 +08:00
```
Return current uptime in milliseconds.
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Parameters: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Current uptime
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
Use int64_t for timers and mg_millis()
2021-12-22 05:50:18 +08:00
int64_t uptime = mg_millis();
Update docs
2021-09-15 14:43:24 +08:00
```
Update docs
2021-08-28 15:46:01 +08:00
mg_comma -> mg_commalist
2021-08-28 13:54:56 +08:00
## String
Update docs
2021-11-05 07:07:47 +08:00
### struct mg\_str
mg_comma -> mg_commalist
2021-08-28 13:54:56 +08:00
Update docs
2021-11-05 07:07:47 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str {
const char *ptr; // Pointer to string data
size_t len; // String len
};
```
mg_comma -> mg_commalist
2021-08-28 13:54:56 +08:00
Update docs
2021-11-05 07:07:47 +08:00
This structure represent an arbitrary chunk of memory, not necessarily
zero-terminated. This is a "mongoose string", and it gets used extensively
in the codebase instead of C zero-terminated strings.
For example, when an HTTP request is received, Mongoose created a
Fix links and typos
2021-11-16 20:30:40 +08:00
`struct mg_http_message` which has a collection of `struct mg_str` pointing
Update docs
2021-11-05 07:07:47 +08:00
to request method, URI, headers, and so on. This way, Mongoose avoids
any heap allocations and does not modify the received buffer - instead, it
uses `struct mg_str` to describe various parts of HTTP request.
Same goes with many other cases.
NOTE: since `ptr` is not necessarily zero-terminated, do not use libc string
Fix links and typos
2021-11-16 20:30:40 +08:00
functions against it - like `strlen()` or `sscanf()`.
mg_comma -> mg_commalist
2021-08-28 13:54:56 +08:00
Update docs
2021-09-15 14:43:24 +08:00
### mg\_str()
mg_comma -> mg_commalist
2021-08-28 13:54:56 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str mg_str(const char *s)
mg_comma -> mg_commalist
2021-08-28 13:54:56 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
Create Mongoose string from NULL-terminated C-string. This function doesn't
duplicate provided string, and stores pointer within created `mg_str` structure.
Note, that is you have problems in C++ (constructor shadowing), there is `mg_str_s`
synonym for this function.
mg_comma -> mg_commalist
2021-08-28 13:54:56 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `s` - Pointer to NULL-terminated string to store in created mg_str
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Created Mongoose string
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
mg_comma -> mg_commalist
2021-08-28 13:54:56 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str str = mg_str("Hello, world!);
mg_comma -> mg_commalist
2021-08-28 13:54:56 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
### mg\_str\_n()
More docs
2020-12-09 00:26:17 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str mg_str_n(const char *s, size_t n);
More docs
2020-12-09 00:26:17 +08:00
```
Fix links and typos
2021-11-16 20:30:40 +08:00
Create Mongoose string from C-string `s` (can be non-NULL terminated, length is
specified in `n`). Note: This function doesn't duplicate provided string,
but stores pointer within created `mg_str` structure.
More docs
2020-12-09 00:26:17 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `s` - Pointer to string to store in created `mg_str`
Fix links and typos
2021-11-16 20:30:40 +08:00
- `n` - String length
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Created Mongoose string
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
More docs
2020-12-09 00:26:17 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str str = mg_str_n("hi", 2);
More docs
2020-12-09 00:26:17 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
### mg\_casecmp()
More docs
2020-12-09 00:26:17 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
int mg_casecmp(const char *s1, const char *s2);
More docs
2020-12-09 00:26:17 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
Case insensitive compare two NULL-terminated strings.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `s1`, `s2` - Pointers to strings to compare
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Zero if strings are equal, more than zero if first argument is greater then second, and less than zero otherwise
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
```c
if (mg_casecmp("hello", "HELLO") == 0) {
// Strings are equal
}
```
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
### mg\_ncasecmp()
More docs
2020-12-09 00:26:17 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
int mg_ncasecmp(const char *s1, const char *s2, size_t len);
More docs
2020-12-09 00:26:17 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
Case insensitive compare two C-strings, not more than `len` symbols or until meet `\0` symbol.
More docs
2020-12-09 00:26:17 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `s1`, `s2` - Pointers to strings to compare
- `len` - Maximum length to compare
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Zero if strings are equal, more than zero if first argument is
greater then second, and less than zero otherwise
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
More docs
2020-12-09 00:26:17 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
if (mg_ncasecmp("hello1", "HELLO2", 5) == 0) {
// Strings are equal
}
More docs
2020-12-09 00:26:17 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
### mg\_vcmp()
More docs
2020-12-09 00:26:17 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
int mg_vcmp(const struct mg_str *s1, const char *s2);
More docs
2020-12-09 00:26:17 +08:00
```
Fix links and typos
2021-11-16 20:30:40 +08:00
Compare mongoose string and C-string.
More docs
2020-12-09 00:26:17 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `s1` - Pointer to Mongoose string to compare
- `s2` - Pointer to C-string to compare
Add params and retvals
2021-09-15 20:37:57 +08:00
Return value: 0 if strings are equal, more than zero if first argument is
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
greater then second, and less than zero otherwise
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
More docs
2020-12-09 00:26:17 +08:00
docs update
2021-08-29 03:27:55 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str str = mg_str("hello");
if (mg_vcmp(str, "hello") == 0) {
// Strings are equal
}
More docs
2020-12-09 00:26:17 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
### mg\_vcasecmp()
More docs
2020-12-09 00:26:17 +08:00
docs update
2021-08-29 03:27:55 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
int mg_vcasecmp(const struct mg_str *str1, const char *str2);
More docs
2020-12-09 00:26:17 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
Case insensitive compare mongoose string and C-string.
More docs
2020-12-09 00:26:17 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `str1` - Mongoose string to compare
- `str2` - C-string to compare
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Zero if strings are equal, more than zero if first argument is
greater then second, and less than zero otherwise
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
More docs
2020-12-09 00:26:17 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str str = mg_str("hello");
if (mg_vcasecmp(str, "HELLO") == 0) {
// Strings are equal
}
More docs
2020-12-09 00:26:17 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
### mg\_strcmp()
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
Update docs
2021-09-15 14:43:24 +08:00
```c
int mg_strcmp(const struct mg_str str1, const struct mg_str str2);
```
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
Fix links and typos
2021-11-16 20:30:40 +08:00
Compare two mongoose strings.
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `str1`, `str2` - Pointers to Mongoose strings to compare
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Zero if strings are equal, more than zero if first argument is
greater then second, and less than zero otherwise
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str str1 = mg_str("hello");
struct mg_str str2 = mg_str("hello");
if (mg_strcmp(str1, str2) == 0) {
// Strings are equal
}
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
### mg\_strdup()
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str mg_strdup(const struct mg_str s);
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
Duplicate provided string. Return new string or `MG_NULL_STR` on error.
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Note: This function allocates memory for returned string. You may need to free it using `free` function.
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `s` - Mongoose string to duplicate
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Duplicated string
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str str1 = mg_str("hello");
struct mg_str str2 = mg_strdup(str1);
//...
Update README.md
2022-12-06 03:24:28 +08:00
free((void *)str2.ptr);
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
### mg\_strstr()
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
const char *mg_strstr(const struct mg_str haystack, const struct mg_str needle)
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Search for `needle` substring in `haystack` string.
Parameters:
- `haystack` - Mongoose sting to search for substring
- `needle` - Mongoose string to search
Return value: pointer to `needle`
Update docs
2021-09-15 14:43:24 +08:00
occurrence within `haystack` or `NULL` if not found.
Usage example:
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
Update docs
2021-09-15 14:43:24 +08:00
```c
struct mg_str str = mg_str("Hello, world");
struct mg_str sub_str = mg_str("world");
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
Update docs
2021-09-15 14:43:24 +08:00
if (mg_strstr(str, sub_str) != NULL) {
// Found
}
```
### mg\_strstrip()
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str mg_strstrip(struct mg_str s)
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
Remove heading and trailing whitespace from mongoose string `s`.
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
Fix links and typos
2021-11-16 20:30:40 +08:00
Parameters:
Add params and retvals
2021-09-15 20:37:57 +08:00
- `s` - Mongoose string for trimming
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Input string
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
Update docs
2021-09-15 14:43:24 +08:00
```c
struct mg_str str = mg_strstrip(mg_str(" Hello, world "));
if (mg_vcmp(str, "Hello, world") == 0) {
// Strings are equal
}
```
Handle #1459 - deprecate mg_globmatch, introduce mg_match()
2022-01-29 19:03:54 +08:00
### mg\_match()
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
```c
Handle #1459 - deprecate mg_globmatch, introduce mg_match()
2022-01-29 19:03:54 +08:00
bool mg_match(struct mg_str str, struct mg_str pattern, struct mg_str *caps);
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
```
Handle #1459 - deprecate mg_globmatch, introduce mg_match()
2022-01-29 19:03:54 +08:00
Check if string `str` matches glob pattern `pattern`, and optionally capture
wildcards into the provided array `caps`.
Update docs
2022-01-29 19:11:22 +08:00
<span class="badge bg-danger">NOTE: </span> If `caps` is not NULL, then the
Handle #1459 - deprecate mg_globmatch, introduce mg_match()
2022-01-29 19:03:54 +08:00
`caps` array size must be at least the number of wildcard symbols in `pattern`
Update docs
2022-01-29 19:11:22 +08:00
plus 1. The last cap will be initialized to an empty string.
Update docs
2022-01-29 19:12:31 +08:00
Update docs
2021-09-15 14:43:24 +08:00
The glob pattern matching rules are as follows:
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
Update docs
2021-09-15 14:43:24 +08:00
- `?` matches any single character
- `*` matches zero or more characters except `/`
- `#` matches zero or more characters
- any other character matches itself
mg_iobuf_delete -> mg_iobuf_del
2021-08-28 14:16:38 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Handle #1459 - deprecate mg_globmatch, introduce mg_match()
2022-01-29 19:03:54 +08:00
- `str` - a string to match
- `pattern` - a pattern to match against
- `caps` - an optional array of captures for wildcard symbols `?`, `*`, '#'
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: `true` if matches, `false` otherwise
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-08-28 15:46:01 +08:00
```c
Handle #1459 - deprecate mg_globmatch, introduce mg_match()
2022-01-29 19:03:54 +08:00
// Assume that hm->uri holds /foo/bar. Then we can match the requested URI:
Update docs
2022-01-29 19:11:22 +08:00
struct mg_str caps[3]; // Two wildcard symbols '*' plus 1
Update README.md added missing parameter in sample code of `mg_match`.
2022-05-29 21:52:56 +08:00
if (mg_match(hm->uri, mg_str("/*/*"), caps)) {
Handle #1459 - deprecate mg_globmatch, introduce mg_match()
2022-01-29 19:03:54 +08:00
// caps[0] holds `foo`, caps[1] holds `bar`.
Update docs
2021-09-15 14:43:24 +08:00
}
```
Update docs
2021-08-28 15:46:01 +08:00
Update docs
2021-09-15 14:43:24 +08:00
### mg\_commalist()
Update docs
2021-08-28 15:46:01 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
bool mg_commalist(struct mg_str *s, struct mg_str *k, struct mg_str *v);
More docs
2020-12-09 00:26:17 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
Parse string `s`, which is a comma-separated list of entries. An entry could be
either an arbitrary string, which gets stored in `v`, or a `KEY=VALUE` which
gets stored in `k` and `v` respectively.
Update docs
2021-08-28 15:46:01 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
IMPORTANT: This function modifies `s` by pointing to the next entry.
More docs
2020-12-09 00:26:17 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `s` - String to search for entry
- `k` - Pointer to `mg_str` to receive entry key
- `v` - Pointer to `mg_str` to receive entry value
Add params and retvals
2021-09-15 20:37:57 +08:00
Return value: `true` if entry is found, `false` otherwise
Update docs
2021-08-28 15:46:01 +08:00
Usage example:
More docs
2020-12-09 00:26:17 +08:00
```c
Update docs
2021-09-15 14:43:24 +08:00
struct mg_str k, v, s = mg_str("a=333,b=777");
while (mg_commalist(&s, &k, &v)) // This loop output:
printf("[%.*s] set to [%.*s]\n", // [a] set to [333]
(int) k.len, k.ptr, (int) v.len, v.ptr); // [b] set to [777]
More docs
2020-12-09 00:26:17 +08:00
```
Update docs
2022-06-08 18:01:30 +08:00
<img src="images/mg_commalist.svg" alt="Function mg_commalist()" />
Update docs
2021-09-15 14:43:24 +08:00
### mg\_hex()
```c
char *mg_hex(const void *buf, size_t len, char *dst);
```
Hex-encode binary data `buf`, `len` into a buffer `dst` and nul-terminate it.
The output buffer must be at least 2 x `len` + 1 big.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `buf` - Data to hex-encode
- `len` - Data length
- `dst` - Pointer to output buffer
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: `dst` pointer. The encoded characters are lowercase
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
char data[] = "\x1\x2\x3";
char buf[sizeof(data)*2];
char *hex = mg_hex(data, sizeof(data) - 1, buf);
LOG(LL_INFO, ("%s", hex)); // Output "010203";
free(hex);
```
### mg\_unhex()
```c
void mg_unhex(const char *buf, size_t len, unsigned char *to);
```
Hex-decode string `buf`, `len` into a buffer `to`. The `to` buffer should be
at least `lsn` / 2 big.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `buf` - Data to hex-decode
- `len` - Data length
- `to` - Pointer to output buffer
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
char data[] = "010203";
char *buf[sizeof(data)/2];
char *hex = mg_unhex(data, sizeof(data) - 1, buf); // buf is now [1,2,3]
free(hex);
```
### mg\_unhexn()
```c
unsigned long mg_unhexn(const char *s, size_t len);
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Parse `len` characters of the hex-encoded string `s`.
Update docs
2021-09-15 14:43:24 +08:00
The maximum value of `len` is the width of the `long` x 2, for example
on 32-bit platforms it is 8.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `s` - String to parse
- `len` - String length
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Return parsed value
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
char data[] = "010203";
char *buf[sizeof(data)/2];
unsigned long val = mg_unhex(data, sizeof(data) - 1); // val is now 123
```
Add mg_remove_double_dots(), hide mg_http_upload()
2022-07-01 03:27:43 +08:00
### mg\_remove\_double\_dots()
```c
char *mg_remove_double_dots(char *s);
```
Modify string `s` in place by removing double dots from it. Used to
sanitize file names or URIs received from the network.
Parameters:
- `s` - String to sanitise
Return value: the `s` pointer
Usage example:
```c
char data[] = "../../a.txt";
mg_remove_double_dots(data); // data is /a.txt
```
Using mg_snprintf() everywhere
2022-02-11 01:11:03 +08:00
### mg\_snprintf(), mg\_vsnprintf()
Update docs
2021-09-15 14:43:24 +08:00
```c
Using mg_snprintf() everywhere
2022-02-11 01:11:03 +08:00
size_t mg_snprintf(char *buf, size_t len, const char *fmt, ...);
size_t mg_vsnprintf(char *buf, size_t len, const char *fmt, va_list ap);
Update docs
2021-09-15 14:43:24 +08:00
```
Using mg_snprintf() everywhere
2022-02-11 01:11:03 +08:00
Print formatted string into a string buffer, just like `snprintf()`
standard function does, but in a predictable way that does not depend on
the C library or the build environment. The return value can be larger
than the buffer length `len`, in which case the overflow bytes are not printed.
Introduce %Q format specifier, rework device dashboard
2022-06-09 04:44:01 +08:00
Mongoose library is often used to exchange data in JSON format, therefore a
Add %V and %H specifiers for mg_snrpintf()
2022-06-22 20:15:52 +08:00
non-standard `%Q`, `%V`, `%H` specifiers for formatting JSON strings is also supported.
Update docs
2021-09-15 14:43:24 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `buf` - Pointer to pointer to output buffer
Using mg_snprintf() everywhere
2022-02-11 01:11:03 +08:00
- `len` - Buffer size
Add params and retvals
2021-09-15 20:37:57 +08:00
- `fmt` - printf-like format string
Using mg_snprintf() everywhere
2022-02-11 01:11:03 +08:00
Supported format specifiers:
- `hhd`, `hd`, `d`, `ld`, `lld` - for `char`, `short`, `int`, `long`, `int64_t`
- `hhu`, `hu`, `u`, `lu`, `llu` - same but for unsigned variants
- `hhx`, `hx`, `x`, `lx`, `llx` - same, unsigned and hex output
Add %V and %H specifiers for mg_snrpintf()
2022-06-22 20:15:52 +08:00
- `s` - expect `char *`
Remove dangerous mg_pfn_realloc(). Add %q printf specifier
2022-08-11 01:27:58 +08:00
- `q` - expect `char *`, outputs JSON-escaped string (extension)
Add %V and %H specifiers for mg_snrpintf()
2022-06-22 20:15:52 +08:00
- `Q` - expect `char *`, outputs double-quoted JSON-escaped string (extension)
- `H` - expect `int`, `void *`, outputs double-quoted hex string (extension)
Fix #1888: add %I *printf specifier for IP address. Remove mg_ntoa, mg_straddr
2022-12-03 22:08:10 +08:00
- `I` - expect `int` (4 or 6), `void *`, outputs IP address (extension)
Use %I in mip.c Add %A to print hw address and use it in mip.c Fix some debug data
2022-12-07 00:44:31 +08:00
- `A` - expect `void *`, outputs hardware address (extension)
Add %V and %H specifiers for mg_snrpintf()
2022-06-22 20:15:52 +08:00
- `V` - expect `int`, `void *`, outputs double-quoted base64 string (extension)
Change argument of %M handler to mg_pfn_t plus some cosmetic changes
2022-08-09 03:01:04 +08:00
- `M` - expect `mg_pfn_t`, calls another print function (extension)
Add %V and %H specifiers for mg_snrpintf()
2022-06-22 20:15:52 +08:00
- `g`, `f` - expect `double`
- `c` - expect `char`
- `%` - expect `%` character itself
- `p` - expect any pointer, prints `0x.....` hex value
Using mg_snprintf() everywhere
2022-02-11 01:11:03 +08:00
- `%X.Y` - optional width and precision modifiers
- `%.*` - optional precision modifier specified as `int` argument
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Number of bytes printed
Add params and retvals
2021-09-15 20:37:57 +08:00
Add json docs
2022-06-10 20:01:52 +08:00
Sending JSON HTTP response:
```c
mg_http_reply(c, 200, "Content-Type: application/json\r\n",
"{%Q: %g}", "value", 1.2345);
```
Example of using more complex format strings:
Update docs
2021-09-15 14:43:24 +08:00
Using mg_snprintf() everywhere
2022-02-11 01:11:03 +08:00
```c
mg_snprintf(buf, sizeof(buf), "%lld", (int64_t) 123); // 123
mg_snprintf(buf, sizeof(buf), "%.2s", "abcdef"); // ab
mg_snprintf(buf, sizeof(buf), "%.*s", 2, "abcdef"); // ab
mg_snprintf(buf, sizeof(buf), "%05x", 123); // 00123
Handle minus in the fmt spec
2022-02-11 19:02:06 +08:00
mg_snprintf(buf, sizeof(buf), "%%-%3s", "a"); // %- a
Add %g support to mg_snprintf()
2022-06-10 16:38:36 +08:00
mg_snprintf(buf, sizeof(buf), "hi, %Q", "a"); // hi, "a"
mg_snprintf(buf, sizeof(buf), "r: %M, %d", f,1,2,7); // r: 3, 7
Fix #1888: add %I *printf specifier for IP address. Remove mg_ntoa, mg_straddr
2022-12-03 22:08:10 +08:00
mg_snprintf(buf, sizeof(buf), "%I", 4, "abcd"); // 97.98.99.100
Use %I in mip.c Add %A to print hw address and use it in mip.c Fix some debug data
2022-12-07 00:44:31 +08:00
mg_snprintf(buf, sizeof(buf), "%A", "abcdef"); // 61:62:63:64:65:66
Add %g support to mg_snprintf()
2022-06-10 16:38:36 +08:00
// Printing sub-function for %M specifier. Grabs two int parameters
added mg_rprintf(), updated doc to new %M API
2022-07-08 01:15:55 +08:00
size_t f(void (*out)(char, void *), void *ptr, va_list *ap) {
Add %g support to mg_snprintf()
2022-06-10 16:38:36 +08:00
int a = va_arg(*ap, int);
added mg_rprintf(), updated doc to new %M API
2022-07-08 01:15:55 +08:00
int b = va_arg(*ap, int);
mg_*rprintf -> mg_*xprintf
2022-08-14 03:34:20 +08:00
return mg_xprintf(out, ptr, "%d", a + b);
Add %g support to mg_snprintf()
2022-06-10 16:38:36 +08:00
}
```
### mg\_mprintf(), mg\_vmprintf()
```c
char *mg_mprintf(const char *fmt, ...);
Get rid of mg_*asprintf
2022-08-13 22:37:55 +08:00
char *mg_vmprintf(const char *fmt, va_list *ap);
Add %g support to mg_snprintf()
2022-06-10 16:38:36 +08:00
```
Print message into an allocated memory buffer. Caller must free the result.
Parameters:
- `fmt` - printf-like format string
Return value: allocated memory buffer
Usage example:
```c
char *msg = mg_mprintf("Double quoted string: %Q!", "hi");
free(msg);
Update docs
2021-09-15 14:43:24 +08:00
```
Fix docs, nits to freertos includes
2022-08-15 06:46:33 +08:00
### mg\_xprintf(), mg\_vxprintf()
added mg_rprintf(), updated doc to new %M API
2022-07-08 01:15:55 +08:00
```c
mg_*rprintf -> mg_*xprintf
2022-08-14 03:34:20 +08:00
size_t mg_xprintf(void (*out)(char, void *), void *param, const char *fmt, ...);
size_t mg_vxprintf(void (*out)(char, void *), void *param, const char *fmt,
added mg_rprintf(), updated doc to new %M API
2022-07-08 01:15:55 +08:00
va_list *ap);
```
Print message using a specified character output function
Parameters:
- `out` - function to be used for printing chars
- `param` - argument to be passed to `out`
- `fmt` - printf-like format string
Return value: Number of bytes printed
Usage example:
```c
void myfn(char c, void *p);
mg_*rprintf -> mg_*xprintf
2022-08-14 03:34:20 +08:00
size_t len = mg_xprintf(myfn, myfn_p, "Double quoted string: %Q!", "hi");
added mg_rprintf(), updated doc to new %M API
2022-07-08 01:15:55 +08:00
```
Add pfn functions docs Add RPC docs
2022-08-05 04:04:11 +08:00
### mg\_pfn\_iobuf()
```c
void mg_pfn_iobuf(char ch, void *param);
```
Print a character to a [Generic IO buffer](#struct-mg_iobuf)
Parameters:
- `ch` - char to be printed
Remove dangerous mg_pfn_realloc(). Add %q printf specifier
2022-08-11 01:27:58 +08:00
- `param` - must be `struct mg_iobuf *`
Add pfn functions docs Add RPC docs
2022-08-05 04:04:11 +08:00
Usage example:
```c
mg_*rprintf -> mg_*xprintf
2022-08-14 03:34:20 +08:00
mg_xprintf(mg_pfn_iobuf, &c->send, "hi!"); // Append to the output buffer
Add pfn functions docs Add RPC docs
2022-08-05 04:04:11 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
### mg\_to64()
```c
int64_t mg_to64(struct mg_str str);
Fix #1521 - add mg_tou64()
2022-04-12 17:20:43 +08:00
uint64_t mg_tou64(struct mg_str str);
Update docs
2021-09-15 14:43:24 +08:00
```
Parse 64-bit integer value held by string `s`.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `str` - String to parse
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Parsed value
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
int64_t val = mg_to64(mg_str("123")); // Val is now 123
```
### mg\_aton()
```c
bool mg_aton(struct mg_str str, struct mg_addr *addr);
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Parse IP address held by `str` and store it in `addr`.
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `str` - String to parse, for example `1.2.3.4`, `[::1]`, `01:02::03`
- `addr` - Pointer to `mg_addr` string to receive parsed value
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: `true` on success, `false` otherwise
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
struct mg_addr addr;
if (mg_aton(mg_str("127.0.0.1"), &addr)) {
// addr is now binary representation of 127.0.0.1 IP address
}
```
Add json docs
2022-06-10 20:01:52 +08:00
## JSON
Add pfn functions docs Add RPC docs
2022-08-05 04:04:11 +08:00
Note that Mongoose's printing functions support non-standard format specifiers `%Q` and `%M`,
More json docs
2022-06-13 22:04:52 +08:00
which allow to print JSON strings easily:
```c
char *json = mg_mprintf("{%Q:%d}", "value", 123); // {"value":123}
free(json);
```
Therefore, for a full JSON support, a set of parsing functions is required -
which is described below.
Add json docs
2022-06-10 20:01:52 +08:00
### mg\_json\_get()
```c
enum { MG_JSON_TOO_DEEP = -1, MG_JSON_INVALID = -2, MG_JSON_NOT_FOUND = -3 };
Refactor JSON and RPC API
2022-07-30 14:55:26 +08:00
int mg_json_get(struct mg_str json, const char *path, int *toklen);
Add json docs
2022-06-10 20:01:52 +08:00
```
Refactor JSON and RPC API
2022-07-30 14:55:26 +08:00
Parse JSON string `json` and return the offset of the element
specified by the JSON `path`. The length of the element is stored
Add json docs
2022-06-10 20:01:52 +08:00
in the `toklen`.
Parameters:
Refactor JSON and RPC API
2022-07-30 14:55:26 +08:00
- `json` - a string containing valid JSON
- `path` - a JSON path. Must start with `$`, e.g. `$.user`
- `toklen` - a pointer that receives element's length, can be NULL
Add json docs
2022-06-10 20:01:52 +08:00
Return value: offset of the element, or negative `MG_JSON_*` on error.
Usage example:
```c
More json docs
2022-06-13 22:04:52 +08:00
// Create a json string: { "a": 1, "b": [2, 3] }
char *buf = mg_mprintf("{ %Q: %d, %Q: [%d, %d] }", "a", 1, "b", 2, 3);
Refactor JSON and RPC API
2022-07-30 14:55:26 +08:00
struct mg_str json = mg_str(buf);
int offset, length;
Add json docs
2022-06-10 20:01:52 +08:00
// Lookup "$", which is the whole JSON. Can be used for validation
Refactor JSON and RPC API
2022-07-30 14:55:26 +08:00
offset = mg_json_get(json, "$", &length); // offset = 0, length = 23
Add json docs
2022-06-10 20:01:52 +08:00
// Lookup attribute "a". Point to value "1"
Refactor JSON and RPC API
2022-07-30 14:55:26 +08:00
offset = mg_json_get(json, "$.a", &length); // offset = 7, length = 1
Add json docs
2022-06-10 20:01:52 +08:00
// Lookup attribute "b". Point to array [2, 3]
Refactor JSON and RPC API
2022-07-30 14:55:26 +08:00
offset = mg_json_get(json, "$.b", &length); // offset = 15, length = 6
Add json docs
2022-06-10 20:01:52 +08:00
// Lookup attribute "b[1]". Point to value "3"
Refactor JSON and RPC API
2022-07-30 14:55:26 +08:00
offset = mg_json_get(json, "$.b[1]", &length); // offset = 19, length = 1
More json docs
2022-06-13 22:04:52 +08:00
free(buf);
Add json docs
2022-06-10 20:01:52 +08:00
```
### mg\_json\_get\_num()
```c
bool mg_json_get_num(struct mg_str json, const char *path, double *v);
```
Fetch numeric (double) value from the json string `json` at JSON path
`path` into a placeholder `v`. Return true if successful.
Parameters:
- `json` - a string containing valid JSON
- `path` - a JSON path. Must start with `$`
- `v` - a placeholder for value
Return value: true on success, false on error
Usage example:
```c
double d = 0.0;
mg_json_get_num(mg_str("[1,2,3]", "$[1]", &d)); // d contains 2
mg_json_get_num(mg_str("{\"a\":1.23}", "$.a", &d)); // d contains 1.23
```
### mg\_json\_get\_bool()
```c
fix JSON docs
2022-06-15 01:19:25 +08:00
bool mg_json_get_bool(struct mg_str json, const char *path, bool *v);
Add json docs
2022-06-10 20:01:52 +08:00
```
Fetch boolean (bool) value from the json string `json` at JSON path
`path` into a placeholder `v`. Return true if successful.
Parameters:
- `json` - a string containing valid JSON
- `path` - a JSON path. Must start with `$`
- `v` - a placeholder for value
Return value: true on success, false on error
Usage example:
```c
bool b = false;
fix JSON docs
2022-06-15 01:19:25 +08:00
mg_json_get_bool(mg_str("[123]", "$[0]", &b)); // Error. b remains to be false
mg_json_get_bool(mg_str("[true]", "$[0]", &b)); // b is true
Add json docs
2022-06-10 20:01:52 +08:00
```
Add mg_json_get_long
2022-07-01 03:03:02 +08:00
### mg\_json\_get\_long()
```c
Nits
2022-07-02 00:28:06 +08:00
long mg_json_get_long(struct mg_str json, const char *path, long default_val);
Add mg_json_get_long
2022-07-01 03:03:02 +08:00
```
Fetch integer numeric (long) value from the json string `json` at JSON path
`path`. Return it if found, or `default_val` if not found.
Parameters:
- `json` - a string containing valid JSON
- `path` - a JSON path. Must start with `$`
- `default_val` - a default value for the failure case
Return value: found value, or `default_val` value
Usage example:
```c
Nits
2022-07-02 00:28:06 +08:00
long a = mg_json_get_long(mg_str("[123]", "$a", -1)); // a = -1
long b = mg_json_get_long(mg_str("[123]", "$[0]", -1)); // b = 123
Add mg_json_get_long
2022-07-01 03:03:02 +08:00
```
Add json docs
2022-06-10 20:01:52 +08:00
### mg\_json\_get\_str()
```c
fix JSON docs
2022-06-15 01:19:25 +08:00
char *mg_json_get_str(struct mg_str json, const char *path);
Add json docs
2022-06-10 20:01:52 +08:00
```
Fetch string value from the json string `json` at JSON path
fix JSON docs
2022-06-15 01:19:25 +08:00
`path`. If found, a string is allocated using `calloc()`,
un-escaped, and returned to the caller. It is the caller's responsibility to
Add json docs
2022-06-10 20:01:52 +08:00
`free()` the returned string.
Parameters:
- `json` - a string containing valid JSON
- `path` - a JSON path. Must start with `$`
fix JSON docs
2022-06-15 01:19:25 +08:00
Return value: non-NULL on success, NULL on error
Add json docs
2022-06-10 20:01:52 +08:00
Usage example:
```c
Docs nitpick
2022-06-10 22:00:34 +08:00
struct mg_str json = mg_str("{\"a\": \"hi\"}"); // json = {"a": "hi"}
char *str = mg_json_get_str(json, "$.a"); // str = "hi"
Add json docs
2022-06-10 20:01:52 +08:00
free(str);
```
Add mg_json_get_hex(), mg_json_get_b64()
2022-06-22 23:28:22 +08:00
### mg\_json\_get\_hex()
```c
char *mg_json_get_hex(struct mg_str json, const char *path, int *len);
```
Fetch hex-encoded buffer from the json string `json` at JSON path
`path`. If found, a buffer is allocated using `calloc()`, decoded,
and returned to the caller. It is the caller's responsibility to
`free()` the returned string. Returned buffer is 0-terminated.
Parameters:
- `json` - a string containing valid JSON
- `path` - a JSON path. Must start with `$`
- `len` - a pointer that receives decoded length. Can be NULL
Return value: non-NULL on success, NULL on error
Usage example:
```c
struct mg_str json = mg_str("{\"a\": \"6869\"}"); // json = {"a": "6869"}
char *str = mg_json_get_hex(json, "$.a", NULL); // str = "hi"
free(str);
```
### mg\_json\_get\_b64()
```c
char *mg_json_get_b4(struct mg_str json, const char *path, int *len);
```
Fetch base64-encoded buffer from the json string `json` at JSON path
`path`. If found, a buffer is allocated using `calloc()`, decoded,
and returned to the caller. It is the caller's responsibility to
`free()` the returned string. Returned buffer is 0-terminated.
Parameters:
- `json` - a string containing valid JSON
- `path` - a JSON path. Must start with `$`
- `len` - a pointer that receives decoded length. Can be NULL
Return value: non-NULL on success, NULL on error
Usage example:
```c
struct mg_str json = mg_str("{\"a\": \"YWJj\"}"); // json = {"a": "YWJj"}
char *str = mg_json_get_b64(json, "$.a", NULL); // str = "abc"
free(str);
```
Add pfn functions docs Add RPC docs
2022-08-05 04:04:11 +08:00
## RPC
Mongoose includes a set of functions to ease server-side processing by means of RPC methods.
### struct mg\_rpc
The RPC method handler structure. Each method has an entry in a linked list, each entry points to a string describing the pattern that will invoke it and the function that will be called to satisfy the method invocation, with a proper function argument.
```c
struct mg_rpc {
struct mg_rpc *next; // Next in list
struct mg_str method; // Method pattern
void (*fn)(struct mg_rpc_req *); // Handler function
void *fn_data; // Handler function argument
};
```
### struct mg\_rpc\_req
The RPC request descriptor. An invoked method receives a descriptor containing the request, and a pointer to a function to be called to print the output response, with a proper function argument; e.g.: [mg_pfn_realloc()](#mg_pfn_realloc) or [mg_pfn_iobuf()](#mg_pfn_iobuf)
```c
struct mg_rpc_req {
struct mg_rpc **head; // RPC handlers list head
struct mg_rpc *rpc; // RPC handler being called
mg_pfn_t pfn; // Response printing function
void *pfn_data; // Response printing function data
void *req_data; // Arbitrary request data
struct mg_str frame; // Request, e.g. {"id":1,"method":"add","params":[1,2]}
};
```
### mg\_rpc\_add()
```c
void mg_rpc_add(struct mg_rpc **head, struct mg_str method_pattern,
void (*handler)(struct mg_rpc_req *), void *handler_data);
```
Add the method `method_pattern` to the list `head` of RPC methods. Invoking this method will call `handler` and pass `handler_data` to it with the request (as `r->fn_data` in the usage example below).
Parameters:
- `head` - the linked list pointer
- `method_pattern` - the name of the method
- `handler` - the RPC function performing the action for this method
- `handler_data` - Arbitrary function data
Let RPC handle responses too
2022-08-27 00:41:13 +08:00
<span class="badge bg-info">NOTE:</span>
if `method_pattern` is an empty string, this handler will be called to process
JSON-RPC responses. Handling responses might be necessary if the JSON requests
are initiated by both sides.
Add pfn functions docs Add RPC docs
2022-08-05 04:04:11 +08:00
Usage example:
```c
struct mg_rpc *s_rpc_head = NULL;
static void rpc_sum(struct mg_rpc_req *r) {
double a = 0.0, b = 0.0;
mg_json_get_num(r->frame, "$.params[0]", &a);
mg_json_get_num(r->frame, "$.params[1]", &b);
mg_rpc_ok(r, "%g", a + b);
}
static void rpc_mul(struct mg_rpc_req *r) {//...}
mg_rpc_add(&s_rpc_head, mg_str("sum"), rpc_sum, NULL);
mg_rpc_add(&s_rpc_head, mg_str("mul"), rpc_mul, NULL);
```
### mg\_rpc\_del()
```c
void mg_rpc_del(struct mg_rpc **head, void (*handler)(struct mg_rpc_req *));
```
Remove the method with RPC function handler `handler` from the list `head` of RPC methods.
Parameters:
- `head` - the linked list pointer
- `handler` - the RPC function performing the action for this method, use NULL to deallocate all
Usage example:
```c
struct mg_rpc *s_rpc_head = NULL;
// add methods
// ...
// Time to cleanup
mg_rpc_del(&s_rpc_head, rpc_mul); // Deallocate specific handler
mg_rpc_del(&s_rpc_head, NULL); // Deallocate all RPC handlers
```
### mg\_rpc\_process()
```c
void mg_rpc_process(struct mg_rpc_req *req);
```
Invoke the proper method for this request. If the requested method does not exist, `mg_rpc_err()` will be invoked and an error indication will be printed
Parameters:
- `req` - a request
Usage example:
```c
Update docs for mg_rpc_process()
2022-08-10 22:35:07 +08:00
struct mg_rpc *s_rpcs = NULL; // Empty RPC list head
mg_rpc_add(&s_rpcs, mg_str("rpc.list"), mg_rpc_list, NULL); // Add rpc.list
// ... add more RPC methods
Add pfn functions docs Add RPC docs
2022-08-05 04:04:11 +08:00
Update docs for mg_rpc_process()
2022-08-10 22:35:07 +08:00
// On request, process the incoming frame
struct mg_str req = mg_str("{\"id\":1,\"method\":\"sum\",\"params\":[1,2]}");
struct mg_iobuf io = {0, 0, 0, 512}; // Empty IO buf, with 512 realloc granularity
Add pfn functions docs Add RPC docs
2022-08-05 04:04:11 +08:00
struct mg_rpc_req r = {
Update docs for mg_rpc_process()
2022-08-10 22:35:07 +08:00
.head = &s_rpcs, // RPC list head
.rpc = NULL, // This will be set by mg_rpc_process()
.pfn = mg_pfn_iobuf, // Printing function: print into the io buffer
.pfn_data = &io, // Pass our io buffer as a parameter
.req_data = NULL, // No specific request data
.frame = req, // Specify incoming frame
Add pfn functions docs Add RPC docs
2022-08-05 04:04:11 +08:00
};
Update docs for mg_rpc_process()
2022-08-10 22:35:07 +08:00
mg_rpc_process(&r);
if (io.buf != NULL) printf("Response: %s\n", (char *) io.buf);
mg_iobuf_free(&io);
Add pfn functions docs Add RPC docs
2022-08-05 04:04:11 +08:00
```
### mg\_rpc\_ok(), mg\_rpc\_vok()
```c
void mg_rpc_ok(struct mg_rpc_req *, const char *fmt, ...);
void mg_rpc_vok(struct mg_rpc_req *, const char *fmt, va_list *ap);
```
Helper functions to print result frames
Parameters:
- `req` - a request
- `fmt` - printf-like format string
Usage example:
```c
static void rpc_sum(struct mg_rpc_req *r) {
double a = 0.0, b = 0.0;
mg_json_get_num(r->frame, "$.params[0]", &a);
mg_json_get_num(r->frame, "$.params[1]", &b);
mg_rpc_ok(r, "%g", a + b);
}
```
### mg\_rpc\_err(), mg\_rpc\_verr()
```c
void mg_rpc_err(struct mg_rpc_req *, int code, const char *fmt, ...);
void mg_rpc_verr(struct mg_rpc_req *, int code, const char *fmt, va_list *);
```
Helper functions to print error frames
Parameters:
- `req` - a request
- `fmt` - printf-like format string
Usage example:
```c
static void rpc_dosome(struct mg_rpc_req *r) {
...
mg_rpc_err(r, -32109, "\"%.*s not found\"", len, &r->frame.ptr[offset]);
}
```
### mg\_rpc\_list()
```c
void mg_rpc_list(struct mg_rpc_req *r);
```
Built-in RPC method to list all registered RPC methods. This function is not usually called directly, but registered as a method.
Parameters:
- `req` - a request
Usage example:
```c
mg_rpc_add(&s_rpc_head, mg_str("rpc.list"), mg_rpc_list, &s_rpc_head);
```
(see also [mg_rpc_add()](#mg_rpc_add))
Update docs
2021-09-15 14:43:24 +08:00
## Utility
### mg\_call()
```c
void mg_call(struct mg_connection *c, int ev, void *ev_data);
```
Send `ev` event to `c` event handler. This function is useful then implementing
your own protocol.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to send event
- `ev` - Event to send
- `ev_data` - Additional event parameter
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
// In a timer callback, send MG_EV_USER event to all connections
static void timer_fn(void *arg) {
struct mg_mgr *mgr = (struct mg_mgr *) arg;
for (struct mg_connection *c = mgr->conns; c != NULL; c = c->next) {
mg_call(c, MG_EV_USER, "hi!");
}
}
```
### mg\_error()
```c
void mg_error(struct mg_connection *c, const char *fmt, ...);
```
Send `MG_EV_ERROR` to connection event handler with error message formatted using printf semantics.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Connection to send event
- `fmt` - Format string in `printf` semantics
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
mg_error(c, "Operation failed, error code: %d", errno);
```
### mg\_md5\_init()
```c
void mg_md5_init(mg_md5_ctx *c);
```
Initialize context for MD5 hashing.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - Pointer to `mg_md5_ctx` structure to initialize
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
mg_md5_ctx ctx;
mg_md5_init(&ctx);
```
### mg\_md5\_update()
```c
void mg_md5_update(mg_md5_ctx *c, const unsigned char *data, size_t len);
```
Hash `len` bytes of data pointed by `data` using MD5 algorithm.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - MD5 context
- `data` - Data to hash
- `len` - Data length
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
mg_md5_ctx ctx;
// Context initialization
// ...
mg_md5_update(&ctx, "data", 4); // hash "data" string
mg_md5_update(&ctx, "more data", 9); // hash "more data" string
```
### mg\_md5\_final()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
void mg_md5_final(mg_md5_ctx *c, unsigned char buf[16]);
Update docs
2021-09-15 14:43:24 +08:00
```
Get current MD5 hash for context.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - MD5 context
- `buf` - Pointer to buffer to write MD5 hash value
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
mg_md5_ctx ctx;
// Context initialization
// ...
unsigned char buf[16];
mg_md5_final(&ctx, buf); // `buf` is now MD5 hash
```
### mg\_sha1\_init()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
void mg_sha1_init(mg_sha1_ctx *c);
Update docs
2021-09-15 14:43:24 +08:00
```
Initialize context for calculating SHA1 hash
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `c` - pointer to `mg_sha1_ctx` structure to initialize
Return value: none
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
mg_sha1_ctx ctx;
mg_sha1_init(&ctx);
```
### mg\_sha1\_update()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
void mg_sha1_update(mg_sha1_ctx *c, const unsigned char *data, size_t len);
Update docs
2021-09-15 14:43:24 +08:00
```
Hash `len` bytes of `data` using SHA1 algorithm.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Fix links and typos
2021-11-16 20:30:40 +08:00
- `c` - SHA1 context
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `data` - Data to hash
- `len` - Data length
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
mg_sha1_ctx ctx;
// Context initialization
// ...
mg_sha1_update(&ctx, "data", 4); // hash "data" string
mg_sha1_update(&ctx, "more data", 9); // hash "more data" string
```
### mg\_sha1\_final()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
void mg_sha1_final(unsigned char digest[20], mg_sha1_ctx *c);
Update docs
2021-09-15 14:43:24 +08:00
```
Get current SHA1 hash for context.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `c` - SHA1 context
- `digest` - Pointer to buffer to receive hash value
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
mg_sha1_ctx ctx;
// Context initialization
// ...
unsigned char buf[20];
mg_sha1_final(buf, &ctx); // `buf` is now SHA1 hash
```
### mg\_base64\_update()
```c
int mg_base64_update(unsigned char p, char *out, int pos);
```
Encode `p` byte to base64 and write result into `out` buffer starting with `pos` position.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `p` - Byte to encode
- `out` - Pointer to buffer to write result
- `pos` - Position in output buffer to write result
Add params and retvals
2021-09-15 20:37:57 +08:00
Fix links and typos
2021-11-16 20:30:40 +08:00
Return value: New position for further operations
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
char buf[10];
mg_base64_update((unsigned char)"a", buf, 0); // Encode "a" into base64 and write it to the beginning of buf
```
### mg\_base64\_final()
```c
int mg_base64_final(char *buf, int pos);
```
Add base64 finish mark and `\0` symbol to `buf` at `pos` position.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `buf` - Pointer to buffer to write finish mark
- `pos` - Position to write
Add params and retvals
2021-09-15 20:37:57 +08:00
Fix links and typos
2021-11-16 20:30:40 +08:00
Return value: New position for further operations
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
```c
char buf[10];
int pos;
// ...
mg_base64_final(buf, pos);
```
### mg\_base64\_encode()
```c
int mg_base64_encode(const unsigned char *p, int n, char *to);
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Encode `n` bytes data pointed by `p` using base64 and write result into `to`.
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `p` - Pointer to data to encode
- `n` - Data length
- `to` - Pointer to buffer to write result
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Written symbols number
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
char buf[128];
mg_base64_encode((uint8_t *) "abcde", 5, buf); // buf is now YWJjZGU=
```
### mg\_base64\_decode()
```c
int mg_base64_decode(const char *src, int n, char *dst);
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Decode `n` bytes of base64-ed `src` and write it to `dst`.
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `src` - Data to decode
- `n` - Data length
- `dst` - Pointer to output buffer
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Number of written symbols.
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
char buf[128];
mg_base64_decode("Q2VzYW50YQ==", 12, buf); // buf is now "Cesanta"
```
### mg\_random()
```c
void mg_random(void *buf, size_t len);
```
Fill in buffer `buf`, `len` with random data. Note: Mongoose uses this
function for TLS and some other routines that require RNG (random number
generator). It is possible to override a built-in `mg_random()` by specifying
a `MG_ENABLE_CUSTOM_RANDOM=1` build preprocessor constant.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `buf` - Pointer to buffer to receive random data
- `len` - Buffer size
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
char buf[10];
mg_random(buf, sizeof(buf)); // `buf` is now random bytes
```
Fix #1616 - randomize mqtt will and client id for parallel test
2022-07-04 18:00:06 +08:00
### mg\_random\_str()
```c
char *mg_random_str(char *buf, size_t len);
```
Fill in buffer `buf`, `len` with random alphanumeric characters: `a-zA-Z0-9`.
A buffer is zero-terminated.
Parameters:
- `buf` - a pointer to a buffer
- `len` - a buffer size
Return value: `buf` value.
Usage example:
```c
char buf[10];
printf("Random: %s\n", mg_random_str(buf, sizeof(buf)));
```
Update docs
2021-09-15 14:43:24 +08:00
### mg\_ntohs()
```c
uint16_t mg_ntohs(uint16_t net);
```
Convert `uint16_t` value to host order.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `net` - 16-bit value in network order
Return value: 16-bit value in host order
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
uint16_t val = mg_ntohs(0x1234);
```
### mg\_ntohl()
```c
uint32_t mg_ntohl(uint32_t net);
```
Convert `uint32_t` value to host order.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `net` - 32-bit value in network order
Return value: 32-bit value in host order
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
uint32_t val = mg_ntohl(0x12345678);
```
### mg\_ntohs()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
uint16_t mg_htons(uint16_t h);
Update docs
2021-09-15 14:43:24 +08:00
```
Convert `uint16_t` value to network order.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `h` - 16-bit value in host order
Return value: 16-bit value in network order
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
uint16_t val = mg_htons(0x1234);
```
### mg\_htonl()
```c
Add params and retvals
2021-09-15 20:37:57 +08:00
uint32_t mg_ntohl(uint32_t h);
Update docs
2021-09-15 14:43:24 +08:00
```
Convert `uint32_t` value to network order.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `h` - 32-bit value in host order
Return value: 32-bit value in network order
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
uint32_t val = mg_htonl(0x12345678);
```
### mg\_crc32()
```c
uint32_t mg_crc32(uint32_t crc, const char *buf, size_t len);
```
Calculate CRC32 checksum for a given buffer. An initial `crc` value should be `0`.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Fix links and typos
2021-11-16 20:30:40 +08:00
- `crc` - Initial CRC value
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `buf` - Data to calculate CRC32
- `len` - Data size
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Calculated CRC32 checksum
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
char data[] = "hello";
uint32_t crc = mg_crc32(0, data, sizeof(data));
```
### mg\_check\_ip\_acl()
```c
int mg_check_ip_acl(struct mg_str acl, uint32_t remote_ip);
```
Check IPv4 address `remote_ip` against the IP ACL `acl`. Parameters:
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update docs
2021-09-15 14:43:24 +08:00
- `acl` - an ACL string, e.g. `-0.0.0.0/0,+1.2.3.4`
- `remote_ip` - IPv4 address in network byte order
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: 1 if `remote_ip` is allowed, 0 if not, and <0 if `acl` is invalid
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
if (mg_check_ip_acl(mg_str("-0.0.0.0/0,+1.2.3.4"), c->peer.ip) != 1) {
LOG(LL_INFO, ("NOT ALLOWED!"));
}
```
### mg\_url\_decode()
```c
int mg_url_decode(const char *s, size_t n, char *to, size_t to_len, int form);
```
Decode URL-encoded string `s` and write it into `to` buffer.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `s` - String to encode
Fix links and typos
2021-11-16 20:30:40 +08:00
- `n` - String to encode length
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `to` - Pointer to output buffer
- `to_len` - Output buffer size
- `form` - If non-zero, then `+` is decoded as whitespace.
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Decoded bytes count or negative value on error
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
char url[] = "eexample.org%2Ftest";
char buf[1024];
mg_url_encode(url, sizeof(url) - 1, buf, sizeof(buf), 0); // buf is now "example.org/test"
```
### mg\_url\_encode
```c
size_t mg_url_encode(const char *s, size_t n, char *buf, size_t len);
```
Encode `s` string to URL-encoding and write encoded string into `buf`.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `s` - String to encode
- `n` - String to encode length
- `buf` - Output buffer
- `len` - Output buffer size
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Number of characters written to `buf`
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
char url[] = "example.org/test";
char buf[1024];
mg_url_encode(url, sizeof(url) - 1, buf, sizeof(buf)); // buf is now "example.org%2Ftest"
```
## IO Buffers
IO buffer, described by the `struct mg_iobuf`, is a simple data structure
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
that inserts or deletes chunks of data at arbitrary offsets and grows/shrinks
struct iobuf doc
2021-08-30 20:06:45 +08:00
automatically.
Update docs
2021-08-28 15:46:01 +08:00
### struct mg\_iobuf
More docs
2020-12-09 00:26:17 +08:00
Update docs
2021-08-28 15:46:01 +08:00
```c
struct mg_iobuf {
struct iobuf doc
2021-08-30 20:06:45 +08:00
unsigned char *buf; // Pointer to stored data
size_t size; // Total size available
size_t len; // Current number of bytes
Add align to struct mg_iobuf
2022-08-01 19:53:25 +08:00
size_t align; // Alignment during allocation
Update docs
2021-08-28 15:46:01 +08:00
};
```
Generic IO buffer. The `size` specifies an allocation size of the data pointed
by `buf`, and `len` specifies number of bytes currently stored.
Change mg_iobuf image
2022-05-25 01:56:54 +08:00
<img src="images/mg_iobuf.svg" alt="struct mg_iobuf diagram" />
Update docs
2021-09-15 14:43:24 +08:00
Update docs
2021-08-28 15:46:01 +08:00
### mg\_iobuf\_init()
More docs
2020-12-09 00:26:17 +08:00
```c
Add align to struct mg_iobuf
2022-08-01 19:53:25 +08:00
int mg_iobuf_init(struct mg_iobuf *io, size_t size, size_t align);
More docs
2020-12-09 00:26:17 +08:00
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Initialize IO buffer, allocate `size` bytes.
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `io` - Pointer to `mg_iobuf` structure to initialize
- `size` - Amount of bytes to allocate
Add align to struct mg_iobuf
2022-08-01 19:53:25 +08:00
- `align` - Align `size` to the `align` mem boundary. `0` means no alignment
Add params and retvals
2021-09-15 20:37:57 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: 1 on success, 0 on allocation failure
Add streaming client support, MG_EV_HTTP_CHUNK
2021-03-08 23:41:16 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
struct mg_iobuf io;
Add align to struct mg_iobuf
2022-08-01 19:53:25 +08:00
if (mg_iobuf_init(&io, 0, 64)) {
Update docs
2021-09-15 14:43:24 +08:00
// io successfully initialized
}
```
Update docs
2021-08-28 15:46:01 +08:00
### mg\_iobuf\_resize()
Add streaming client support, MG_EV_HTTP_CHUNK
2021-03-08 23:41:16 +08:00
```c
Update docs
2021-08-28 15:46:01 +08:00
int mg_iobuf_resize(struct mg_iobuf *io, size_t size);
Add streaming client support, MG_EV_HTTP_CHUNK
2021-03-08 23:41:16 +08:00
```
Update docs
2021-08-28 15:46:01 +08:00
Resize IO buffer, set the new size to `size`. The `io->buf` pointer could
change after this, for example if the buffer grows. If `size` is 0, then the
`io->buf` is freed and set to NULL, and both `size` and `len` are set to 0.
Add align to struct mg_iobuf
2022-08-01 19:53:25 +08:00
The resulting `io->size` is always aligned to the `io->align` byte boundary;
therefore, to avoid memory fragmentation and frequent reallocations, set
`io->align` to a higher value.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `io` - iobuf to resize
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `size` - New size
Add params and retvals
2021-09-15 20:37:57 +08:00
Return value: 1 on success, 0 on allocation failure
Add mg_check_ip_acl()
2021-08-25 14:59:31 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
struct mg_iobuf io;
Add align to struct mg_iobuf
2022-08-01 19:53:25 +08:00
mg_iobuf_init(&io, 0, 10); // An empty buffer with 10-byte alignment
Update docs
2021-09-15 14:43:24 +08:00
Add align to struct mg_iobuf
2022-08-01 19:53:25 +08:00
if (mg_iobuf_resize(&io, 1)) {
// New io size is 10
Update docs
2021-09-15 14:43:24 +08:00
}
```
Update docs
2021-08-28 15:46:01 +08:00
### mg\_iobuf\_free()
Add mg_check_ip_acl()
2021-08-25 14:59:31 +08:00
```c
Update docs
2021-08-28 15:46:01 +08:00
void mg_iobuf_free(struct mg_iobuf *io);
Add mg_check_ip_acl()
2021-08-25 14:59:31 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
Free memory pointed by `io->buf` and set to NULL. Both `size` and `len` are set to 0.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `io` - iobuf to free
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
struct mg_iobuf io;
// IO buffer initialization
// ...
Add mg_check_ip_acl()
2021-08-25 14:59:31 +08:00
Update docs
2021-09-15 14:43:24 +08:00
// Time to cleanup
mg_iobuf_free(&io);
```
Add mg_check_ip_acl()
2021-08-25 14:59:31 +08:00
Update docs
2021-08-28 15:46:01 +08:00
### mg\_iobuf\_add()
Add mg_check_ip_acl()
2021-08-25 14:59:31 +08:00
Update docs
2021-08-28 15:46:01 +08:00
```c
Add align to struct mg_iobuf
2022-08-01 19:53:25 +08:00
size_t mg_iobuf_add(struct mg_iobuf *io, size_t offset, const void *buf, size_t len);
Update docs
2021-08-28 15:46:01 +08:00
```
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Insert data buffer `buf`, `len` at offset `offset`. The iobuf is expanded
Add align to struct mg_iobuf
2022-08-01 19:53:25 +08:00
if required. The resulting `io->size` is always aligned to the `io->align` byte boundary; therefore,
Update docs
2021-09-15 14:43:24 +08:00
to avoid memory fragmentation and frequent reallocations, set `align` to a higher value.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `io` - iobuf to add data
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `offset` - Offset to add data
- `buf` - Data to add
Fix links and typos
2021-11-16 20:30:40 +08:00
- `len` - Data length
Add params and retvals
2021-09-15 20:37:57 +08:00
Fix links and typos
2021-11-16 20:30:40 +08:00
Return value: new `io` length
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
Add mg_check_ip_acl()
2021-08-25 14:59:31 +08:00
Add stm32-nucleo-h743z and stm32-nucleo-f429z
2021-08-26 18:40:47 +08:00
```c
Add align to struct mg_iobuf
2022-08-01 19:53:25 +08:00
struct mg_iobuf io; // Declare buffer
mg_iobuf_init(&io, 0, 16); // Initialise empty buffer with 16 byte alignment
docs
2022-06-08 18:30:54 +08:00
```
<img src="images/mg_iobuf_add1.svg" alt="Function mg_iobuf_init()" />
```c
Add align to struct mg_iobuf
2022-08-01 19:53:25 +08:00
mg_iobuf_add(&io, io.len, "hello", 5); // Append "hello"
Update docs
2021-08-28 15:46:01 +08:00
```
docs
2022-06-08 18:30:54 +08:00
<img src="images/mg_iobuf_add2.svg" alt="Function mg_iobuf_add()" />
Update docs
2021-09-15 14:43:24 +08:00
Update docs
2021-08-28 15:46:01 +08:00
### mg\_iobuf\_del()
```c
size_t mg_iobuf_del(struct mg_iobuf *io, size_t offset, size_t len);
Add mg_check_ip_acl()
2021-08-25 14:59:31 +08:00
```
Update docs
2021-08-28 15:46:01 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Delete `len` bytes starting from `offset`, and shift the remaining bytes.
If `len` is greater than `io->len`, nothing happens, so such call is silently ignored.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `io` - iobuf to delete data
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `offset` - Start offset
- `len` - Amount of bytes to delete
Add params and retvals
2021-09-15 20:37:57 +08:00
Fix links and typos
2021-11-16 20:30:40 +08:00
Return value: New `io` length
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
struct mg_iobuf io;
Update docs
2022-08-06 02:55:15 +08:00
mg_iobuf_init(&io, 0, 16); // Empty buffer
mg_iobuf_add(&io, 0, "hi", 2); // io->len is 2, io->size is 16
mg_iobuf_del(&io, 0, "hi", 2); // io->len is 0, io->size is still 16
Update docs
2021-09-15 14:43:24 +08:00
```
Update images
2022-08-06 02:44:55 +08:00
<img src="images/mg_iobuf_del.svg" alt="Function mg_iobuf_del()" />
Update docs
2021-09-15 14:43:24 +08:00
## URL
### mg\_url\_port()
```c
unsigned short mg_url_port(const char *url);
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Return port for given URL
Parameters:
- `url` - URL to extract port
Fix links and typos
2021-11-16 20:30:40 +08:00
Return value: Port for given URL or `0` if URL doesn't contain port and there
isn't default port for URL protocol
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
fix the doc error: htts to https
2022-09-03 10:51:09 +08:00
unsigned short port1 = mg_url_port("https://myhost.com") // port1 is now 443 (default https port)
Update docs
2021-09-15 14:43:24 +08:00
unsigned short port2 = mg_url_port("127.0.0.1:567") // port2 is now 567
```
### mg\_url\_is_ssl()
```c
int mg_url_is_ssl(const char *url);
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Check if given URL uses encrypted scheme
Parameters:
- `url` - URL to check
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: `0` is given URL uses encrypted scheme and non-zero otherwise
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
if (mg_url_is_ssl("https://example.org") == 0) {
// scheme is encrypted
}
```
### mg\_url\_host()
```c
struct mg_str mg_url_host(const char *url);
```
Extract host name from given URL.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Include ipv6 wrapping brackets [] in the result of mg_url_host()
2021-09-21 15:10:27 +08:00
- `url` - a URL string
Add params and retvals
2021-09-15 20:37:57 +08:00
Return value: host name
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
Include ipv6 wrapping brackets [] in the result of mg_url_host()
2021-09-21 15:10:27 +08:00
struct mg_str a = mg_url_host("https://my.example.org:1234"); // a == "my.example.org"
struct mg_str b = mg_url_host("tcp://[::1]"); // b == "[::1]"
Update docs
2021-09-15 14:43:24 +08:00
```
### mg\_url\_user()
```c
struct mg_str mg_url_user(const char *url);
```
Extract user name from given URL.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `url` - URL to extract user name
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: User name or empty string if not found
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
struct mg_str user_name = mg_url_user("https://user@password@my.example.org"); // user_name is now "user"
```
### mg\_url\_pass()
```c
struct mg_str mg_url_pass(const char *url);
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Extract password from given URL.
Parameters:
- `url` - URL to extract password
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: Password or empty string if not found
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
struct mg_str pwd = mg_url_user("https://user@password@my.example.org"); // pwd is now "password"
```
### mg\_url\_uri()
```c
const char *mg_url_uri(const char *url);
```
Add params and retvals
2021-09-15 20:37:57 +08:00
Extract URI from given URL.
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Note, that function returns pointer within `url`; there is no need to free() it explicitly
Update docs
2021-09-15 14:43:24 +08:00
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
- `url` - URL to extract URI
Return value: URI or `\` if not found
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
```c
const char *uri = mg_url_uri("https://example.org/subdir/subsubdir"); // `uri` is now pointer to "subdir/subsubdir"
```
## Logging
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Mongoose provides a set of functions and macros for logging. The application can
Update docs
2021-09-15 14:43:24 +08:00
use these functions for its own purposes as well as the rest of Mongoose API.
### LOG()
```c
#define LOG(level, args)
Get rid of MG_ENABLE_LOG, change mg_hexdump()
2022-05-07 04:09:13 +08:00
#define MG_ERROR(args) MG_LOG(MG_LL_ERROR, args)
#define MG_INFO(args) MG_LOG(MG_LL_INFO, args)
#define MG_DEBUG(args) MG_LOG(MG_LL_DEBUG, args)
#define MG_VERBOSE(args) MG_LOG(MG_LL_VERBOSE, args)
Update docs
2021-09-15 14:43:24 +08:00
```
Get rid of MG_ENABLE_LOG, change mg_hexdump()
2022-05-07 04:09:13 +08:00
Logging macros.
Update docs
2021-09-15 14:43:24 +08:00
Usage example:
Get rid of MG_ENABLE_LOG, change mg_hexdump()
2022-05-07 04:09:13 +08:00
Update docs
2021-09-15 14:43:24 +08:00
```c
Get rid of MG_ENABLE_LOG, change mg_hexdump()
2022-05-07 04:09:13 +08:00
MG_INFO(("Hello %s!", "world")); // Output "Hello, world"
Update docs
2021-09-15 14:43:24 +08:00
```
### mg\_log\_set()
```c
void mg_log_set(const char *spec);
```
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Set Mongoose logging level.
Add params and retvals
2021-09-15 20:37:57 +08:00
Parameters:
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
- `spec` - String, containing log level, can be one of the following values:
Minor formatting fix
2022-05-25 18:14:42 +08:00
- `0` - Disable logging
- `1` - Log errors only
- `2` - Log errors and info messages
Fix typo in documentation
2022-10-15 09:27:06 +08:00
- `3` - Log errors, info and debug messages
Minor formatting fix
2022-05-25 18:14:42 +08:00
- `4` - Log everything
Update docs
2021-09-15 14:43:24 +08:00
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
Return value: None
Add params and retvals
2021-09-15 20:37:57 +08:00
Update docs
2021-09-15 14:43:24 +08:00
It is possible to override log level per source file basis. For example, if
there is a file called `foo.c`, and you'd like to set a global level to `2`
Update README.md I have gone through and edited for consistency, punctuation, wording, and grammar. If you have questions feel free to reach out. I fixed some spelling errors "if" instead of "is" "update" instead of "updatw", etc. -Jordan Ramsey
2021-09-24 00:07:00 +08:00
(info) but increase log level for file foo.c to `debug`, then, a `spec` should
Update docs
2021-09-15 14:43:24 +08:00
look like `"2,foo.c=3"`. There could be several comma-separated overrides.
Usage example:
```c
mg_log_set("2"); // Set log level to info
mg_log_set("2,foo.c=3,bar.c=0"); // Set log level to info, with overrides
```
Get rid of MG_ENABLE_LOG, change mg_hexdump()
2022-05-07 04:09:13 +08:00
### mg\_hexdump()
```c
void mg_hexdump(const void *buf, int len);
```
Log a hex dump of binary data `buf`, `len`.
Parameters:
- `buf` - Data pointer
- `len` - Data length
Return value: none
Usage example:
```c
mg_hexdump(c->recv.buf, c->recv.len); // Hex dump incoming data
```
Add mg_log_set_fn(), MG_ENABLE_LOG
2022-06-19 16:04:22 +08:00
### mg\_log\_set\_fn()
```c
Update mg_log_set_fn()
2022-08-13 22:43:27 +08:00
void mg_log_set_fn(mg_pfn_t logfunc, void *param);
Add mg_log_set_fn(), MG_ENABLE_LOG
2022-06-19 16:04:22 +08:00
```
Redirect logs to a custom function. Parameters:
- `logfunc` - a pointer to a function that logs a single character
Update mg_log_set_fn()
2022-08-13 22:43:27 +08:00
- `param` - a parameter for a logging function
Add mg_log_set_fn(), MG_ENABLE_LOG
2022-06-19 16:04:22 +08:00
Usage example: redirecting logs to syslog.
```c
Update mg_log_set_fn()
2022-08-13 22:43:27 +08:00
static void mylog(char ch, void *param) {
Add examples/esp32/uart-bridge
2022-06-20 01:27:37 +08:00
static char buf[256];
static size_t len;
buf[len++] = ch;
if (ch == '\n' || len >= sizeof(buf)) {
syslog(LOG_INFO, "%.*s", (int) len, buf); // Send logs
len = 0;
Add mg_log_set_fn(), MG_ENABLE_LOG
2022-06-19 16:04:22 +08:00
}
}
...
Update mg_log_set_fn()
2022-08-13 22:43:27 +08:00
mg_log_set_fn(mylog, NULL);
Add mg_log_set_fn(), MG_ENABLE_LOG
2022-06-19 16:04:22 +08:00
```
Update docs
2021-09-15 14:43:24 +08:00
## Filesystem
Enhance fs docs
2022-05-25 20:28:25 +08:00
### struct mg\_fs
Update docs
2021-09-15 14:43:24 +08:00
Enhance fs docs
2022-05-25 20:28:25 +08:00
```c
struct mg_fs {
int (*st)(const char *path, size_t *size, time_t *mtime); // stat file
void (*ls)(const char *path, void (*fn)(const char *, void *), void *);
void *(*op)(const char *path, int flags); // Open file
void (*cl)(void *fd); // Close file
size_t (*rd)(void *fd, void *buf, size_t len); // Read file
size_t (*wr)(void *fd, const void *buf, size_t len); // Write file
size_t (*sk)(void *fd, size_t offset); // Set file position
bool (*mv)(const char *from, const char *to); // Rename file
bool (*rm)(const char *path); // Delete file
bool (*mkd)(const char *path); // Create directory
};
enum { MG_FS_READ = 1, MG_FS_WRITE = 2, MG_FS_DIR = 4 };
```
Filesystem virtualisation layer.
Mongoose allows to override file IO operations in order to support different
Update docs
2021-09-15 14:43:24 +08:00
storages, like programmable flash, no-filesystem devices etc.
In order to accomplish this, Mongoose provides a `struct mg_fs` API to
docs
2022-05-25 03:36:21 +08:00
specify a custom filesystem. In addition to this, Mongoose provides several
Enhance fs docs
2022-05-25 20:28:25 +08:00
built-in APIs - a standard POSIX, FatFS, and a "packed FS" API:
Update docs
2021-09-15 14:43:24 +08:00
```c
Enhance fs docs
2022-05-25 20:28:25 +08:00
extern struct mg_fs mg_fs_posix; // POSIX open/close/read/write/seek
Typo fs docs
2022-05-25 20:29:49 +08:00
extern struct mg_fs mg_fs_packed; // Packed FS, see examples/device-dashboard
Enhance fs docs
2022-05-25 20:28:25 +08:00
extern struct mg_fs mg_fs_fat; // FAT FS
```
Update docs
2021-09-15 14:43:24 +08:00
Enhance fs docs
2022-05-25 20:28:25 +08:00
### struct mg\_fd
```c
struct mg_fd {
void *fd;
struct mg_fs *fs;
Update docs
2021-09-15 14:43:24 +08:00
};
```
Enhance fs docs
2022-05-25 20:28:25 +08:00
Opened file abstraction.
### mg\_fs\_open()
```c
struct mg_fd *mg_fs_open(struct mg_fs *fs, const char *path, int flags);
```
Open a file in a given filesystem.
Parameters:
- `fs` - a filesystem implementation
- `path` - a file path
- `flags` - desired flags, a combination of `MG_FS_READ` and `MG_FS_WRITE`
Return value: a non-NULL opened descriptor, or NULL on failure.
Usage example:
```c
struct mg_fd *fd = mg_fs_open(&mg_fs_posix, "/tmp/data.json", MG_FS_WRITE);
```
### mg\_fs\_close()
```c
void mg_fs_close(struct mg_fd *fd);
```
Close an opened file descriptor.
Parameters:
- `fd` - an opened file descriptor
Return value: none
### mg\_file\_read()
```c
char *mg_file_read(struct mg_fs *fs, const char *path, size_t *size);
```
Read the whole file in memory.
Parameters:
- `fs` - a filesystem implementation
- `path` - a file path
- `size` - if not NULL, will contained the size of the read file
Return value: on success, a pointer to file data, which is guaranteed
to the 0-terminated. On error, NULL.
Usage example:
```c
size_t size = 0;
char *data = mg_file_read(&mg_fs_packed, "/data.json", &size);
```
### mg\_file\_write()
```c
bool mg_file_write(struct mg_fs *fs, const char *path, const void *buf, size_t len);
```
Write a piece of data `buf`, `len` to a file `path`. If the file does not
exist, it gets created. The previous content, if any, is deleted.
Parameters:
- `fs` - a filesystem implementation
- `path` - a file path
- `buf` - a pointer to data to be written
- `len` - a data size
Return value: true on success, false on error
Usage example:
```c
mg_file_write(&mg_fs_fat, "/test.txt", "hi\n", 3);
```
### mg\_file\_printf()
```c
bool mg_file_printf(struct mg_fs *fs, const char *path, const char *fmt, ...);
```
Write a printf-formatted data to a file `path`. If the file does not
exist, it gets created. The previous content, if any, is deleted.
Parameters:
- `fs` - a filesystem implementation
- `path` - a file path
- `fmt` - a [mg_snprintf](#mg-snrpintf) format string
Return value: true on success, false on error
Usage example:
Update docs
2021-09-15 14:43:24 +08:00
```c
Enhance fs docs
2022-05-25 20:28:25 +08:00
mg_file_printf(&mg_fs_fat, "/test.txt", "%s\n", "hi");
Update docs
2021-09-15 14:43:24 +08:00
```
Reference in New Issue Copy Permalink