= Mongoose Web Server =

This page aims to help application developers integrate the [https://github.com/valenok/mongoose/ Mongoose] Web / HTTP server into their RTEMS applications. Only a reasonably basic configuration is treated.

It is assumed that:
 *  the reader is using RTEMS 4.11 (the interface to Mongoose has changed significantly from 4.10), [wiki:TBR/UserManual/Quick_Start compiling it from source] and is comfortable doing so
 *  networking is already configured and working in the application
 *  a file-system (from which to serve web pages and write logs to) is already configured and working in the application

=  What is it?  =

Mongoose is a lightweight web server, one of two (the other being the [wiki:TBR/UserManual/Simple_HTTPD Simple HTTPD] server) available in RTEMS.

Unfortunately, recent versions of the server have moved to an RTEMS-incompatible license and thus it is not up-to-date in RTEMS. It is anticipated that it will be removed at some future date.

=  Prerequisites  =

RTEMS must have been configured with networking and POSIX interfaces enabled.

=  Library  =

The Mongoose library must be pulled in for linking. To do so, ensure that ''-lmghttpd'' is passed to the linker.

If you're using a ''Makefile'' based on the provided [http://git.rtems.org/rtems/tree/make/Templates/Makefile.leaf template] - available for RTEMS 4.11 in its ''share/rtems4.11/make/Templates/Makefile.leaf'' path - this can be accomplished by adding ''-lmghttpd'' to ''LD_LIBS''; e.g.:
{{{
LD_LIBS+=-lmghttpd
}}}

=  CONFIGURE / confdefs.h  =

Mongoose uses the POSIX API and its mutex and condition variable features and thus resources must be allocated for it in the application's configuration.

It uses:
* One POSIX "master" thread
* A number of POSIX worker threads, depending on the number requested when starting Mongoose
* Two libio file descriptors for each worker thread
* Three POSIX condition variables
* One POSIX mutex

=  Initializing Mongoose  =

{{{
#include <mghttpd/mongoose.h>
}}}
in the source file you'll initialize Mongoose from.

''mg_start()'' is used to start Mongoose:
{{{
struct mg_context *mg_start(const struct mg_callbacks *callbacks, void *user_data, const char **options)
}}}

For the basic configuration described here, ''NULL'' can be passed for the ''user_data'' parameter, but ''callback'' '''must''' be provided. To initialise a structure with no callbacks enabled, use:
{{{
struct mg_callbacks callbacks = { NULL };
}}}

The ''options'' parameter is a ''NULL''-terminated array of string pairs, each pair giving an option name and a value (see the Mongoose documentation for a [https://docs.cesanta.com/Options.shtml description of options]). By way of example, ''options'' might be defined as such:
{{{
 const char *options[] = {
   "document_root",   "/usr/www",
   "listening_ports", "80",
   "num_threads",     "1",
   "thread_priority", "10",
   "access_log_file", "/var/log/httpd-access.log",
   "error_log_file",  "/var/log/httpd-error.log",
   NULL
 }
}}}

Calling ''mg_start()'' (after networking and the file-system are initialized) will return a "context" upon success, ''NULL'' upon failure (sadly, at the time of writing, not necessarily with an indication of the nature of the failure - configuring an error log (as in the example ''options'' above) is recommended for troubleshooting failures).

This context is used for further operating on that Mongoose instance (for example, in calling ''mg_stop()'' to halt it).

=  Done!  =

Hopefully at this point, you've a working Mongoose server.

Ensure there's a page for it to serve (e.g., ''/usr/www/index.html'') and test by browsing to ''!http://''<ip>''/'' (where ''<ip>'' is a resolvable name or IP address for your RTEMS target)!