Mongoose Embedding Guide

Embedding Mongoose is done in two steps:

  1. Copy mongoose.c and mongoose.h to your application's source tree and include them in the build.
  2. Somewhere in the application code, call mg_create_server() to create a server, configure it with mg_set_option() and loop with mg_poll_server() until done. Call mg_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, NULL);
  mg_set_option(server, "document_root", ".");      // Serve current directory
  mg_set_option(server, "listening_port", "8080");  // Open 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 app.c into one folder, start terminal on UNIX or Visual Studio command line prompt on Windows, and run the following command:

cc app.c mongoose.c -pthread -o app     # on Unix
cl.exe app.c mongoose.c /TC /MD         # on Windows

When run, this simple application opens port 8080 and serves static files, CGI files and lists directory content in the current working directory.

It is possible to generate HTML page content. Mongoose can call user-defined function when certain events occur. That function is called an event handler, and it is the second parameter to mg_create_server() function. Here is the example event handler function:

int event_handler(struct mg_connection *conn, enum mg_event ev) {
  switch (ev) {
    case MG_AUTH: return MG_TRUE;
    default: return MG_FALSE;
  }
}

Event handler is called by Mongoose with struct mg_connection * pointer and an event number. struct mg_connection *conn has all information about the request: HTTP headers, POST or websocket data buffer, etcetera. enum mg_event ev tells which exactly event is sent. For each event, an event handler returns a value which tells Mongoose how to behave.

The sequence of events for every connection is this:

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 event_handler(struct mg_connection *conn, enum mg_event ev) {
  if (ev == MG_AUTH) {
    return MG_TRUE;   // Authorize all requests
  } else if (ev == MG_REQUEST && !strcmp(conn->uri, "/hello")) {
    mg_printf_data(conn, "%s", "Hello world");
    return MG_TRUE;   // Mark as processed
  } else {
    return MG_FALSE;  // Rest of the events are not processed
  }
}

int main(void) {
  struct mg_server *server = mg_create_server(NULL, event_handler);
  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;
}

Example code

Mongoose source code contains number of examples, located in the examples directory. To build any example, go to the respective directory and run make.

Compilation flags

Below is the list of compilation flags that enable or disable certain features. By default, some features are enabled, and could be disabled by setting appropriate NO_* flag. Features that are disabled by default could be enabled by setting appropriate USE_* flag. Bare bones Mongoose is quite small, about 30 kilobytes of compiled x86 code. Each feature adds a couple of kilobytes to the executable size, and also has some runtime penalty.

Note that some flags start with NS_ prefix. This is because Mongoose uses Net Skeleton as a low-level networking engine. If user code has #include <net_skeleton.h>, then all Net Skeleton functions will be available too.

-DMONGOOSE_NO_AUTH          Disable MD5 authorization support
-DMONGOOSE_NO_CGI           Disable CGI support
-DMONGOOSE_NO_DAV           Disable WebDAV support
                            (PUT, DELETE, MKCOL, PROPFIND methods)
-DMONGOOSE_NO_DIRECTORY_LISTING  Disable directory listing
-DMONGOOSE_NO_FILESYSTEM    Disables all file IO, serving from memory only
-DMONGOOSE_NO_LOGGING       Disable access/error logging
-DMONGOOSE_ENABLE_THREADS   Enable mg_start_thread() function
-DMONGOOSE_NO_WEBSOCKET     Disable WebSocket support
-DMONGOOSE_NO_USER          No concept of a user on used platform.
                            (Platform does not provide getpwnam, setgid or setuid)

-DMONGOOSE_USE_IDLE_TIMEOUT_SECONDS=X Idle connection timeout, default is 30
-DMONGOOSE_USE_LUA          Enable Lua scripting
-DMONGOOSE_USE_LUA_SQLITE3  Enable sqlite3 binding for Lua
-DMONGOOSE_USE_POST_SIZE_LIMIT=X      POST requests larger than X will be
                                      rejected, not set by default
-DMONGOOSE_USE_EXTRA_HTTP_HEADERS=X   Append X to the HTTP headers
                                      for static files, empty by default

-DNS_ENABLE_DEBUG         Enables debug messages on stdout, very noisy
-DNS_ENABLE_SSL           Enable SSL
-DNS_ENABLE_IPV6          Enable IPv6 support
-DNS_ENABLE_HEXDUMP       Enables hexdump of sent and received traffic
-DNS_STACK_SIZE=X         Sets stack size to X for  ns_start_thread()
-DNS_DISABLE_THREADS      Disable threads support
-DNS_DISABLE_SOCKETPAIR   For systems without loopback interface
-DMONGOOSE_SEND_NS_EVENTS Send Net Skeleton events to the event handler
                          in addition to the Mongoose events


rc_tagdetect_client
Author(s): Monika Florek-Jasinska , Raphael Schaller
autogenerated on Thu Jun 25 2020 03:46:05