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_start() to start the server. Pass configuration options and event handlers to mg_start(). Call mg_stop() when server needs to be stopped.

Mongoose calls event handlers when certain events happen. For example, when new request arrives, Mongoose calls begin_request handler to let user handle the request. In the handler, user code can get all information about the request -- parsed headers, etcetera. Here is a list of well-commented embedding examples:

hello.c This is the most basic "Hello, world!" example
post.c This example shows how to handle form submission
upload.c This example shows how to handle file upload
websocket.c This example shows how to handle websocket requests
chat.c, main.js An example of web chat application, with cookie-based user authentication, session support. All UI is done using static HTML/CSS. Interaction with backed is done using AJAX.

API Reference

mg_start()

struct mg_context *mg_start(const char **configuration_options
                            int (*event_handler_func)(struct mg_event *),
                            void *user_data);

Starts mongoose web server. This function starts a separate master thread, which opens listening sockets, and num_threads worker threads, which are used to handle incoming requests.

options: NULL terminated list of option_name, option_value pairs that specify Mongoose configuration parameters.
event_handler: a function that will be called on specific events, see description below.
user_data: Opaque pointer, used by application developer to store global private data.
Return: web server context, or NULL on error.

Side-effects: on UNIX, mg_start() ignores SIGPIPE signals. If custom processing is required SIGPIPE, signal handler must be set up after calling mg_start().

Important: Mongoose does not install SIGCHLD handler. If CGI is used, SIGCHLD handler must be set up to reap CGI zombie processes.

mg_stop()

void mg_stop(struct mg_context *);

Stop the web server. This function blocks until all Mongoose threads are stopped. Context pointer becomes invalid.

Events triggered by Mongoose

Every time an event happens, such as new connection being made, Mongoose calls user-specified event handler. Mongoose passes struct mg_event structure to the event handler, which event handler can use to find any information required to handle an event:

struct mg_event {
  int type;               // Event type
  void *user_data;        // User data pointer passed to mg_start()
  void *conn_data;        // Connection-specific, per-thread user data.
  void *event_param;      // Event-specific parameter
  struct mg_connection *conn;
  struct mg_request_info *request_info;
};

Below is a list of all events triggered by Mongoose:

MG_REQUEST_BEGIN

Called when Mongoose has received and successfully parsed new HTTP request. request_info attribute of struct mg_event contains parsed HTTP request. Return value tells mongoose what to do next. If event handler returns 0, that means that the handler did not process the request, did not send any data to the client, and expects Mongoose to continue processing the request. Returning non-zero tells Mongoose to stop doing any processing, cause callback already sent valid reply to the client.

MG_REQUEST_END

Called when mongoose has finished processing the request. Could be used to implement custom request logging, request execution time profiling, etcetera. Return value is ignored by Mongoose.

MG_HTTP_ERROR

Called when Mongoose is about to send HTTP error to the client. event_param attribute contains integer HTTP error code, that could be accessed like this:
int status_code = (int) (long) event->event_param;
If handler returns zero, then Mongoose proceeds with sending error to the client, otherwise Mongoose will not send anything.

MG_EVENT_LOG

Called when Mongoose wants to log an error message. Normally, error messages are logged to the error log file. If handler returns 0, mongoose will not log to the log file. event_param holds a message to be logged:
const char *message = (const char *) event->event_param;

MG_THREAD_BEGIN

Called when Mongoose starts a new thread. Handler will be executing in the context of that new thread. It is used to perform any extra per-thread initialization. Return value is ignored by Mongoose.

MG_THREAD_END

Called when Mongoose is about to terminate a thread. Used to clean up the state initialized by MG_THREAD_BEGIN handling. Return value is ignored.

Embedding Examples

The common pattern is to handle MG_REQUEST_BEGIN and serve static files from memory, and/or construct dynamic replies on the fly. Here is my embed.c gist that shows how to easily any data can be embedded directly into the executable. If such data needs to be encrypted, then encrypted database or encryption dongles would be a better choice.

5.8 KiB Raw Blame History