3.7 KiB
Mongoose Embedding Guide
Embedding Mongoose is done in two steps:
- Copy mongoose.c and mongoose.h to your application's source tree and include these two files in the build.
- Somewhere in the application code, call
mg_create_server()
to create a server, configure it withmg_set_option()
and loop withmg_poll_server()
until done. Callmg_destroy_server()
to cleanup.
Here's a minimal application app.c
that embeds mongoose:
#include "mongoose.h"
int main(void) {
struct mg_server *server = mg_create_server(NULL);
mg_set_option(server, "document_root", ".");
mg_set_option(server, "listening_port", "8080");
for (;;) mg_poll_server(server, 1000); // Infinite loop, Ctrl-C to stop
mg_destroy_server(&server);
return 0;
}
To compile it, put mongoose.c
, mongoose.h
and minimal.c
into one
folder, then run the following UNIX command:
cc app.c mongoose.c -o app
If you're on Windows, run this in a Visual Studio shell:
cl app.c mongoose.c /TC /MD
When run, this simple application opens port 8080 and serves static files, CGI files and lists directory content in the current working directory.
Mongoose can call user-defined functions when certain URIs are requested.
These functions are called uri handlers. mg_add_uri_handler()
registers
an URI handler, and there is no restriction exist on the number of URI handlers.
Also, mongoose can call a user-defined function when it is about to send
HTTP error back to client. That function is called http error handler and
can be registered by mg_set_http_error_handler()
. Handlers are called
by Mongoose with struct mg_connection *
pointer as a parameter, which
has all information about the request: HTTP headers, POST or websocket
data buffer, etcetera.
Let's extend our minimal application example and
create an URI that will be served by user's C code. The app will handle
/hello
URI by showing a hello message. So, when app is run,
http://127.0.0.1:8080/hello will say hello, and here's the code:
#include <string.h>
#include "mongoose.h"
static int handle_hello(struct mg_connection *conn) {
static const char *reply = "HTTP/1.0 200 OK\r\n\r\nHello world!\n";
mg_write(conn, reply, strlen(reply));
return 1;
}
int main(void) {
struct mg_server *server = mg_create_server(NULL);
mg_set_option(server, "document_root", ".");
mg_set_option(server, "listening_port", "8080");
mg_add_uri_handler(server, "/hello", &handle_hello);
for (;;) mg_poll_server(server, 1000); // Infinite loop, Ctrl-C to stop
mg_destroy_server(&server);
return 0;
}
Note that URI handler must output valid HTTP response, which includes
the reply line with status code HTTP/1.0 200 OK
, HTTP headers which are
empty in our example, and message body Hello world!\n
. Note that reply
line is ended with \r\n
, and HTTP headers are also ended with \r\n
.
Mongoose source code contains a well-commented example code, listed below:
-
hello.c shows how to handle form input, file upload, websocket communication, get cookie values.
-
chat implements basic online chat functionality using Lua scripting capabilities of Mongoose. Not a single line of C is written for that example. Demostrates usage of database, cookie-based authentication, session support, RESTful interface. No additional software is required to run it on any platform.