Add means to replace mg_cry and log_access by own implemention

As discussed in #582, in some cases it might be useful to completely
replace an internal function by some user defined one. Still, the
interfaces of these functions, and even the function names (and
therefore the #define names), may change without notice.
Please read the section "Feature selection" in the Embedded.md
manual before using it.

docs/Building.md

@@ -6,10 +6,10 @@ See [Embedding.md](https://github.com/civetweb/civetweb/blob/master/docs/Embeddi
 
 #### Where to get the source code?
 
-The latest version can be found at
+The latest development version can be found at
 https://github.com/civetweb/civetweb
 
-Released versions can be found at
+Tested and released versions can be found at
 https://github.com/civetweb/civetweb/releases
 
 
@@ -74,6 +74,7 @@ make clean
 ```
 Clean up files generated during the build
 
+
 ## Setting build options
 
 Make options can be set on the command line with the make command like so.
@@ -86,10 +87,14 @@ make build WITH_LUA=1
 | ------------------------- | ----------------------------------------- |
 | WITH_LUA=1                | build with Lua support                    |
 | WITH_DUKTAPE=1            | build with server-side JavaScript support |
-| WITH_DEBUG=1              | build with GDB debug support              |
 | WITH_IPV6=1               | with IPV6 support                         |
 | WITH_WEBSOCKET=1          | build with web socket support             |
 | WITH_SERVER_STATS=1       | build with support for server statistics  |
+| WITH_EXPERIMENTAL=1       | include experimental features (depending  |
+|                           | on the version)                           |
+| WITH_ALL=1                | Include all of the above features         |
+|                           |                                           |
+| WITH_DEBUG=1              | build with GDB debug support              |
 | WITH_CPP=1                | build libraries with c++ classes          |
 | CONFIG_FILE=file          | use 'file' as the config file             |
 | CONFIG_FILE2=file         | use 'file' as the backup config file      |
@@ -105,6 +110,7 @@ make build WITH_LUA=1
 Note that the WITH_* options used for *make* are not identical to the
 preprocessor defines in the source code - usually USE_* is used there.
 
+
 ## Changing PREFIX
 
 To change the target destination pass the `PREFIX` option to the command `make install` (not `make build`). Example usage:
@@ -132,6 +138,7 @@ install -m 755 civetweb "/opt/civetweb/bin/"
 
 If the output looks good: Just remove the `-n` option to actually install the software on your system.
 
+
 ## Setting compile flags
 
 Compile flags can be set using the *COPT* make option like so.
@@ -139,17 +146,30 @@ Compile flags can be set using the *COPT* make option like so.
 make build COPT="-DNDEBUG -DNO_CGI"
 ```
 
-| Compile Flags             | Description                          |
-| ------------------------- | ------------------------------------ |
-| NDEBUG                    | strip off all debug code             |
-| DEBUG                     | build debug version (very noisy)     |
-| NO_CGI                    | disable CGI support                  |
-| NO_CACHING                | disable caching functionality        |
-| NO_SSL                    | disable SSL functionality            |
-| NO_SSL_DL                 | link against system libssl library   |
-| NO_FILES                  | do not serve files from a directory  |
-| SQLITE_DISABLE_LFS        | disables large files (Lua only)      |
-| SSL_ALREADY_INITIALIZED   | do not initialize libcrypto          |
+| Compile Flags              | Description                          |
+| -------------------------- | ------------------------------------ |
+| NDEBUG                     | strip off all debug code             |
+| DEBUG                      | build debug version (very noisy)     |
+|                            |                                      |
+| NO_FILES                   | do not serve files from a directory  |
+| NO_SSL                     | disable SSL functionality            |
+| NO_CGI                     | disable CGI support                  |
+| NO_CACHING                 | disable caching functionality        |
+|                            |                                      |
+| USE_IPV6                   | enable IPv6 support                  |
+| USE_WEBSOCKET              | enable websocket support             |
+| USE_LUA                    | enable Lua support                   |
+| USE_DUKTAPE                | enable server-side JavaScript        |
+|                            | support by including Duktape         |
+| USE_SERVER_STATS           | enable server statistics support     |
+| MG_EXPERIMENTAL_INTERFACES | include experimental interfaces      |
+|                            |                                      |
+| NO_SSL_DL                  | link against system libssl library   |
+| SQLITE_DISABLE_LFS         | disables large files (Lua only)      |
+| SSL_ALREADY_INITIALIZED    | do not initialize libcrypto          |
+
+Note: If `make` is used (with this [Makefile](https://github.com/civetweb/civetweb/blob/master/Makefile)), you should not pass the `USE_<feature>` flags using `COPT`, but use the `WITH_<feature>` syntax above, since additional features may also use additional source code files.
+
 
 ## Cross Compiling
 

docs/Embedding.md

@@ -1,9 +1,11 @@
 Embedding CivetWeb
 =========
 
-CivetWeb is primarily designed so applications can easily add HTTP and HTTPS server as well as WebSocket functionality.  For example, an application server could use CivetWeb to enable a web service interface for automation or remote control.
+CivetWeb is primarily designed so applications can easily add HTTP and HTTPS server as well as WebSocket (WS and WSS) server functionality.
+For example, a C/C++ application could use CivetWeb to enable a web service and configuration interface, to add a HTML5 data visualization interface, for automation or remote control, as a protocol gateway or as a HTTP/WebSocket client for firewall traversal.
+
+It can also be used as a stand-alone executable. It can deliver static files and offers built-in server side Lua, JavaScript and CGI support. Some instructions how to build the stand-alone server can be found in [Building.md](https://github.com/civetweb/civetweb/blob/master/docs/Building.md).
 
-However, it can also be used as a stand-alone executable. It can deliver static files and offers built-in server side Lua, JavaScript and CGI support. Some instructions how to build the stand-alone server can be found in [Building.md](https://github.com/civetweb/civetweb/blob/master/docs/Building.md).
 
 Files
 ------
@@ -11,11 +13,12 @@ Files
 There is just a small set of files to compile in to the application,
 but if a library is desired, see [Building.md](https://github.com/CivetWeb/CivetWeb/blob/master/docs/Building.md)
 
+
 #### Regarding the INL file extension
 The *INL* file extension represents code that is statically included inline in a source file.  Slightly different from C++ where it means "inline" code which is technically not the same as static code. CivetWeb overloads this extension for the sake of clarity as opposed to having .c extensions on files that should not be directly compiled.
 
-#### HTTP Server Source Files
 
+#### HTTP Server Source Files
 These files constitute the CivetWeb library.  They do not contain a `main` function,
 but all functions required to run a HTTP server.
 
@@ -35,19 +38,18 @@ but all functions required to run a HTTP server.
     - src/mod\_*.inl (modules to access third party components from civetweb)
 
 
-Note: The C++ wrapper uses the official C interface (civetweb.h) and does not add new features to the server. Several features available in the C interface are missing in the C++ interface. While all features should be accessible using the C interface, this is not a design goal of the C++ interface.
+Note: The C++ wrapper uses the official C interface (civetweb.h) without adding any features to the server itself. Several features available in the C interface are missing in the C++ interface. While all features should be accessible using the C interface, this is not a design goal of the C++ interface.
 
 
 #### Additional Source Files for Executables
-
 These files can be used to build a server executable. They contain a `main` function
 starting the HTTP server.
 
-  - Stand-alone C Server
+  - Stand-alone C server
       - src/main.c
-  - Reference embedded C Server
+  - Reference embedded C server
       - examples/embedded\_c/embedded\_c.c
-  - Reference embedded C++ Server
+  - Reference embedded C++ server
       - examples/embedded\_cpp/embedded\_cpp.cpp
 
 Note: The "embedded" example is actively maintained, updated, extended and tested. Other examples in the examples/ folder might be outdated and remain there for reference.
@@ -78,6 +80,27 @@ By default, the server will automatically serve up files like a normal HTTP serv
 Alternative quick start: Have a look at the examples embedded\_c and embedded\_cpp
 
 
+Feature selection
+------
+
+CivetWeb is highly customizable at build time, in addition to configuration at start time.
+
+##### start time options
+Start time options are passed to `mg_start`. They are documented in the [UserManual.md](https://github.com/civetweb/civetweb/blob/master/docs/UserManual.md).
+
+##### callbacks
+Pointers to callback functions are passed to `mg_start` as well. They are documented in [civetweb.h](https://github.com/civetweb/civetweb/blob/master/include/civetweb.h) and the callbacks [API documentation](https://github.com/civetweb/civetweb/blob/master/docs/api/mg_callbacks.md).
+
+##### compiler defines
+Several features can be turned "on" or "off" by setting compile defines. CivetWeb builds with a reasonable default feature set. Optional features not including in the default can be added by adding a `USE\_<feature>` define. Default features can be removed by adding a `NO_<feature>` define. E.g., to build with Lua support, set `#define USE_LUA` (-DUSE_LUA), to build without CGI support set `#define NO_CGI` (-DNO_CGI). A list of feature defines is available in [Building.md](https://github.com/civetweb/civetweb/blob/master/docs/Building.md) - some versions may have additional, undocumented feature defines. Undocumented defines may become unavailable in future versions without notice.
+
+##### externally provided functions
+In some special cases, it might be meaningful to completely replace an internal function in [civetweb.c](https://github.com/civetweb/civetweb/blob/master/src/civetweb.c) with your own implementation.
+Since CivetWeb is free and open source software covered by the MIT license, you can feel free to just edit civetweb.c according to your needs.
+However, this might be annoying when updating the server, pulling new features or bug fixes from the main repository. For some selected functions, it is possible to provide your own implementation using a `MG_EXTERNAL_FUNCTION_<internal_function_name>` define. For details on this mechanism, please look directly into the source code [civetweb.c](https://github.com/civetweb/civetweb/blob/master/src/civetweb.c). Interfaces and even names of internal functions may change without notice - when you use these defines, you have to check this every time you update CivetWeb. It might still be less effort than to apply your patches every time.
+This customization option is currently in an evaluation phase. In case you need additional function defines, please create an issue on GitHub explaining your use case, to discuss if this would be an appropriate solution - in general, other customization options are preferred.
+
+
 Lua Support
 ------
 

src/civetweb.c

@@ -3412,6 +3412,15 @@ mg_difftimespec(const struct timespec *ts_now, const struct timespec *ts_before)
 }
 
 
+#if defined(MG_EXTERNAL_FUNCTION_mg_cry_internal_impl)
+static void mg_cry_internal_impl(const struct mg_connection *conn,
+                                 const char *func,
+                                 unsigned line,
+                                 const char *fmt,
+                                 va_list ap);
+#include "external_mg_cry_internal_impl.inl"
+#else
+
 /* Print error message to the opened error log stream. */
 static void
 mg_cry_internal_impl(const struct mg_connection *conn,
@@ -3485,6 +3494,8 @@ mg_cry_internal_impl(const struct mg_connection *conn,
 	}
 }
 
+#endif /* Externally provided function */
+
 
 static void
 mg_cry_internal_wrap(const struct mg_connection *conn,
@@ -14031,6 +14042,11 @@ header_val(const struct mg_connection *conn, const char *header)
 }
 
 
+#if defined(MG_EXTERNAL_FUNCTION_log_access)
+static void log_access(const struct mg_connection *conn);
+#include "external_log_access.inl"
+#else
+
 static void
 log_access(const struct mg_connection *conn)
 {
@@ -14123,6 +14139,8 @@ log_access(const struct mg_connection *conn)
 	}
 }
 
+#endif /* Externally provided function */
+
 
 /* Verify given socket address against the ACL.
  * Return -1 if ACL is malformed, 0 if address is disallowed, 1 if allowed.

src/mod_lua.inl

@@ -1979,8 +1979,8 @@ handle_lsp_request(struct mg_connection *conn,
 	}
 
 #if defined(MG_USE_OPEN_FILE)
-    /* The "file in memory" feature is going to be removed. For details see
-     * https://groups.google.com/forum/#!topic/civetweb/h9HT4CmeYqI */
+	/* The "file in memory" feature is going to be removed. For details see
+	 * https://groups.google.com/forum/#!topic/civetweb/h9HT4CmeYqI */
 	file_in_memory = filep->access.membuf;
 #else
 	file_in_memory = NULL;