diff options
Diffstat (limited to 'src/civetweb/docs')
83 files changed, 3932 insertions, 0 deletions
diff --git a/src/civetweb/docs/APIReference.md b/src/civetweb/docs/APIReference.md new file mode 100644 index 00000000..58c2faf3 --- /dev/null +++ b/src/civetweb/docs/APIReference.md @@ -0,0 +1,134 @@ +# CivetWeb API Reference + +CivetWeb is often used as HTTP and HTTPS library inside a larger application. +A C API is available to integrate the CivetWeb functionality in a larger +codebase. A C++ wrapper is also available, although it is not guaranteed +that all functionality available through the C API can also be accessed +from C++. This document describes the public C API. Basic usage examples of +the API can be found in [Embedding.md](Embedding.md), as well as in the +examples directory. + +## Macros + +| Macro | Description | +| :--- | :--- | +| **`CIVETWEB_VERSION`** | The current version of the software as a string with the major and minor version number seperated with a dot. For version 1.9, this string will have the value "1.9", for thw first patch of this version "1.9.1". | +| **`CIVETWEB_VERSION_MAJOR`** | The current major version as number, e.g., (1) for version 1.9. | +| **`CIVETWEB_VERSION_MINOR`** | The current minor version as number, e.g., (9) for version 1.9. | +| **`CIVETWEB_VERSION_PATCH`** | The current patch version as number, e.g., (0) for version 1.9 or (1) for version 1.9.1. | + +## Handles + +* `struct mg_context *` +Handle for one instance of the HTTP(S) server. +All functions using `const struct mg_context *` as an argument do not modify a running server instance, but just query information. Functions using a non-const `struct mg_context *` as an argument may modify a server instance (e.g., register a new URI, stop the server, ...). + +* `struct mg_connection *` +Handle for one individual client-server connection. +Functions working with `const struct mg_connection *` operate on data already known to the server without reading data from or sending data to the client. Callbacks using a `const struct mg_connection *` argument are supposed to not call functions from the `mg_read()` and `mg_write()` family. To support a correct application, reading and writing functions require a non-const `struct mg_connection *` connection handle. + +The content of both structures is not defined in the interface - they are only used as opaque pointers (handles). + +## Structures + +* [`struct mg_client_cert;`](api/mg_client_cert.md) +* [`struct mg_client_options;`](api/mg_client_options.md) +* [`struct mg_callbacks;`](api/mg_callbacks.md) +* [`struct mg_form_data_handler;`](api/mg_form_data_handler.md) +* [`struct mg_header;`](api/mg_header.md) +* [`struct mg_option;`](api/mg_option.md) +* [`struct mg_request_info;`](api/mg_request_info.md) +* [`struct mg_server_ports;`](api/mg_server_ports.md) + + +## Library API Functions + +* [`mg_init_library( feature );`](api/mg_init_library.md) +* [`mg_exit_library( feature );`](api/mg_exit_library.md) + +* [`mg_check_feature( feature );`](api/mg_check_feature.md) +* [`mg_version();`](api/mg_version.md) + + +## Server API Functions + +* [`mg_start( callbacks, user_data, options );`](api/mg_start.md) +* [`mg_stop( ctx );`](api/mg_stop.md) + +* [`mg_get_builtin_mime_type( file_name );`](api/mg_get_builtin_mime_type.md) +* [`mg_get_option( ctx, name );`](api/mg_get_option.md) +* [`mg_get_server_ports( ctx, size, ports );`](api/mg_get_server_ports.md) +* [`mg_get_user_data( ctx );`](api/mg_get_user_data.md) +* [`mg_set_auth_handler( ctx, uri, handler, cbdata );`](api/mg_set_auth_handler.md) +* [`mg_set_request_handler( ctx, uri, handler, cbdata );`](api/mg_set_request_handler.md) +* [`mg_set_websocket_handler( ctx, uri, connect_handler, ready_handler, data_handler, close_handler, cbdata );`](api/mg_set_websocket_handler.md) + +* [`mg_lock_context( ctx );`](api/mg_lock_context.md) +* [`mg_unlock_context( ctx );`](api/mg_unlock_context.md) + +* [`mg_get_context( conn );`](api/mg_get_context.md) + +* [`mg_send_http_error( conn, status_code, fmt, ... );`](api/mg_send_http_error.md) + +* [`mg_send_digest_access_authentication_request( conn, realm );`](api/mg_send_digest_access_authentication_request.md) +* [`mg_check_digest_access_authentication( conn, realm, filename );`](api/mg_check_digest_access_authentication.md) +* [`mg_modify_passwords_file( passwords_file_name, realm, user, password );`](api/mg_modify_passwords_file.md) + + +## Client API Functions + +* [`mg_connect_client( host, port, use_ssl, error_buffer, error_buffer_size );`](api/mg_connect_client.md) +* [`mg_connect_websocket_client( host, port, use_ssl, error_buffer, error_buffer_size, path, origin, data_func, close_func, user_data);`](api/mg_connect_websocket_client.md) +* [`mg_websocket_client_write( conn, opcode, data, data_len );`](api/mg_websocket_client_write.md) + +* [`mg_download( host, port, use_ssl, error_buffer, error_buffer_size, fmt, ... );`](api/mg_download.md) + + +## Common API Functions + +* [`mg_close_connection( conn );`](api/mg_close_connection.md) +* [`mg_cry( conn, fmt, ... );`](api/mg_cry.md) + +* [`mg_get_cookie( cookie, var_name, buf, buf_len );`](api/mg_get_cookie.md) +* [`mg_get_header( conn, name );`](api/mg_get_header.md) +* [`mg_get_request_info( conn );`](api/mg_get_request_info.md) +* [`mg_get_response( conn, ebuf, ebuf_len, timeout );`](api/mg_get_response.md) +* [`mg_get_response_code_text( conn, response_code );`](api/mg_get_response_code_text.md) +* [`mg_get_user_connection_data( conn );`](api/mg_get_user_connection_data.md) +* [`mg_get_valid_options();`](api/mg_get_valid_options.md) +* [`mg_get_var( data, data_len, var_name, dst, dst_len );`](api/mg_get_var.md) +* [`mg_get_var2( data, data_len, var_name, dst, dst_len, occurrence );`](api/mg_get_var2.md) +* [`mg_handle_form_request( conn, fdh );`](api/mg_handle_form_request.md) +* [`mg_lock_connection( conn );`](api/mg_lock_connection.md) +* [`mg_md5( buf, ... );`](api/mg_md5.md) +* [`mg_printf( conn, fmt, ... );`](api/mg_printf.md) +* [`mg_read( conn, buf, len );`](api/mg_read.md) +* [`mg_send_chunk( conn, buf, len );`](api/mg_send_chunk.md) +* [`mg_send_file( conn, path );`](api/mg_send_file.md) +* [`mg_send_mime_file( conn, path, mime_type );`](api/mg_send_mime_file.md) +* [`mg_send_mime_file2( conn, path, mime_type, additional_headers );`](api/mg_send_mime_file2.md) +* [`mg_set_user_connection_data( conn, data );`](api/mg_set_user_connection_data.md) +* [`mg_start_thread( f, p );`](api/mg_start_thread.md) +* [`mg_store_body( conn, path );`](api/mg_store_body.md) +* [`mg_strcasecmp( s1, s2 );`](api/mg_strcasecmp.md) +* [`mg_strncasecmp( s1, s2, len );`](api/mg_strncasecmp.md) +* [`mg_unlock_connection( conn );`](api/mg_unlock_connection.md) +* [`mg_url_decode( src, src_len, dst, dst_len, is_form_url_encoded );`](api/mg_url_decode.md) +* [`mg_url_encode( src, dst, dst_len );`](api/mg_url_encode.md) +* [`mg_websocket_write( conn, opcode, data, data_len );`](api/mg_websocket_write.md) +* [`mg_write( conn, buf, len );`](api/mg_write.md) + + +## Diagnosis Functions + +* [`mg_get_system_info( buffer, buf_len );`](api/mg_get_system_info.md) +* [`mg_get_context_info( ctx, buffer, buf_len );`](api/mg_get_context_info.md) +* [`mg_get_connection_info( ctx, idx, buffer, buf_len );`](api/mg_get_context_info.md) + + +## Deprecated: + +* [~~`mg_get_valid_option_names();`~~](api/mg_get_valid_option_names.md) +* [~~`mg_upload( conn, destination_dir );`~~](api/mg_upload.md) + + diff --git a/src/civetweb/docs/Building.md b/src/civetweb/docs/Building.md new file mode 100644 index 00000000..9d7b56ff --- /dev/null +++ b/src/civetweb/docs/Building.md @@ -0,0 +1,216 @@ +Building CivetWeb +========= + +This guide covers the build instructions for the stand-alone web server. +See [Embedding.md](https://github.com/civetweb/civetweb/blob/master/docs/Embedding.md) for information on extending an existing C or C++ application. A brief overview of the source code files can be found in [Embedding.md](https://github.com/civetweb/civetweb/blob/master/docs/Embedding.md) as well. + +#### Where to get the source code? + +The latest version can be found at +https://github.com/civetweb/civetweb + +Released versions can be found at +https://github.com/civetweb/civetweb/releases + + +Building for Windows +--------- + +#### Using Visual Studio + +Open the *VS/civetweb.sln* in Visual Studio. +To include SSL support, you may have to add an extra library for the cryptography support. You might wish to use yaSSL. However, it is GPL licensed or uses a commercial license. See [yaSSL.md](https://github.com/civetweb/civetweb/blob/master/docs/yaSSL.md) for more information. +Alternatively, you might wish to use OpenSSL. See [OpenSSL.md](https://github.com/civetweb/civetweb/blob/master/docs/OpenSSL.md) for more information. + +#### Using MinGW-w64 or TDM-GCC +In the start menu locate and run the "Run terminal" batch file. For TDM-GCC this is named "MinGW Command Prompt". +Navigate to the civetweb sources directory and run: +``` +mingw32-make CC=gcc +``` + +#### Using Qt Creator +Open the Qt Designer project in the Qt folder + +#### Using CMake +Except for the components in the `third_party` folder (e.g., Lua and Duktape), CivetWeb can also be built with CMake. +CMake can be used for all supported operating systems. + + +Building for Linux, BSD, and OSX +--------- + +## Using Make + +``` +make help +``` +Get a list of all supported make option + +``` +make build +``` +compile the code + +``` +make install +``` +Install on the system, Linux only. + +``` +make lib WITH_CPP=1 WITH_IPV6=1 +make clean slib WITH_CPP=1 WITH_LUA=1 WITH_WEBSOCKET=1 +``` +Build the static and shared libraries. +The *WITH_CPP* make option is to include the CivetServer class. +The additional make options configure the library just as it would the application. + +The *slib* option should be done on a separate clean build as position +independent code (PIC) is required for it. Trying to run it after +building the static library or the server will result in a link error. + +``` +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. +``` +make build WITH_LUA=1 +``` + + +| Make Options | Description | +| ------------------------- | ----------------------------------------- | +| 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_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 | +| HTMLDIR=/path | place to install initial web pages | +| DOCUMENT_ROOT=/path | HTMLDIR override, config option, install | +| | nothing is installed here. | +| PORTS=8080 | listening ports override when installing | +| SSL_LIB=libssl.so.0 | use versioned SSL library | +| CRYPTO_LIB=libcrypto.so.0 | system versioned CRYPTO library | +| PREFIX=/usr/local | sets the install directory | +| COPT='-DNO_SSL' | method to insert compile flags | + +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: + +``` +$ make build +$ make -n install PREFIX=/opt/civetweb +``` +Note: The `-n` corresponds to the `--dry-run` option (it does not make any changes): You can see where `make install` would install. Example output of the above command: + +``` +$ make -n install PREFIX=/opt/civetweb +install -d -m 755 "/opt/civetweb/share/doc/civetweb" +install -m 644 resources/itworks.html /opt/civetweb/share/doc/civetweb/index.html +install -m 644 resources/civetweb_64x64.png /opt/civetweb/share/doc/civetweb/ +install -d -m 755 "/opt/civetweb/etc" +install -m 644 resources/civetweb.conf "/opt/civetweb/etc/" +sed -i 's#^document_root.*$#document_root /opt/civetweb/share/doc/civetweb#' "/opt/civetweb/etc/civetweb.conf" +sed -i 's#^listening_ports.*$#listening_ports 8080#' "/opt/civetweb/etc/civetweb.conf" +install -d -m 755 "/opt/civetweb/share/doc/civetweb" +install -m 644 *.md "/opt/civetweb/share/doc/civetweb" +install -d -m 755 "/opt/civetweb/bin" +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. +``` +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 | + +## Cross Compiling + +Take total control with *CC*, *COPT* and *TARGET_OS* as make options. +TARGET_OS is used to determine some compile details as will as code function. +TARGET_OS values should be be one found in *resources/Makefile.in-os*. + +``` +make CC=arm-none-linux-gnueabi-gcc COPT="-march=armv7-a -mfpu=vfp -mfloat-abi=softfp" TARGET_OS=FROG +``` + +## Cocoa DMG Packaging (OSX Only) + +Use the alternate *Makefile.osx* to do the build. The entire build has +to be done using *Makefile.osx* because additional compile and link options +are required. This Makefile has all the same options as the other one plus +one additional *package* rule. + +``` +make -f Makefile.osx package +``` + +Building with Buildroot +--------- + +[Buildroot](http://buildroot.uclibc.org/) is a tool for creating cross compiled file systems. Including Civetweb in buildroot is fairly easy. There is even support for various build options. + +1. First, check if it already there. + - In buildroot, make menuconfig + - Package Selection for the target ---> + - Networking applications ---> + - civetweb +2. If not there, just add it + - copy *Config.in* and *civetweb.mk* from Civetweb's *contrib/buildroot/* to Buildroot's *package/civetweb/* directory. + - In Buildroot's *package/Config.in, insert the following line in were you will know how to find it in the menu. + > ``` source "package/civetweb/Config.in" ``` + + +Building on Android +--------- + +This is a small guide to help you run civetweb on Android, originally +tested on the HTC Wildfire. +Note: You do not need root access to run civetweb on Android. + +- Download the source from the Downloads page. +- Download the Android NDK from [http://developer.android.com/tools/sdk/ndk/index.html](http://developer.android.com/tools/sdk/ndk/index.html) +- Run `/path-to-ndk/ndk-build -C /path-to-civetweb/resources` + That should generate civetweb/lib/armeabi/civetweb +- Using the adb tool (you need to have Android SDK installed for that), + push the generated civetweb binary to `/data/local` folder on device. +- From adb shell, navigate to `/data/local` and execute `./civetweb`. +- To test if the server is running fine, visit your web-browser and + navigate to `http://127.0.0.1:8080` You should see the `Index of /` page. + + +Notes: + +- `jni` stands for Java Native Interface. Read up on Android NDK if you want + to know how to interact with the native C functions of civetweb in Android + Java applications. + + + diff --git a/src/civetweb/docs/Contribution.md b/src/civetweb/docs/Contribution.md new file mode 100644 index 00000000..aa88c14f --- /dev/null +++ b/src/civetweb/docs/Contribution.md @@ -0,0 +1,23 @@ +Contributing to CivetWeb +==== + +Contributions to CivetWeb are welcome, provided all contributions carry the MIT license. + +- Please report issues on GitHub. If the issue you want to report is already reported there, add a note with your specific details to that issue. In case of doubt, please create a new issue. +- If you know how to fix the issue, please create a pull request on GitHub. Please take care your modifications pass the continuous integration checks. These checks are performed automatically when you create a pull request, but it may take some hours until all tests are completed. Please provide a description for every pull request. +- Alternatively, you can post a patch or describe the required modifications in a GitHub issue. +However, a pull request would be preferred. +- Contributor names are listed in CREDITS.md, unless you explicitly state you don't want your name to be listed there. This file is occasionally updated, adding new contributors, using author names from git commits and GitHub comments. + + +- In case your modifications either + 1. modify or extend the API, + 2. affect multi-threading, + 3. imply structural changes, + or + 4. have significant influence on maintenance, + + please first create an issue on GitHub or create a thread on the CivetWeb discussion group, to discuss the planned changed. + +- In case you think you found a security issue that should be evaluated and fixed before public disclosure, feel free to write an email. Although CivetWeb is a fork from Mongoose from 2013, the code bases are different now, so security vulnerabilities of Mongoose usually do not affect CivetWeb. Open an issue for Mongoose vulnerabilities you want to have checked if CivetWeb is affected. + diff --git a/src/civetweb/docs/Embedding.md b/src/civetweb/docs/Embedding.md new file mode 100644 index 00000000..0ffbc230 --- /dev/null +++ b/src/civetweb/docs/Embedding.md @@ -0,0 +1,260 @@ +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. + +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 +------ + +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 + +These files constitute the CivetWeb library. They do not contain a `main` function, +but all functions required to run a HTTP server. + + - HTTP server API + - include/civetweb.h + - C implementation + - src/civetweb.c + - src/md5.inl (MD5 calculation) + - src/sha1.inl (SHA calculation) + - src/handle\_form.inl (HTML form handling functions) + - src/timer.inl (optional timer support) + - Optional: C++ wrapper + - include/CivetServer.h (C++ interface) + - src/CivetServer.cpp (C++ wrapper implementation) + - Optional: Third party components + - src/third\_party/* (third party components, mainly used for the standalone 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. + + +#### 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 + - src/main.c + - Reference embedded C Server + - examples/embedded\_c/embedded\_c.c + - 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. + + +Quick Start +------ + +By default, the server will automatically serve up files like a normal HTTP server. An embedded server is most likely going to overload this functionality. + +### C + - Include the C interface ```civetweb.h```. + - Use `mg_start()` to start the server. + - Use *options* to select the port and document root among other things. + - Use *callbacks* to add your own hooks. + - Use `mg_set_request_handler()` to easily add your own request handlers. + - Use `mg_stop()` to stop the server. + +### C++ + - Note that CivetWeb is Clean C, and C++ interface ```CivetServer.h``` is only a wrapper layer around the C interface. + Not all CivetWeb features available in C are also available in C++. + - Create CivetHandlers for each URI. + - Register the handlers with `CivetServer::addHandler()` + - `CivetServer` starts on contruction and stops on destruction. + - Use contructor *options* to select the port and document root among other things. + - Use constructor *callbacks* to add your own hooks. + +Alternative quick start: Have a look at the examples embedded\_c and embedded\_cpp + + +Lua Support +------ + +Lua is a server side include functionality. Files ending in .lua will be processed with Lua. + +##### Add the following CFLAGS + + - `-DLUA_COMPAT_ALL` + - `-DUSE_LUA` + - `-DUSE_LUA_SQLITE3` + - `-DUSE_LUA_FILE_SYSTEM` + +##### Add the following sources + + - src/mod\_lua.inl + - src/third\_party/lua-5.2.4/src + + lapi.c + + lauxlib.c + + lbaselib.c + + lbitlib.c + + lcode.c + + lcorolib.c + + lctype.c + + ldblib.c + + ldebug.c + + ldo.c + + ldump.c + + lfunc.c + + lgc.c + + linit.c + + liolib.c + + llex.c + + lmathlib.c + + lmem.c + + loadlib.c + + lobject.c + + lopcodes.c + + loslib.c + + lparser.c + + lstate.c + + lstring.c + + lstrlib.c + + ltable.c + + ltablib.c + + ltm.c + + lundump.c + + lvm.c + + lzio.c + - src/third\_party/sqlite3.c + - src/third\_party/sqlite3.h + - src/third\_party/lsqlite3.c + - src/third\_party/lfs.c + - src/third\_party/lfs.h + +This build is valid for Lua version Lua 5.2. It is also possible to build with Lua 5.1 (including LuaJIT) or Lua 5.3. + + +JavaScript Support +------ + +CivetWeb can be built with server side JavaScript support by including the Duktape library. + + +CivetWeb internals +------ + +CivetWeb is multithreaded web server. `mg_start()` function allocates +web server context (`struct mg_context`), which holds all information +about web server instance: + +- configuration options. Note that CivetWeb makes internal copies of + passed options. +- SSL context, if any +- user-defined callbacks +- opened listening sockets +- a queue for accepted sockets +- mutexes and condition variables for inter-thread synchronization + +When `mg_start()` returns, all initialization is guaranteed to be complete +(e.g. listening ports are opened, SSL is initialized, etc). `mg_start()` starts +some threads: a master thread, that accepts new connections, and several +worker threads, that process accepted connections. The number of worker threads +is configurable via `num_threads` configuration option. That number puts a +limit on number of simultaneous requests that can be handled by CivetWeb. +If you embed CivetWeb into a program that uses SSL outside CivetWeb as well, +you may need to initialize SSL before calling `mg_start()`, and set the pre- +processor define `SSL_ALREADY_INITIALIZED`. This is not required if SSL is +used only within CivetWeb. + +When master thread accepts new a connection, a new accepted socket (described +by `struct socket`) it placed into the accepted sockets queue, +which has size of `MGSQLEN` (default 20). +Any idle worker thread can grab accepted sockets from that queue. +If all worker threads are busy, master thread can accept and queue up to +20 more TCP connections, filling up the queue. +In the attempt to queue even more accepted connection, the master thread blocks +until there is space in the queue. When the master thread is blocked on a +full queue, the operating system can also queue incoming connection. +The number is limited by the `listen()` call parameter, +which is `SOMAXCONN` and depends on the platform. + +Worker threads are running in an infinite loop, which in a simplified form +looks something like this: + +```C + static void *worker_thread() { + while (consume_socket()) { + process_new_connection(); + } + } +``` + +Function `consume_socket()` gets a new accepted socket from the CivetWeb socket +queue, atomically removing it from the queue. If the queue is empty, +`consume_socket()` blocks and waits until a new socket is placed in the queue +by the master thread. + +`process_new_connection()` actually processes the +connection, i.e. reads the request, parses it, and performs appropriate action +depending on the parsed request. + +Master thread uses `poll()` and `accept()` to accept new connections on +listening sockets. `poll()` is used to avoid `FD_SETSIZE` limitation of +`select()`. Since there are only a few listening sockets, there is no reason +to use hi-performance alternatives like `epoll()` or `kqueue()`. Worker +threads use blocking IO on accepted sockets for reading and writing data. +All accepted sockets have `SO_RCVTIMEO` and `SO_SNDTIMEO` socket options set +(controlled by the `request_timeout_ms` CivetWeb option, 30 seconds default) +which specifies a read/write timeout on client connections. + + +A minimal example +------ + +Initializing a HTTP server +```C +{ + /* Server context handle */ + struct mg_context *ctx; + + /* Initialize the library */ + mg_init_library(0); + + /* Start the server */ + ctx = mg_start(NULL, 0, NULL); + + /* Add some handler */ + mg_set_request_handler(ctx, "/hello", handler, "Hello world"); + + ... Run the application ... + + /* Stop the server */ + mg_stop(ctx); + + /* Un-initialize the library */ + mg_exit_library(); +} +``` + +A simple callback +```C +static int +handler(struct mg_connection *conn, void *ignored) +{ + const char *msg = "Hello world"; + unsigned long len = (unsigned long)strlen(msg); + + mg_printf(conn, + "HTTP/1.1 200 OK\r\n" + "Content-Length: %lu\r\n" + "Content-Type: text/plain\r\n" + "Connection: close\r\n\r\n", + len); + + mg_write(conn, msg, len); + + return 200; +} +``` + diff --git a/src/civetweb/docs/Installing.md b/src/civetweb/docs/Installing.md new file mode 100644 index 00000000..2476b94f --- /dev/null +++ b/src/civetweb/docs/Installing.md @@ -0,0 +1,38 @@ +Civetweb Install Guide +==== + +This guide covers the distributions for CivetWeb. The latest source code is available at [https://github.com/civetweb/civetweb](https://github.com/civetweb/civetweb). + +Windows +--- + +This pre-built version comes pre-built wit Lua support. Libraries for SSL support are not included due to licensing restrictions; +however, users may add an SSL library themselves. +Instructions for adding SSL support can be found in [https://github.com/civetweb/civetweb/tree/master/docs](https://github.com/civetweb/civetweb/tree/master/docs) + +1. In case the Visual C++ Redistributable are not already installed: + 32 Bit Version: Install the [Redistributable for Visual Studio 2010](http://www.microsoft.com/en-us/download/details.aspx?id=8328) + 64 Bit Version: Install the [Redistributable for Visual Studio 2015](http://www.microsoft.com/en-us/download/details.aspx?id=48145) + Note: The required version of the Redistributables may vary, depending on the CivetWeb version. +2. Download latest *civetweb-win.zip* from [SourceForge](https://sourceforge.net/projects/civetweb/files/) +3. When started, Civetweb puts itself into the tray. + +OS X +--- + +This pre-built version comes with Lua, IPV6 and SSL support. + +1. Download the latest *Civetweb.dmg* from [SourceForge](https://sourceforge.net/projects/civetweb/files/) +2. Click on the it and look for the attachment in the finder. +4. Drag Civetweb to the Applications folder. +5. When started, Civetweb puts itself into top menu. + +Linux +--- + +1. Download the latest *civetweb.tar.gz* from [SourceForge](https://sourceforge.net/projects/civetweb/files/) +2. Open archive and change to the new directory. +3. make help +4. make +5. make install +6. Run the program ```/usr/local/bin/civetweb```, it will use the configuration file */usr/local/etc/civetweb.conf*. diff --git a/src/civetweb/docs/Interface_Changes_1.10.md b/src/civetweb/docs/Interface_Changes_1.10.md new file mode 100644 index 00000000..16bc7dde --- /dev/null +++ b/src/civetweb/docs/Interface_Changes_1.10.md @@ -0,0 +1,86 @@ +# Interface changes + +## Proposed interface changes for 1.10 + +Status: To be discussed + +### Server interface + +#### mg\_start / mg\_init\_library + +Calling mg\_init\_library is recommended before calling mg\_start. + +Compatibility: +Initially, mg\_init\_library will be called implicitly if it has +not been called before mg\_start. +If mg\_init\_library was not called, mg\_stop may leave memory leaks. + +#### mg\_websocket\_write functions + +Calling mg\_lock\_connection is no longer called implicitly +in mg\_websocket\_write functions. +If you use websocket write functions them from two threads, +you must call mg\_lock\_connection explicitly, just like for any +other connection. + +This is an API harmonization issue. + +Compatibility: +If a websocket connection was used in only one thread, there is +no incompatibility. If a websocket connection was used in multiple +threads, the user has to add the mg\_lock\_connection before and +the mg\_unlock\_connection after the websocket write call. + +#### open\_file member of mg\_callbacks + +This member is going to be removed. +It is superseeded by mg\_add\_request\_handler. + +Compatibility: +Current code using open\_file needs to be changed. +Instructions how to do this will be provided. + + +### Client interface + + +#### mg\_init\_library + +Calling mg\_init\_library is required before calling any client +function. In particular, the TLS initialization must be done +before using mg\_connect\_client\_secure. + +Compatibility: +Some parts of the client interface did not work, if mg\_start +was not called before. Now server and client become independent. + +#### mg\_connect\_client (family) + +mg_connect_client needs several new parameters (options). + +Details are to be defined. + +mg_connect_client and mg_download should return a different kind of +mg_connection than used in server callbacks. At least, there should +be a function mg_get_response_info, instead of using +mg_get_request_info, and getting the HTTP response code from the +server by looking into the uri member of struct mg_request_info. + + +### `size_t` in all interface + +Having `size_t` in interfaces while building for 32 and 64 bit +complicates maintenance in an unnecessary way +(see [498](https://github.com/civetweb/civetweb/issues/498)). + +Replace all data sizes by 64 bit integers. + + +### Pattern definition + +The current definition of pattern matching is problematic +(see [499](https://github.com/civetweb/civetweb/issues/499)). + +Find and implement a new definition. + + diff --git a/src/civetweb/docs/OpenSSL.md b/src/civetweb/docs/OpenSSL.md new file mode 100644 index 00000000..1f01cca7 --- /dev/null +++ b/src/civetweb/docs/OpenSSL.md @@ -0,0 +1,153 @@ +Adding OpenSSL Support +===== + +Civetweb supports *HTTPS* connections using the OpenSSL transport layer +security (TLS) library. OpenSSL is a free, open source library (see +http://www.openssl.org/). + + +Getting Started +---- + +- Install OpenSSL on your system. There are OpenSSL install packages for all + major Linux distributions as well as a setup for Windows. +- The default build configuration of the civetweb web server will load the + required OpenSSL libraries, if a HTTPS certificate has been configured. + + +Civetweb Configuration +---- + +The configuration file must contain an https port, identified by a letter 's' +attached to the port number. +To serve http and https from their standard ports use the following line in +the configuration file 'civetweb.conf': +<pre> + listening_ports 80, 443s +</pre> +To serve only https use: +<pre> + listening_ports 443s +</pre> + +Furthermore the SSL certificate file must be set: +<pre> + ssl_certificate d:\civetweb\certificate\server.pem +</pre> + + +Creating a self signed certificate +---- + +OpenSSL provides a command line interface, that can be used to create the +certificate file required by civetweb (server.pem). + +One can use the following steps in Windows (in Linux replace "copy" by "cp" +and "type" by "cat"): + +<pre> + openssl genrsa -des3 -out server.key 1024 + + openssl req -new -key server.key -out server.csr + + copy server.key server.key.orig + + openssl rsa -in server.key.orig -out server.key + + openssl x509 -req -days 3650 -in server.csr -signkey server.key -out server.crt + + copy server.crt server.pem + + type server.key >> server.pem +</pre> + +The server.pem file created must contain a 'CERTIFICATE' section as well as a +'RSA PRIVATE KEY' section. It should look like this (x represents BASE64 +encoded data): + +<pre> +-----BEGIN CERTIFICATE----- +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxx +-----END CERTIFICATE----- +-----BEGIN RSA PRIVATE KEY----- +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx +-----END RSA PRIVATE KEY----- +</pre> + + +Including a certificate from a certificate authority +---- + +CivetWeb requires one certificate file in PEM format. +If you got multiple files from your certificate authority, +you need to copy their content together into one file. +Make sure the file has one section BEGIN RSA PRIVATE KEY / +END RSA PRIVATE KEY, and at least one section +BEGIN CERTIFICATE / END CERTIFICATE. +In case you received a file with a section +BEGIN PRIVATE KEY / END PRIVATE KEY, +you may get a suitable file by adding the letters RSA manually. + +Set the "ssl_certificate" configuration parameter to the +file name (including path) of the resulting *.pem file. + +The file must look like the file in the section +"Creating a self signed certificate", but it will have several +BEGIN CERTIFICATE / END CERTIFICATE sections. + + +Common Problems +---- + +In case the OpenSSL configuration is not set up correctly, the server will not +start. Configure an error log file in 'civetweb.conf' to get more information: +<pre> + error_log_file error.log +</pre> + +Check the content of 'error.log': + +<pre> +load_dll: cannot load libeay32.*/libcrypto.*/ssleay32.*/libssl.* +</pre> +This error message means, the SSL library has not been installed (correctly). +For Windows you might use the pre-built binaries. A link is available at the +OpenSSL project home page (http://www.openssl.org/related/binaries.html). +Choose the windows system folder as installation directory - this is the +default location. + +<pre> +set_ssl_option: cannot open server.pem: error:PEM routines:*:PEM_read_bio:no start line +set_ssl_option: cannot open server.pem: error:PEM routines:*:PEM_read_bio:bad end line +</pre> +These error messages indicate, that the format of the ssl_certificate file does +not match the expectations of the SSL library. The PEM file must contain both, +a 'CERTIFICATE' and a 'RSA PRIVATE KEY' section. It should be a strict ASCII +file without byte-order marks. +The instructions above may be used to create a valid ssl_certificate file. + + diff --git a/src/civetweb/docs/README.md b/src/civetweb/docs/README.md new file mode 100644 index 00000000..9494409f --- /dev/null +++ b/src/civetweb/docs/README.md @@ -0,0 +1,42 @@ + CivetWeb +======= + +CivetWeb is an easy to use, powerful, C/C++ embeddable web server with optional CGI, SSL and Lua support. + +CivetWeb can be used by developers as a library, to add web server functionality to an existing application. +CivetWeb uses an [MIT license](https://github.com/civetweb/civetweb/blob/master/LICENSE.md). + +It can also be used by end users as a stand-alone web server. It is available as single executable, no installation is required. + +The current stable version is 1.9.1 - [release notes](https://github.com/civetweb/civetweb/blob/master/RELEASE_NOTES.md) + + +End users can download CivetWeb at SourceForge +[https://sourceforge.net/projects/civetweb/](https://sourceforge.net/projects/civetweb/) + +Developers can contribute to CivetWeb via GitHub +[https://github.com/civetweb/civetweb](https://github.com/civetweb/civetweb) + +Trouble tickets should be filed on GitHub +[https://github.com/civetweb/civetweb/issues](https://github.com/civetweb/civetweb/issues) + +Announcements are at Google Groups +[https://groups.google.com/d/forum/civetweb](https://groups.google.com/d/forum/civetweb) + +While older support question and discussion threads have been at [Google groups](https://groups.google.com/d/forum/civetweb), most newer ones are [GitHub issues](https://github.com/civetweb/civetweb/issues). + +Source releases can be found on GitHub +[https://github.com/civetweb/civetweb/releases](https://github.com/civetweb/civetweb/releases) + + +Documentation +--------------- + +- [Installing.md](Installing.md) - Install Guide (for end users using pre-built binaries) +- [UserManual.md](UserManual.md) - End User Guide +- [Building.md](Building.md) - Building the Server (quick start guide) +- [Embedding.md](Embedding.md) - Embedding (how to add HTTP support to an existing application) +- [OpenSSL.md](OpenSSL.md) - Adding HTTPS (SSL/TLS) support using OpenSSL. +- [API documentation](api) - Additional documentation on the civetweb application programming interface ([civetweb.h](https://github.com/civetweb/civetweb/blob/master/include/civetweb.h)). + +[Authors](https://github.com/civetweb/civetweb/blob/master/CREDITS.md) diff --git a/src/civetweb/docs/UserManual.md b/src/civetweb/docs/UserManual.md new file mode 100644 index 00000000..3acf4927 --- /dev/null +++ b/src/civetweb/docs/UserManual.md @@ -0,0 +1,814 @@ + +Overview +===== + +Civetweb is small and easy to use web server. +It may be embedded into C/C++ host applications or used as a stand-alone +server. See `Embedding.md` for information on embedding civetweb into +host applications. + +The stand-alone server is self-contained, and does not require any external +software to run. Some Windows users may need to install the +[Visual C++ Redistributable](http://www.microsoft.com/en-us/download/details.aspx?id=30679). + +Installation +---- + +On Windows, UNIX and Mac, the civetweb stand-alone executable may be started +from the command line. +Running `civetweb` in a terminal, optionally followed by configuration parameters +(`civetweb [OPTIONS]`) or a configuration file name (`civetweb [config_file_name]`), +starts the web server. + +For UNIX and Mac, civetweb does not detach from the terminal. +Pressing `Ctrl-C` keys will stop the server. + +On Windows, civetweb iconifies itself to the system tray icon when started. +Right-click on the icon pops up a menu, where it is possible to stop +civetweb, or configure it, or install it as Windows service. + +When started without options, the server exposes the local directory at +[http](http://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol) port 8080. +Thus, the easiest way to share a folder on Windows is to copy `civetweb.exe` +to this folder, double-click the exe, and launch a browser at +[http://localhost:8080](http://localhost:8080). Note that 'localhost' should +be changed to a machine's name if a folder is accessed from other computer. + +When started, civetweb first searches for the configuration file. +If configuration file is specified explicitly in the command line, i.e. +`civetweb path_to_config_file`, then specified configuration file is used. +Otherwise, civetweb would search for file `civetweb.conf` in the same directory +the executable is located, and use it. This configuration file is optional. + +The configuration file is a sequence of lines, each line containing one +command line argument name and the corresponding value. +Empty lines, and lines beginning with `#`, are ignored. +Here is the example of `civetweb.conf` file: + + document_root c:\www + listening_ports 80,443s + ssl_certificate c:\civetweb\ssl_cert.pem + +When a configuration file is used, additional command line arguments may +override the configuration file settings. +All command line arguments must start with `-`. + +For example: The above `civetweb.conf` file is used, and civetweb started as +`civetweb -document_root D:\web`. Then the `D:\web` directory will be served +as document root, because command line options take priority over the +configuration file. The configuration options section below provides a good +overview of the Civetweb features. + +Note that configuration options on the command line must start with `-`, +but their names are the same as in the config file. All option names are +listed in the next section. Thus, the following two setups are equivalent: + + # Using command line arguments + $ civetweb -listening_ports 1234 -document_root /var/www + + # Using config file + $ cat civetweb.conf + listening_ports 1234 + document_root /var/www + $ civetweb + +Civetweb can also be used to modify `.htpasswd` passwords files: + + civetweb -A <htpasswd_file> <realm> <user> <passwd> + +Unlike other web servers, civetweb does not require CGI scripts to be located +in a special directory. CGI scripts can be anywhere. CGI (and SSI) files are +recognized by the file name pattern. Civetweb uses shell-like glob +patterns. Pattern match starts at the beginning of the string, so essentially +patterns are prefix patterns. Syntax is as follows: + + ** Matches everything + * Matches everything but slash character, '/' + ? Matches any character + $ Matches the end of the string + | Matches if pattern on the left side or the right side matches. + +All other characters in the pattern match themselves. Examples: + + **.cgi$ Any string that ends with .cgi + /foo Any string that begins with /foo + **a$|**b$ Any string that ends with a or b + +# Configuration Options + +Below is a list of configuration options understood by Civetweb. +Every option is followed by it's default value. If a default value is not +present, then the default is empty. + +### cgi\_pattern `**.cgi$|**.pl$|**.php$` +All files that match `cgi_pattern` are treated as CGI files. Default pattern +allows CGI files be anywhere. To restrict CGIs to a certain directory, +use `/path/to/cgi-bin/**.cgi` as pattern. Note that the full file path is +matched against the pattern, not the URI. + +### cgi\_environment +Extra environment variables to be passed to the CGI script in +addition to standard ones. The list must be comma-separated list +of name=value pairs, like this: `VARIABLE1=VALUE1,VARIABLE2=VALUE2`. + +### put\_delete\_auth\_file +Passwords file for PUT and DELETE requests. Without password file, it will not +be possible to, PUT new files to the server or DELETE existing ones. PUT and +DELETE requests might still be handled by Lua scripts and CGI paged. + +### cgi\_interpreter +Path to an executable to use as CGI interpreter for __all__ CGI scripts +regardless of the script file extension. If this option is not set (which is +the default), Civetweb looks at first line of a CGI script, +[shebang line](http://en.wikipedia.org/wiki/Shebang_(Unix\)), for an +interpreter (not only on Linux and Mac but also for Windows). + +For example, if both PHP and Perl CGIs are used, then +`#!/path/to/php-cgi.exe` and `#!/path/to/perl.exe` must be first lines of the +respective CGI scripts. Note that paths should be either full file paths, +or file paths relative to the current working directory of the civetweb +server. If civetweb is started by mouse double-click on Windows, the current +working directory is the directory where the civetweb executable is located. + +If all CGIs use the same interpreter, for example they are all PHP, it is +more efficient to set `cgi_interpreter` to the path to `php-cgi.exe`. +The shebang line in the CGI scripts can be omitted in this case. +Note that PHP scripts must use `php-cgi.exe` as executable, not `php.exe`. + +### protect\_uri +Comma separated list of URI=PATH pairs, specifying that given +URIs must be protected with password files specified by PATH. +All Paths must be full file paths. + +### authentication\_domain `mydomain.com` +Authorization realm used for HTTP digest authentication. This domain is +used in the encoding of the `.htpasswd` authorization files as well. +Changing the domain retroactively will render the existing passwords useless. + +### enable\_auth\_domain\_check `yes` +When using absolute URLs, verify the host is identical to the authentication\_domain. If enabled, requests to absolute URLs will only be processed +if they are directed to the domain. If disabled, absolute URLs to any host +will be accepted. + +### ssi\_pattern `**.shtml$|**.shtm$` +All files that match `ssi_pattern` are treated as Server Side Includes (SSI). + +SSI is a simple interpreted server-side scripting language which is most +commonly used to include the contents of another file into a web page. +It can be useful when it is desirable to include a common piece +of code throughout a website, for example, headers and footers. + +In order for a webpage to recognize an SSI-enabled HTML file, the filename +should end with a special extension, by default the extension should be +either `.shtml` or `.shtm`. These extentions may be changed using the +`ssi_pattern` option. + +Unknown SSI directives are silently ignored by civetweb. Currently, two SSI +directives are supported, `<!--#include ...>` and +`<!--#exec "command">`. Note that the `<!--#include ...>` directive supports +three path specifications: + + <!--#include virtual="path"> Path is relative to web server root + <!--#include abspath="path"> Path is absolute or relative to + web server working dir + <!--#include file="path">, Path is relative to current document + <!--#include "path"> + +The `include` directive may be used to include the contents of a file or the +result of running a CGI script. The `exec` directive is used to execute a +command on a server, and show the output that would have been printed to +stdout (the terminal window) otherwise. Example: + + <!--#exec "ls -l" --> + +For more information on Server Side Includes, take a look at the Wikipedia: +[Server Side Includes](http://en.wikipedia.org/wiki/Server_Side_Includes) + +### throttle +Limit download speed for clients. `throttle` is a comma-separated +list of key=value pairs, where key could be: + + * limit speed for all connections + x.x.x.x/mask limit speed for specified subnet + uri_prefix_pattern limit speed for given URIs + +The value is a floating-point number of bytes per second, optionally +followed by a `k` or `m` character, meaning kilobytes and +megabytes respectively. A limit of 0 means unlimited rate. The +last matching rule wins. Examples: + + *=1k,10.0.0.0/8=0 limit all accesses to 1 kilobyte per second, + but give connections the from 10.0.0.0/8 subnet + unlimited speed + + /downloads/=5k limit accesses to all URIs in `/downloads/` to + 5 kilobytes per second. All other accesses are unlimited + +### access\_log\_file +Path to a file for access logs. Either full path, or relative to the current +working directory. If absent (default), then accesses are not logged. + +### enable\_directory\_listing `yes` +Enable directory listing, either `yes` or `no`. + +### error\_log\_file +Path to a file for error logs. Either full path, or relative to the current +working directory. If absent (default), then errors are not logged. + +### global\_auth\_file +Path to a global passwords file, either full path or relative to the current +working directory. If set, per-directory `.htpasswd` files are ignored, +and all requests are authorized against that file. + +The file has to include the realm set through `authentication_domain` and the +password in digest format: + + user:realm:digest + test:test.com:ce0220efc2dd2fad6185e1f1af5a4327 + +Password files may be generated using `civetweb -A` as explained above, or +online tools e.g. [this generator](http://www.askapache.com/online-tools/htpasswd-generator). + +### index\_files `index.xhtml,index.html,index.htm,index.cgi,index.shtml,index.php` +Comma-separated list of files to be treated as directory index files. +If more than one matching file is present in a directory, the one listed to the left +is used as a directory index. + +In case built-in Lua support has been enabled, `index.lp,index.lsp,index.lua` +are additional default index files, ordered before `index.cgi`. + +### enable\_keep\_alive `no` +Enable connection keep alive, either `yes` or `no`. + +Allows clients to reuse TCP connection for subsequent HTTP requests, +which improves performance. +For this to work when using request handlers it is important to add the +correct Content-Length HTTP header for each request. If this is forgotten the +client will time out. + +Note: If you set keep\_alive to `yes`, you should set keep\_alive\_timeout\_ms +to some value > 0 (e.g. 500). If you set keep\_alive to `no`, you should set +keep\_alive\_timeout\_ms to 0. Currently, this is done as a default value, +but this configuration is redundant. In a future version, the keep\_alive +configuration option might be removed and automatically set to `yes` if +a timeout > 0 is set. + +### access\_control\_list +An Access Control List (ACL) allows restrictions to be put on the list of IP +addresses which have access to the web server. In the case of the Civetweb +web server, the ACL is a comma separated list of IP subnets, where each +subnet is pre-pended by either a `-` or a `+` sign. A plus sign means allow, +where a minus sign means deny. If a subnet mask is omitted, such as `-1.2.3.4`, +this means to deny only that single IP address. + +Subnet masks may vary from 0 to 32, inclusive. The default setting is to allow +all accesses. On each request the full list is traversed, and +the last match wins. Examples: + + -0.0.0.0/0,+192.168/16 deny all accesses, only allow 192.168/16 subnet + +To learn more about subnet masks, see the +[Wikipedia page on Subnetwork](http://en.wikipedia.org/wiki/Subnetwork). + +### extra\_mime\_types +Extra mime types, in tha form `extension1=type1,exten-sion2=type2,...`. +See the [Wikipedia page on Internet media types](http://en.wikipedia.org/wiki/Internet_media_type). +Extension must include a leading dot. Example: +`.cpp=plain/text,.java=plain/text` + +### listening\_ports `8080` +Comma-separated list of ports to listen on. If the port is SSL, a +letter `s` must be appended, for example, `80,443s` will open +port 80 and port 443, and connections on port 443 will be SSL-ed. +For non-SSL ports, it is allowed to append letter `r`, meaning 'redirect'. +Redirect ports will redirect all their traffic to the first configured +SSL port. For example, if `listening_ports` is `80r,443s`, then all +HTTP traffic coming at port 80 will be redirected to HTTPS port 443. + +It is possible to specify an IP address to bind to. In this case, +an IP address and a colon must be pre-pended to the port number. +For example, to bind to a loopback interface on port 80 and to +all interfaces on HTTPS port 443, use `127.0.0.1:80,443s`. + +If the server is built with IPv6 support, `[::]:8080` can be used to +listen to IPv6 connections to port 8080. IPv6 addresses of network +interfaces can be specified as well, +e.g. `[::1]:8080` for the IPv6 loopback interface. + +[::]:80 will bind to port 80 IPv6 only. In order to use port 80 for +all interfaces, both IPv4 and IPv6, use either the configuration +`80,[::]:80` (create one socket for IPv4 and one for IPv6 only), +or `+80` (create one socket for both, IPv4 and IPv6). +The `+`-notation to use IPv4 and IPv6 will only work in no network +interface is specified. Depending on your operating system version +and IPv6 network environment, some configurations might not work +as expected, so you have to test to find the configuration most +suitable for your needs. In case `+80` does not work for your +environment, you need to use `80,[::]:80`. + +It is possible to use network interface addresses (e.g., `192.0.2.3:80`, +`[2001:0db8::1234]:80`). To get a list of available network interface +addresses, use `ipconfig` (in a `cmd` window in Windows) or `ifconfig` +(in a Linux shell). +Alternatively, you could use the hostname for an interface. Check the +hosts file of your operating system for a proper hostname +(for Windows, usually found in C:\Windows\System32\drivers\etc\, +for most Linux distributions: /etc/hosts). E.g., to bind the IPv6 +local host, you could use `ip6-localhost:80`. This translates to +`[::1]:80`. Beside the hosts file, there are several other name +resolution services. Using your hostname might bind you to the +localhost or an external interface. You could also try `hostname.local`, +if the proper network services are installed (Zeroconf, mDNS, Bonjour, +Avahi). When using a hostname, you need to test in your particular network +environment - in some cases, you might need to resort to a fixed IP address. + +### document\_root `.` +A directory to serve. By default, the current working directory is served. +The current directory is commonly referenced as dot (`.`). +It is recommended to use an absolute path for document\_root, in order to +avoid accidentally serving the wrong directory. + +### ssl\_certificate +Path to the SSL certificate file. This option is only required when at least +one of the `listening\_ports` is SSL. The file must be in PEM format, +and it must have both, private key and certificate, see for example +[ssl_cert.pem](https://github.com/civetweb/civetweb/blob/master/resources/ssl_cert.pem) +A description how to create a certificate can be found in doc/OpenSSL.md + +### num\_threads `50` +Number of worker threads. Civetweb handles each incoming connection in a +separate thread. Therefore, the value of this option is effectively the number +of concurrent HTTP connections Civetweb can handle. + +### run\_as\_user +Switch to given user credentials after startup. Usually, this option is +required when civetweb needs to bind on privileged ports on UNIX. To do +that, civetweb needs to be started as root. From a security point of view, +running as root is not advisable, therefore this option can be used to drop +privileges. Example: + + civetweb -listening_ports 80 -run_as_user webserver + +### url\_rewrite\_patterns +Comma-separated list of URL rewrites in the form of +`uri_pattern=file_or_directory_path`. When Civetweb receives any request, +it constructs the file name to show by combining `document_root` and the URI. +However, if the rewrite option is used and `uri_pattern` matches the +requested URI, then `document_root` is ignored. Instead, +`file_or_directory_path` is used, which should be a full path name or +a path relative to the web server's current working directory. Note that +`uri_pattern`, as all civetweb patterns, is a prefix pattern. + +This makes it possible to serve many directories outside from `document_root`, +redirect all requests to scripts, and do other tricky things. For example, +to redirect all accesses to `.doc` files to a special script, do: + + civetweb -url_rewrite_patterns **.doc$=/path/to/cgi-bin/handle_doc.cgi + +Or, to imitate support for user home directories, do: + + civetweb -url_rewrite_patterns /~joe/=/home/joe/,/~bill=/home/bill/ + +### hide\_files\_patterns +A pattern for the files to hide. Files that match the pattern will not +show up in directory listing and return `404 Not Found` if requested. Pattern +must be for a file name only, not including directory names. Example: + + civetweb -hide_files_patterns secret.txt|**.hide + +Note: hide\_file\_patterns uses the pattern described above. If you want to +hide all files with a certain extension, make sure to use **.extension +(not just *.extension). + +### request\_timeout\_ms `30000` +Timeout for network read and network write operations, in milliseconds. +If a client intends to keep long-running connection, either increase this +value or (better) use keep-alive messages. + +### keep\_alive\_timeout\_ms `500` or `0` +Idle timeout between two requests in one keep-alive connection. +If keep alive is enabled, multiple requests using the same connection +are possible. This reduces the overhead for opening and closing connections +when loading several resources from one server, but it also blocks one port +and one thread at the server during the lifetime of this connection. +Unfortunately, browsers do not close the keep-alive connection after loading +all resources required to show a website. +The server closes a keep-alive connection, if there is no additional request +from the client during this timeout. + +Note: if enable\_keep\_alive is set to `no` the value of +keep\_alive\_timeout\_ms should be set to `0`, if enable\_keep\_alive is set +to `yes`, the value of keep\_alive\_timeout\_ms must be >0. +Currently keep\_alive\_timeout\_ms is ignored if enable\_keep\_alive is no, +but future versions my drop the enable\_keep\_alive configuration value and +automatically use keep-alive if keep\_alive\_timeout\_ms is not 0. + +### linger\_timeout\_ms +Set TCP socket linger timeout before closing sockets (SO\_LINGER option). +The configured value is a timeout in milliseconds. Setting the value to 0 +will yield in abortive close (if the socket is closed from the server side). +Setting the value to -1 will turn off linger. +If the value is not set (or set to -2), CivetWeb will not set the linger +option at all. + +Note: For consistency with other timeouts, the value is configured in +milliseconds. However, the TCP socket layer usually only offers a timeout in +seconds, so the value should be an integer multiple of 1000. + +### lua\_preload\_file +This configuration option can be used to specify a Lua script file, which +is executed before the actual web page script (Lua script, Lua server page +or Lua websocket). It can be used to modify the Lua environment of all web +page scripts, e.g., by loading additional libraries or defining functions +required by all scripts. +It may be used to achieve backward compatibility by defining obsolete +functions as well. + +### lua\_script\_pattern `"**.lua$` +A pattern for files that are interpreted as Lua scripts by the server. +In contrast to Lua server pages, Lua scripts use plain Lua syntax. +An example can be found in the test directory. + +### lua\_server\_page\_pattern `**.lp$|**.lsp$` +Files matching this pattern are treated as Lua server pages. +In contrast to Lua scripts, the content of a Lua server pages is delivered +directly to the client. Lua script parts are delimited from the standard +content by including them between <? and ?> tags. +An example can be found in the test directory. + +### lua\_background\_script +Experimental feature, and subject to change. +Run a Lua script in the background, independent from any connection. +The script is started before network access to the server is available. +It can be used to prepare the document root (e.g., update files, compress +files, ...), check for external resources, remove old log files, etc. + +The Lua state remains open until the server is stopped. +In the future, some callback functions will be available to notify the +script on changes of the server state. See example lua script : +[background.lua](https://github.com/civetweb/civetweb/blob/master/test/background.lua). + +Additional functions available in background script : +sleep, root path, script name, isterminated + +### lua\_background\_script\_params `param1=1,param2=2` +Can add dynamic parameters to background script. +Parameters mapped to global 'mg' table 'params' field. + +### websocket\_root +In case civetweb is built with Lua and websocket support, Lua scripts may +be used for websockets as well. Since websockets use a different URL scheme +(ws, wss) than other http pages (http, https), the Lua scripts used for +websockets may also be served from a different directory. By default, +the document_root is used as websocket_root as well. + + +### access\_control\_allow\_origin `*` +Access-Control-Allow-Origin header field, used for cross-origin resource +sharing (CORS). +See the [Wikipedia page on CORS](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing). + + +### access\_control\_allow\_methods `*` +Access-Control-Allow-Methods header field, used for cross-origin resource +sharing (CORS) pre-flight requests. +See the [Wikipedia page on CORS](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing). + +If set to an empty string, pre-flights will not be supported directly by the server, +but scripts may still support pre-flights by handling the OPTIONS method properly. +If set to "*", the pre-flight will allow whatever method has been requested. +If set to a comma separated list of valid HTTP methods, the pre-flight will return +exactly this list as allowed method. +If set in any other way, the result is unspecified. + + +### access\_control\_allow\_headers `*` +Access-Control-Allow-Headers header field, used for cross-origin resource +sharing (CORS) pre-flight requests. +See the [Wikipedia page on CORS](http://en.wikipedia.org/wiki/Cross-origin_resource_sharing). + +If set to an empty string, pre-flights will not allow additional headers. +If set to "*", the pre-flight will allow whatever headers have been requested. +If set to a comma separated list of valid HTTP headers, the pre-flight will return +exactly this list as allowed headers. +If set in any other way, the result is unspecified. + + +### error\_pages +This option may be used to specify a directory for user defined error pages. +The error pages may be specified for an individual http status code (e.g., +404 - page requested by the client not found), a group of http status codes +(e.g., 4xx - all client errors) or all errors. The corresponding error pages +must be called error404.ext, error4xx.ext or error.ext, whereas the file +extention may be one of the extentions specified for the index_files option. +See the [Wikipedia page on HTTP status codes](http://en.wikipedia.org/wiki/HTTP_status_code). + +### tcp\_nodelay `0` +Enable TCP_NODELAY socket option on client connections. + +If set the socket option will disable Nagle's algorithm on the connection +which means that packets will be sent as soon as possible instead of waiting +for a full buffer or timeout to occur. + + 0 Keep the default: Nagel's algorithm enabled + 1 Disable Nagel's algorithm for all sockets + +### static\_file\_max\_age `3600` +Set the maximum time (in seconds) a cache may store a static files. + +This option will set the `Cache-Control: max-age` value for static files. +Dynamically generated content, i.e., content created by a script or callback, +must send cache control headers by themselfes. + +A value >0 corresponds to a maximum allowed caching time in seconds. +This value should not exceed one year (RFC 2616, Section 14.21). +A value of 0 will send "do not cache" headers for all static files. +For values <0 and values >31622400, the behavior is undefined. + +### strict\_transport\_security\_max\_age + +Set the `Strict-Transport-Security` header, and set the `max-age` value. +This instructs web browsers to interact with the server only using HTTPS, +never by HTTP. If set, it will be sent for every request handled directly +by the server, except scripts (CGI, Lua, ..) and callbacks. They must +send HTTP headers on their own. + +The time is specified in seconds. If this configuration is not set, +or set to -1, no `Strict-Transport-Security` header will be sent. +For values <-1 and values >31622400, the behavior is undefined. + +### decode\_url `yes` +URL encoded request strings are decoded in the server, unless it is disabled +by setting this option to `no`. + +### ssl\_verify\_peer `no` +Enable client's certificate verification by the server. + +### ssl\_ca\_path +Name of a directory containing trusted CA certificates. Each file in the +directory must contain only a single CA certificate. The files must be named +by the subject name’s hash and an extension of “.0”. If there is more than one +certificate with the same subject name they should have extensions ".0", ".1", +".2" and so on respectively. + +### ssl\_ca\_file +Path to a .pem file containing trusted certificates. The file may contain +more than one certificate. + +### ssl\_verify\_depth `9` +Sets maximum depth of certificate chain. If client's certificate chain is longer +than the depth set here connection is refused. + +### ssl\_default\_verify\_paths `yes` +Loads default trusted certificates locations set at openssl compile time. + +### ssl\_cipher\_list +List of ciphers to present to the client. Entries should be separated by +colons, commas or spaces. + + ALL All available ciphers + ALL:!eNULL All ciphers excluding NULL ciphers + AES128:!MD5 AES 128 with digests other than MD5 + +See [this entry](https://www.openssl.org/docs/manmaster/apps/ciphers.html) in +OpenSSL documentation for full list of options and additional examples. + +### ssl\_protocol\_version `0` +Sets the minimal accepted version of SSL/TLS protocol according to the table: + +Protocols | Value +------------ | ------------- +SSL2+SSL3+TLS1.0+TLS1.1+TLS1.2 | 0 +SSL3+TLS1.0+TLS1.1+TLS1.2 | 1 +TLS1.0+TLS1.1+TLS1.2 | 2 +TLS1.1+TLS1.2 | 3 +TLS1.2 | 4 + +### ssl\_short\_trust `no` +Enables the use of short lived certificates. This will allow for the certificates +and keys specified in `ssl_certificate`, `ssl_ca_file` and `ssl_ca_path` to be +exchanged and reloaded while the server is running. + +In an automated environment it is advised to first write the new pem file to +a different filename and then to rename it to the configured pem file name to +increase performance while swapping the certificate. + +Disk IO performance can be improved when keeping the certificates and keys stored +on a tmpfs (linux) on a system with very high throughput. + +### allow\_sendfile\_call `yes` +This option can be used to enable or disable the use of the Linux `sendfile` system call. It is only available for Linux systems and only affecting HTTP (not HTTPS) connections if `throttle` is not enabled. While using the `sendfile` call will lead to a performance boost for HTTP connections, this call may be broken for some file systems and some operating system versions. + +### case\_sensitive `no` +This option can be uset to enable case URLs for Windows servers. It is only available for Windows systems. Windows file systems are not case sensitive, but they still store the file name including case. If this option is set to `yes`, the comparison for URIs and Windows file names will be case sensitive. + +### allow\_index\_script\_resource `no` +Index scripts (like `index.cgi` or `index.lua`) may have script handled resources. + +It this feature is activated, that /some/path/file.ext might be handled by: + 1. /some/path/file.ext (with PATH\_INFO='/', if ext = cgi) + 2. /some/path/index.lua with mg.request\_info.path\_info='/file.ext' + 3. /some/path/index.cgi with PATH\_INFO='/file.ext' + 4. /some/path/index.php with PATH\_INFO='/file.ext' + 5. /some/index.lua with mg.request\_info.path\_info=='/path/file.ext' + 6. /some/index.cgi with PATH\_INFO='/path/file.ext' + 7. /some/index.php with PATH\_INFO='/path/file.ext' + 8. /index.lua with mg.request\_info.path\_info=='/some/path/file.ext' + 9. /index.cgi with PATH\_INFO='/some/path/file.ext' + 10. /index.php with PATH\_INFO='/some/path/file.ext' + +Note: This example is valid, if the default configuration values for `index_files`, `cgi_pattern` and `lua_script_pattern` are used, and the server is built with CGI and Lua support enabled. + +If this feature is not activated, only the first file (/some/path/file.cgi) will be accepted. + +Note: This parameter affects only index scripts. A path like /here/script.cgi/handle/this.ext will call /here/script.cgi with PATH\_INFO='/handle/this.ext', no matter if this option is set to `yes` or `no`. + +This feature can be used to completely hide the script extension from the URL. + +### additional\_header +Send additional HTTP response header line for every request. +The full header line including key and value must be specified, excluding the carriage return line feed. + +Example (used as command line option): +`-additional_header "X-Frame-Options: SAMEORIGIN"` + +This option can be specified multiple times. All specified header lines will be sent. + +# Lua Scripts and Lua Server Pages +Pre-built Windows and Mac civetweb binaries have built-in Lua scripting +support as well as support for Lua Server Pages. + +Lua scripts (default extension: *.lua) use plain Lua syntax. +The body of the script file is not sent directly to the client, +the Lua script must send header and content of the web page by calling +the function mg.write(text). + +Lua Server Pages (default extensions: *.lsp, *.lp) are html pages containing +script elements similar to PHP, using the Lua programming language instead of +PHP. Lua script elements must be enclosed in `<? ?>` blocks, and can appear +anywhere on the page. Furthermore, Lua Server Pages offer the opportunity to +insert the content of a variable by enclosing the Lua variable name in +`<?= ?>` blocks, similar to PHP. +For example, to print the current weekday name and the URI of the current +page, one can write: + + <p> + <span>Today is:</span> + <? mg.write(os.date("%A")) ?> + </p> + <p> + URI is <?=mg.request_info.uri?> + </p> + +Lua is known for it's speed and small size. Civetweb currently uses Lua +version 5.2.4. The documentation for it can be found in the +[Lua 5.2 reference manual](http://www.lua.org/manual/5.2/). + + +Note that this example uses function `mg.write()`, which sends data to the +web client. Using `mg.write()` is the way to generate web content from inside +Lua code. In addition to `mg.write()`, all standard Lua library functions +are accessible from the Lua code (please check the reference manual for +details). Lua functions working on files (e.g., `io.open`) use a path +relative to the working path of the civetweb process. The web server content +is located in the path `mg.document_root`. +Information on the request is available in the `mg.request_info` +object, like the request method, all HTTP headers, etcetera. + +[page2.lua](https://github.com/civetweb/civetweb/blob/master/test/page2.lua) +is an example for a plain Lua script. + +[page2.lp](https://github.com/civetweb/civetweb/blob/master/test/page2.lp) +is an example for a Lua Server Page. + +Both examples show the content of the `mg.request_info` object as the page +content. Please refer to `struct mg_request_info` definition in +[civetweb.h](https://github.com/civetweb/civetweb/blob/master/include/civetweb.h) +to see additional information on the elements of the `mg.request_info` object. + +Civetweb also provides access to the [SQlite3 database](http://www.sqlite.org/) +through the [LuaSQLite3 interface](http://lua.sqlite.org/index.cgi/doc/tip/doc/lsqlite3.wiki) +in Lua. Examples are given in +[page.lua](https://github.com/civetweb/civetweb/blob/master/test/page.lua) and +[page.lp](https://github.com/civetweb/civetweb/blob/master/test/page.lp). + + +Civetweb exports the following functions to Lua: + +mg (table): + + mg.read() -- reads a chunk from POST data, returns it as a string + mg.write(str) -- writes string to the client + mg.include(filename, [pathtype]) -- include another Lua Page file (Lua Pages only) + -- pathtype can be "abs", "rel"/"file" or "virt[ual]" + -- like defined for SSI #include + mg.redirect(uri) -- internal redirect to a given URI + mg.onerror(msg) -- error handler, can be overridden + mg.version -- a string that holds Civetweb version + mg.document_root -- a string that holds the document root directory + mg.auth_domain -- a string that holds the HTTP authentication domain + mg.get_var(str, varname) -- extract variable from (query) string + mg.get_cookie(str, cookie) -- extract cookie from a string + mg.get_mime_type(filename) -- get MIME type of a file + mg.get_info(infotype) -- get server status information + mg.send_file(filename) -- send a file, including MIME type + mg.url_encode(str) -- URL encode a string + mg.url_decode(str, [form]) -- URL decode a string. If form=true, replace + by space. + mg.base64_encode(str) -- BASE64 encode a string + mg.base64_decode(str) -- BASE64 decode a string + mg.md5(str) -- return the MD5 hash of a string + mg.keep_alive(bool) -- allow/forbid to use http keep-alive for this request + mg.request_info -- a table with the following request information + .remote_addr -- IP address of the client as string + .remote_port -- remote port number + .server_port -- server port number + .request_method -- HTTP method (e.g.: GET, POST) + .http_version -- HTTP protocol version (e.g.: 1.1) + .uri -- resource name + .query_string -- query string if present, nil otherwise + .script_name -- name of the Lua script + .https -- true if accessed by https://, false otherwise + .remote_user -- user name if authenticated, nil otherwise + +connect (function): + + -- Connect to the remote TCP server. This function is an implementation + -- of simple socket interface. It returns a socket object with three + -- methods: send, recv, close, which are synchronous (blocking). + -- connect() throws an exception on connection error. + connect(host, port, use_ssl) + + -- Example of using connect() interface: + local host = 'code.google.com' -- IP address or domain name + local ok, sock = pcall(connect, host, 80, 1) + if ok then + sock:send('GET /p/civetweb/ HTTP/1.0\r\n' .. + 'Host: ' .. host .. '\r\n\r\n') + local reply = sock:recv() + sock:close() + -- reply now contains the web page https://code.google.com/p/civetweb + end + + +All filename arguments are either absolute or relative to the civetweb working +directory (not the document root or the Lua script/page file). + +**IMPORTANT: Civetweb does not send HTTP headers for Lua pages. Therefore, +every Lua Page must begin with a HTTP reply line and headers**, like this: + + <? mg.write('HTTP/1.0 200 OK\r\nContent-Type: text/html\r\n\r\n') ?> + <html><body> + ... the rest of the web page ... + +To serve a Lua Page, civetweb creates a Lua context. That context is used for +all Lua blocks within the page. That means, all Lua blocks on the same page +share the same context. If one block defines a variable, for example, that +variable is visible in all block that follow. + +## Websockets for Lua +Civetweb offers support for websockets in Lua as well. In contrast to plain +Lua scripts and Lua server pages, Lua websocket scripts are shared by all clients. + +Lua websocket scripts must define a few functions: + open(arg) -- callback to accept or reject a connection + ready(arg) -- called after a connection has been established + data(arg) -- called when the server receives data from the client + close(arg) -- called when a websocket connection is closed +All function are called with one argument of type table with at least one field +"client" to identify the client. When "open" is called, the argument table additionally +contains the "request_info" table as defined above. For the "data" handler, an +additional field "data" is available. The functions "open", "ready" and "data" +must return true in order to keep the connetion open. + +Lua websocket pages do support single shot (timeout) and interval timers. + +An example is shown in +[websocket.lua](https://github.com/civetweb/civetweb/blob/master/test/websocket.lua). + + +# Common Problems +- PHP doesn't work - getting empty page, or 'File not found' error. The + reason for that is wrong paths to the interpreter. Remember that with PHP, + the correct interpreter is `php-cgi.exe` (`php-cgi` on UNIX). + Solution: specify the full path to the PHP interpreter, e.g.: + `civetweb -cgi_interpreter /full/path/to/php-cgi` + +- `php-cgi` is unavailable, for example on Mac OS X. As long as the `php` binary is installed, you can run CGI programs in command line mode (see the example below). Note that in this mode, `$_GET` and friends will be unavailable, and you'll have to parse the query string manually using [parse_str](http://php.net/manual/en/function.parse-str.php) and the `QUERY_STRING` environmental variable. + + #!/usr/bin/php + <?php + echo "Content-Type: text/html\r\n\r\n"; + echo "Hello World!\n"; + ?> + +- Civetweb fails to start. If Civetweb exits immediately when started, this + usually indicates a syntax error in the configuration file + (named `civetweb.conf` by default) or the command-line arguments. + Syntax checking is omitted from Civetweb to keep its size low. However, + the Manual should be of help. Note: the syntax changes from time to time, + so updating the config file might be necessary after executable update. + +- Embedding with OpenSSL on Windows might fail because of calling convention. + To force Civetweb to use `__stdcall` convention, add `/Gz` compilation + flag in Visual Studio compiler. + diff --git a/src/civetweb/docs/_config.yml b/src/civetweb/docs/_config.yml new file mode 100644 index 00000000..259a24e4 --- /dev/null +++ b/src/civetweb/docs/_config.yml @@ -0,0 +1 @@ +theme: jekyll-theme-tactile
\ No newline at end of file diff --git a/src/civetweb/docs/api/mg_callbacks.md b/src/civetweb/docs/api/mg_callbacks.md new file mode 100644 index 00000000..c7d69a13 --- /dev/null +++ b/src/civetweb/docs/api/mg_callbacks.md @@ -0,0 +1,60 @@ +# Civetweb API Reference + +### `struct mg_callbacks;` + +### Fields + +| Field | Description | +| :--- | :--- | +|**`begin_request`**|**`int (*begin_request)( struct mg_connection *conn );`**| +| |The `begin_request()` callback function is called when CivetWeb has received a new HTTP request. If the callback function does not process the request, it should return 0. In that case CivetWeb will handle the request with the default callback routine. If the callback function returns a value between 1 and 999, CivetWeb does nothing and the callback function should do all the processing, including sending the proper HTTP headers etc. Starting at CivetWeb version 1.7, the function `begin_request()` is called before any authorization is done. If an authorization check is required, `request_handler()` should be used instead. The return value of the callback function is not only used to signal CivetWeb to not further process the request. The returned value is also stored as HTTP status code in the access log. | +|**`connection_close`**|**`void (*connection_close)( const struct mg_connection *conn );`**| +| |The callback function `connection_close()` is called when CivetWeb is closing a connection. The per-context mutex is locked when the callback function is invoked. The function is primarly useful for noting when a websocket is closing and removing it from any application-maintained list of clients. *Using this callback for websocket connections is deprecated. Use* `mg_set_websocket_handler()` *instead.*| +|**`end_request`**|**`void (*end_request)(const struct mg_connection *conn, int reply_status_code);`**| +| |The callback function `end_request()` is called by CivetWeb when a request has been completely processed. It sends the reply status code which was sent to the client to the application.| +|**`exit_context`**|**`void (*exit_context)( const struct mg_context *ctx );`**| +| |The callback function `exit_context()` is called by CivetWeb when the server is stopped. It allows the application to do some cleanup on the application side.| +|**`http_error`**|**`int (*http_error)( struct mg_connection *conn, int status );`**| +| |The callback function `http_error()` is called by CivetWeb just before an HTTP error is to be sent to the client. The function allows the application to send a custom error page. The status code of the error is provided as a parameter. If the application sends their own error page, it must return 1 to signal CivetWeb that no further processing is needed. If the returned value is 0, CivetWeb will send a built-in error page to the client.| +|**`init_context`**|**`void (*init_context)( const struct mg_context *ctx );`**| +| |The callback function `init_context()` is called after the CivetWeb server has been started and initialized, but before any requests are served. This allowes the application to perform some initialization activities before the first requests are handled.| +|**`init_lua`**|**`void (*init_lua)( const struct mg_connection *conn, void *lua_context );`**| +| |The callback function `init_lua()` is called just before a Lua server page is to be served. Lua page serving must have been enabled at compile time for this callback function to be called. The parameter `lua_context` is a `lua_State *` pointer.| +|**`init_ssl`**|**`int (*init_ssl)( void *ssl_context, void *user_data );`**| +| |The callback function `init_ssl()` is called when CivetWeb initializes the SSL library. The parameter `user_data` contains a pointer to the data which was provided to `mg_start()` when the server was started. The callback function can return 0 to signal that CivetWeb should setup the SSL certificate. With a return value of 1 the callback function signals CivetWeb that the certificate has already been setup and no further processing is necessary. The value -1 should be returned when the SSL initialization fails.| +|**`init_thread`**|**`void (*init_thread)( const struct mg_context *ctx, int thread_type );`**| +| |The callback function `init_thread()` is called when a new thread is created by CivetWeb. The `thread_type` parameter indicates which type of thread has been created. following thread types are recognized:| +| |**0** - The master thread is created | +| |**1** - A worker thread which handles client connections has been created| +| |**2** - An internal helper thread (timer thread) has been created| +|**`log_access`**|**`int (*log_access)( const struct mg_connection *conn, const char *message );`**| +| |The callback function `log_access()` is called when CivetWeb is about to log a message. If the callback function returns 0, CivetWeb will use the default internal access log routines to log the access. If a non-zero value is returned, CivetWeb assumes that access logging has already been done and no further action is performed.| +|**`log_message`**|**`int (*log_message)( const struct mg_connection *conn, const char *message );`**| +| |The callback function `log_message()` is called when CivetWeb is about to log a message. If the callback function returns 0, CivetWeb will use the default internal log routines to log the message. If a non-zero value is returned CivetWeb assumes that logging has already been done and no further action is performed.| +|**`open_file`**|**`const char *(*open_file)( const struct mg_connection *conn, const char *path, size_t *data_len );`**| +| |The callback function `open_file()` is called when a file is to be opened by CivetWeb. The callback can return a pointer to a memory location and set the memory block size in the variable pointed to by `data_len` to signal CivetWeb that the file should not be loaded from disk, but that instead a stored version in memory should be used. If the callback function returns NULL, CivetWeb will open the file from disk. This callback allows caching to be implemented at the application side, or to serve specific files from static memory instead of from disk.| +|~~`upload`~~|**`void (*upload)( struct mg_connection * conn, const char *file_name );`**| +| |*Deprecated. Use* `mg_handle_form_request()` *instead.* The callback function `upload()` is called when CivetWeb has uploaded a file to a temporary directory as result of a call to `mg_upload()`. The parameter `file_name` contains the full file name including path to the uploaded file.| +|~~`websocket_connect`~~|**`int (*websocket_connect)( const struct mg_connection *conn );`**| +| |*Deprecated. Use* `mg_set_websocket_handler()` *instead.* The callback function `websocket_connect()` is called when a websocket request is received, before the actual websocket handshake has taken place. The callback function can signal to CivetWeb if it should accept or deny the incoming request with one of the following return values: | +| |**0** - CivetWeb can proceed with the handshake to accept the connection | +| |**1** - CivetWeb must close the connection immediately without performing a handshake | +|~~`websocket_data`~~|**`int (*websocket_data)( struct mg_connection *conn, int bits, char *data, size_t data_len );`**| +| |*Deprecated. Use* `mg_set_websocket_handler()` *instead.* The callback function `websocket_data()` is called when a data frame has been received from the client. The parameters contain the following information: | +| | **`bits`** - The first byte of the websocket frame. See [RFC-6455](http://tools.ietf.org/html/rfc6455) at section 5.2 for more information. | +| | **`data`** - The pointer to the received data block. Masks--if any--have already been applied. | +| | **`data_len`** - The length of the received data block | +| | If the application wants to keep the websocket open to receive more data, the callback function should return the value **1**. If the value **0** is returned by the callback function, CivetWeb will close the websocket connection and no more frames will be received.| +|~~`websocket_ready`~~|**`int (*websocket_ready)( struct mg_connection *conn );`**| +| |*Deprecated. Use* `mg_set_websocket_handler()` *instead.* The callback function `websocket_ready()` is called after the handshake of a websocket connection has succeeded succesfully to signal the application that the connection is ready for use. | + +### Description + +Much of the functionality in the Civetweb library is provided through callback functions. The application registers their own processing functions with the Civetweb library and when an event happens, the appropriate callback function is called. In this way an application is able to have their processing code right at the heart of the webserver, without the need to change the code of the webserver itself. A number of callback functions are registered when the civetweb subsystem is started. Other may be added or changed at runtime with helper functions. + +A pointer to a `mg_callbacks` structure is passed as parameter to the [`mg_start()`](mg_start.md) function to provide links to callback functions which the webserver will call at specific events. If a specific callback function is not supplied, CivetWeb will fallback to default internal callback routines. Callback functions give the application detailed control over how specific events should be handled. + +### See Also + +* [`mg_start();`](mg_start.md) +* [`mg_stop();`](mg_stop.md) diff --git a/src/civetweb/docs/api/mg_check_digest_access_authentication.md b/src/civetweb/docs/api/mg_check_digest_access_authentication.md new file mode 100644 index 00000000..fec3ad3b --- /dev/null +++ b/src/civetweb/docs/api/mg_check_digest_access_authentication.md @@ -0,0 +1,37 @@ +# Civetweb API Reference + +### `mg_check_digest_access_authentication( conn, realm, filename );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`| A pointer to the connection to be used to send data | +|**`realm`**|`const char *`| The requested authentication realm or NULL | +|**`filename`**|`const char *`| The path to the passwords file | + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`| An integer indicating success or failure | + +### Description + +This function can be used to check if a request header contains HTTP digest authentication +information, matching user and password encoded within the password file. +If the authentication realm (also called authentication domain) is NULL, the parameter +`authentication_domain` as specified in the server configuration (`mg_start()`) is used. + +A positive return value means, the user name, realm and a correct password hash have been +found in the passwords file. +A return of 0 means, reading the password file succeeded, but there was no matching user, +realm and password. +The function returns a negative number on errors. + +### See Also + +* [`mg_send_digest_access_authentication_request();`](mg_send_digest_access_authentication_request.md) +* [`mg_modify_passwords_file();`](mg_modify_passwords_file.md) +* [`mg_start();`](mg_start.md) + diff --git a/src/civetweb/docs/api/mg_check_feature.md b/src/civetweb/docs/api/mg_check_feature.md new file mode 100644 index 00000000..1da1b072 --- /dev/null +++ b/src/civetweb/docs/api/mg_check_feature.md @@ -0,0 +1,40 @@ +# Civetweb API Reference + +### `mg_check_feature( feature );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`feature`**|`unsigned`| A value indicating the feature to be checked | + +### Return Value + +| Type | Description | +| :--- | :--- | +|`unsigned`| A value indicating if a feature is available. A positive value indicates available, while **0** is returned for an unavailable feature | + +### Description + +The function `mg_check_feature()` can be called from an application program to check of specific features have been compiled in the civetweb version which the application has been linked to. The feature to check is provided as an unsigned integer parameter. If the function is available in the currently linked library version, a value **> 0** is returned. Otherwise the function `mg_check_feature()` returns the value **0**. + +The following parameter values can be used: + +| Value | Compilation option | Description | +| :---: | :---: | :--- | +| **1** | NO_FILES | *Able to serve files*. If this feature is available, the webserver is able to serve files directly from a directory tree. | +| **2** | NO_SSL | *Support for HTTPS*. If this feature is available, the webserver van use encryption in the client-server connection. SSLv2, SSLv3, TLSv1.0, TLSv1.1 and TLSv1.2 are supported depending on the SSL library CivetWeb has been compiled with, but which protocols are used effectively when the server is running is dependent on the options used when the server is started. | +| **4** | NO_CGI | *Support for CGI*. If this feature is available, external CGI scripts can be called by the webserver. | +| **8** | USE_IPV6 | *Support IPv6*. The CivetWeb library is capable of communicating over both IPv4 and IPv6, but IPv6 support is only available if it has been enabled at compile time. | +| **16** | USE_WEBSOCKET | Support for web sockets. WebSockets support is available in the CivetWeb library if the proper options has been used during cimpile time. | +| **32** | USE_LUA | *Support for Lua scripts and Lua server pages*. CivetWeb supports server side scripting through the Lua language, if that has been enabled at compile time. Lua is an efficient scripting language which is less resource heavy than for example PHP. | +| **64** | USE_DUKTAPE | *Support for server side JavaScript*. Server side JavaScript can be used for dynamic page generation if the proper options have been set at compile time. Please note that client side JavaScript execution is always available if it has been enabled in the connecting browser. | +| **128** | NO_CACHING | *Support for caching*. The webserver will support caching, if it has not been disabled while compiling the library. | + +Parameter values other than the values mentioned above will give undefined results. Therefore—although the parameter values for the `mg_check_feature()` function are effectively bitmasks, you should't assume that combining two of those values with an OR to a new value will give any meaningful results when the function returns. + +### See Also + +* [`mg_get_option();`](mg_get_option.md) +* [~~`mg_get_valid_option_names();`~~](mg_get_valid_option_names.md) +* [`mg_get_valid_options();`](mg_get_valid_options.md) diff --git a/src/civetweb/docs/api/mg_client_cert.md b/src/civetweb/docs/api/mg_client_cert.md new file mode 100644 index 00000000..c81fbd08 --- /dev/null +++ b/src/civetweb/docs/api/mg_client_cert.md @@ -0,0 +1,21 @@ +# Civetweb API Reference + +### `struct mg_client_cert;` + +### Fields + +| Field | Type | Description | +| :--- | :--- | :--- | +|**`subject`**|`const char *`| The subject of the certificate | +|**`issuer`**|`const char *`| The issuer of the certificate | +|**`serial`**|`const char *`| The serial number of the certificate | +|**`finger`**|`const char *`| The fingerprint of the certificate | + +### Description + +The structure `client_cert` is used as a sub-structure in the [`mg_request_info`](mg_request_info.md) structure to store information of an optional client supplied certificate. + +### See Also + +* [`struct mg_request_info;`](mg_request_info.md) +* [`mg_get_request_info();`](mg_get_request_info.md) diff --git a/src/civetweb/docs/api/mg_client_options.md b/src/civetweb/docs/api/mg_client_options.md new file mode 100644 index 00000000..f3b9b682 --- /dev/null +++ b/src/civetweb/docs/api/mg_client_options.md @@ -0,0 +1,21 @@ +# Civetweb API Reference + +### `struct mg_client_options;` + +### Fields + +| Field | Type | Description | +| :--- | :--- | :--- | +|**`host`**|`const char *`|The hostname or IP address to connect to| +|**`port`**|`int`|The port on the server| +|**`client_cert`**|`const char *`|Pointer to client certificate| +|**`server_cert`**|`const char *`|Pointer to a server certificate| + +### Description + +The the `mgclient_options` structure contains host and security information to connect as a client to another host. A parameter of this type is used in the call to the function [`mg_connect_client_secure();`](mg_connect_client_secure.md). Please note that IPv6 addresses are only permitted if IPv6 support was enabled during compilation. You can use the function [`mg_check_feature()`](mg_check_feature.md) with the parameter `USE_IPV6` while running your application to check if IPv6 is supported. + +### See Also + +* [`mg_check_feature();`](mg_check_feature.md) +* [`mg_connect_client_secure();`](mg_connect_client_secure.md) diff --git a/src/civetweb/docs/api/mg_close_connection.md b/src/civetweb/docs/api/mg_close_connection.md new file mode 100644 index 00000000..ca8d2a10 --- /dev/null +++ b/src/civetweb/docs/api/mg_close_connection.md @@ -0,0 +1,21 @@ +# Civetweb API Reference + +### `mg_close_connection( conn );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`|The connection which must be closed| + +### Return Value + +*none* + +### Description + +The function `mg_close_connection()` is used to close a connection which was opened with the [`mg_download()`](mg_download.md) function. Use of this function to close a connection which was opened in another way is undocumented and may give unexpected results. + +### See Also + +* [`mg_download();`](mg_download.md) diff --git a/src/civetweb/docs/api/mg_connect_client.md b/src/civetweb/docs/api/mg_connect_client.md new file mode 100644 index 00000000..e2aa7739 --- /dev/null +++ b/src/civetweb/docs/api/mg_connect_client.md @@ -0,0 +1,29 @@ +# Civetweb API Reference + +### `mg_connect_client( host, port, use_ssl, error_buffer, error_buffer_size );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`host`**|`const char *`|hostname or IP address of the server| +|**`port`**|`int`|The port to connect to on the server| +|**`use_ssl`**|`int`|Connects using SSL of this value is not zero| +|**`error_buffer`**|`char *`|Buffer to store an error message| +|**`error_buffer_size`**|`size_t`|Maximum size of the error buffer including the NUL terminator| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`struct mg_connection *`|| + +### Description + +The function `mg_connect_client()` connects to a TCP server as a client. This server can be a HTTP server but this is not necessary. The function returns a pointer to a connection structure when the connection is established and NULL otherwise. The host may be on IPv4 or IPv6, but IPv6 is not enabled in every Civetweb installation. Specifically the use of IPv6 communications has to be enabled when the library is compiled. At runtime you can use the [`mg_check_feature()`](mg_check_feature.md) function with the parameter `USE_IPV6` to check if IPv6 communication is supported. + +### See Also + +* [`mg_check_feature();`](mg_check_feature.md) +* [`mg_connect_client_secure();`](mg_connect_client_secure.md) +* [`mg_connect_websocket_client();`](mg_connect_websocket_client.md) diff --git a/src/civetweb/docs/api/mg_connect_client_secure.md b/src/civetweb/docs/api/mg_connect_client_secure.md new file mode 100644 index 00000000..a87949b6 --- /dev/null +++ b/src/civetweb/docs/api/mg_connect_client_secure.md @@ -0,0 +1,30 @@ +# Civetweb API Reference + +### `mg_connect_client_secure( client_options, error_buffer, error_buffer_size );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`client_options`**|`const struct mg_client_options *`|Settings about the server connection| +|**`error_buffer`**|`char *`|Buffer to store an error message| +|**`error_buffer_size`**|`size_t`|Size of the error message buffer including the NUL terminator| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`struct mg_connection *`|| + +### Description + +The function `mg_connect_client_secure()` creates a secure connection with a server. The information about the connection and server is passed in a structure and an error message may be returned in a local buffer. The function returns a pointer to a `struct mg_connection` structure when successful and NULL otherwise. + +Please note that IPv6 communication is supported by Civetweb, but only if the use of IPv6 was enabled at compile time. The check while running a program if IPv6 communication is possible you can call [`mg_check_feature()`](mg_check_feature.md) with the `USE_IPV6` parameter to check if IPv6 communications can be used. + +### See Also + +* [`struct mg_client_options;`](mg_client_options.md) +* [`mg_check_feature();`](mg_check_feature.md) +* [`mg_connect_client();`](mg_connect_client.md) +* [`mg_connect_websocket_client();`](mg_connect_websocket_client.md) diff --git a/src/civetweb/docs/api/mg_connect_websocket_client.md b/src/civetweb/docs/api/mg_connect_websocket_client.md new file mode 100644 index 00000000..8562b25a --- /dev/null +++ b/src/civetweb/docs/api/mg_connect_websocket_client.md @@ -0,0 +1,36 @@ +# Civetweb API Reference + +### `mg_connect_websocket_client( host, port, use_ssl, error_buffer, error_buffer_size, path, origin, data_func, close_func, user-data);` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`host`**|`const char *`|The hostname or IP address of the server| +|**`port`**|`int`|The port on the server| +|**`use_ssl`**|`int`|Use SSL if this parameter is not equal to zero| +|**`error_buffer`**|`char *`|Buffer to store an error message| +|**`error_buffer_size`**|`size_t`|Size of the error message buffer including the NUL terminator| +|**`path`**|`const char *`|The server path to connect to, for example `/app` if you want to connect to `localhost/app`| +|**`origin`**|`const char *`|The value of the `Origin` HTTP header| +|**`data_func`**|`mg_websocket_data_handler`|Callback which is used to process data coming back from the server| +|**`close_func`**|`mg_websocket_close_handler`|Callback which is called when the connection is to be closed| +|**`user_data`**|`void *`|User supplied argument| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`struct mg_connection *`|A pointer to the connection structure, or NULL if connecting failed| + +### Description + +The function `mg_connect_websocket_client()` connects to a websocket on a server as a client. Data and close events are processed with callback functions which must be provided in the call. + +Civetweb supports both IPv4 and IPv6 communication, but only if the use if IPv6 has been enabled at compile time. When running an application it is possible to check if IPv6 addressing is available by calling the [`mg_check_feature()`](mg_check_feature.md) function with the `USE_IPV6` parameter. + +### See Also + +* [`mg_check_feature();`](mg_check_feature.md) +* [`mg_connect_client();`](mg_connect_client.md) +* [`mg_connect_client_secure();`](mg_connect_client_secure.md) diff --git a/src/civetweb/docs/api/mg_cry.md b/src/civetweb/docs/api/mg_cry.md new file mode 100644 index 00000000..0cf45c9b --- /dev/null +++ b/src/civetweb/docs/api/mg_cry.md @@ -0,0 +1,23 @@ +# Civetweb API Reference + +### `mg_cry( conn, fmt, ... );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`const struct mg_connection *`|The connection on which a problem occured| +|**`fmt`**|`const char *`|Format string without a line return| +|**`...`**|*various*|Parameters depending on the format string| + +### Return Value + +*none* + +### Description + +The function `mg_cry()` is called when something happens on a connection. The function takes a format string similar to the `printf()` series of functions with parameters and creates a text string which can then be used for logging. The `mg_cry()` function prints the output to the opened error log stream. Log messages can be processed with the `log_message()` callback function specified in the `struct mg_callbacks` structure. + +### See Also + +* [`struct mg_callbacks;`](mg_callbacks.md) diff --git a/src/civetweb/docs/api/mg_download.md b/src/civetweb/docs/api/mg_download.md new file mode 100644 index 00000000..1dbded0c --- /dev/null +++ b/src/civetweb/docs/api/mg_download.md @@ -0,0 +1,37 @@ +# Civetweb API Reference + +### `mg_download( host, port, use_ssl, error_buffer, error_buffer_size, fmt, ... );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`host`**|`const char *`|The hostname or IP address of the server| +|**`port`**|`int`|The port number on the server| +|**`use_ssl`**|`int`|Use SSL if this value is not equal zero| +|**`error_buffer`**|`char *`|Buffer to store an error message| +|**`error_buffer_size`**|`size_t`|Size of the error message buffer including the terminating NUL| +|**`fmt`**|`const char *`|Format string specifying the remote command to execute| +|**`...`**|*various*|Parameters used in the format string| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`struct mg_connection *`|A pointer to the connection structure if successful and NULL otherwise| + +### Description + +The `mg_download()` function is used to download data from a remote webserver. The server address can either be specified as a hostname or IP address and SSL can be used if needed. If the function succeeds, a pointer is returned to a connection structure. The connection must be closed with a call to the [`mg_close_connection()`](mg_close_connection.md) function. + +The format string is a format string from the `printf()` series of functions to specify the remote command. An example to get the main index page from Google is the following call: + +`conn = mg_download( "google.com", 80, 0, ebuf, sizeof(ebuf), + "%s", "GET / HTTP/1.0\r\nHost: google.com\r\n\r\n" );` + +Please note that although Civetweb supports both IPv4 and IPv6 communication that IPv6 addressing is only available if it was enabled at compile time. When running an application it is possible to check if IPv6 support has been compiled in by using the [`mg_check_feature()`](md_check_feature.md) function with the parameter `USE_IPV6`. + +### See Also + +* [`mg_check_feature();`](mg_check_feature.md) +* [`mg_close_connection();`](mg_close_connection.md) diff --git a/src/civetweb/docs/api/mg_exit_library.md b/src/civetweb/docs/api/mg_exit_library.md new file mode 100644 index 00000000..26434036 --- /dev/null +++ b/src/civetweb/docs/api/mg_exit_library.md @@ -0,0 +1,29 @@ +# Civetweb API Reference + +### `mg_exit_library( );` + +### Parameters + +none + +### Return Value + +| Type | Description | +| :--- | :--- | +|`unsigned`| **0** is returned or error | + +### Description + +The function `mg_exit_library()` should be called from an application program, when the library should be unloaded. +It must be called only from one thread (it is not guaranteed to be thread safe). + +Only use `mg_exit_library( );` when you used [`mg_init_library( feature );`](api/mg_init_library.md) before. + +The library init and exit functions are new in version 1.9 (as dummy implementation) and effective only from version 1.10. +For compatibility reasons, other functions (such as [`mg_start();`](mg_start.md)) will initialize the required features as well, +but they will no longer do a de-initialization, leaving a memory leak when the library is unloaded. + +### See Also + +* [`mg_init_library( feature );`](mg_init_library.md) +* [`mg_check_feature( feature );`](mg_check_feature.md) diff --git a/src/civetweb/docs/api/mg_form_data_handler.md b/src/civetweb/docs/api/mg_form_data_handler.md new file mode 100644 index 00000000..2338b72a --- /dev/null +++ b/src/civetweb/docs/api/mg_form_data_handler.md @@ -0,0 +1,36 @@ +# Civetweb API Reference + +### `struct mg_form_data_handler;` + +### Fields + +|Field|Description| +|:---|:---| +|**`field_found`**|**`int field_found( const char *key, const char *filename, char *path, size_t pathlen, void *user_data )`**;| +||The callback function `field_found()` is called when a new field has been found. The return value of this callback is used to define how the field should be processed. The parameters contain the following information:| +||**`key`** - The name of the field as it was named with the `name` tag in the HTML source.| +||**`filename`** - The name of the file to upload. Please not that this parameter is only valid when the input type was set to `file`. Otherwise this parameter has the value `NULL`.| +||**`path`** - This is an output parameter used to store the full name of the file including the path to store an incoming file at the computer. This parameter must be provided by the application to Civetweb when a form field of type `file` is found. Please not that together with setting this parameter, the callback function must return `FORM_FIELD_STORAGE_STORE`.i With any other return value the contents of the `path` buffer is ignored by Civetweb.| +||**`pathlen`** - The length of the buffer where the output path can be stored.| +||**`user_data`** - A pointer to the value of the field `user_data` of the structure `struct mg_form_data_handler`.| +||The callback function `field_found()` can return the following values back to Civetweb:| +||**`FORM_FIELD_STORAGE_SKIP`** - Ignore the field and continue with processing the next field| +||**`FORM_FIELD_STORAGE_GET`** - Call the callback function `field_get()` to receive the form data| +||**`FORM_FIELD_STORAGE_STORE`** - Store a file as `path` and overwrite that file if it already exists| +||**`FORM_FIELD_STORAGE_ABORT`** - Stop parsing the request and ignore all remaining form fields| +|**`field_get`**|**`int field_get( const char *key, const char *value, size_t valuelen, void *user_data );`**| +|**`field_store`**|**`int field_store( const char *path, long long file_size, void *user_data );`**| +||If the callback function `field_found()` returned `FORM_FIELD_STORAGE_STORE`, Civetweb will try to store the received data in a file. If writing the file is successful, the callback function `field_store()` is called. This function is only called after completion of a full upload, not if a file has only partly been uploaded. When only part of a file is received, Civetweb will delete that partly upload in the background and not inform the main application through this callback. The following parameters are provided in the function call:| +||**`path`** -| +||**`file_size`** - The path on the server where the file was stored| +||**`user_data`** - The size of the stored file in bytes| +|**`user_data`**|**`void *`** The value of the field `user_data` when the callback functions were registered with a call to `mg_handle_form_request();`| +||The `user_data` field is a user supplied argument that will be passed as parameter to each of callback functions| + +### Description + +The structure `struct mg_form_data_handler` contains callback functions for handling form fields. Form fields give additional information back from a web page to the server which can be processed by these callback functions. + +### See Also + +* [`mg_handle_form_request();`](mg_handle_form_request.md) diff --git a/src/civetweb/docs/api/mg_get_builtin_mime_type.md b/src/civetweb/docs/api/mg_get_builtin_mime_type.md new file mode 100644 index 00000000..c9044ae1 --- /dev/null +++ b/src/civetweb/docs/api/mg_get_builtin_mime_type.md @@ -0,0 +1,24 @@ +# Civetweb API Reference + +### `mg_get_builtin_mime_type( file_name );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`file_name`**|`const char *`|The name of the file for which the MIME type has to be determined| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`const char *`|A text string describing the MIME type| + +### Description + +The function `mg_get_builtin_mime_type()` tries to determine the MIME type of a given file. If the MIME type cannot be determined, the value `text/plain` is returned. Please note that this function does not an intelligent check of the file contents. The MIME type is solely determined based on the file name extension. + +### See Also + +* [`mg_send_mime_file();`](mg_send_mime_file.md) +* [`mg_send_mime_file2();`](mg_send_mime_file2.md) diff --git a/src/civetweb/docs/api/mg_get_connection_info.md b/src/civetweb/docs/api/mg_get_connection_info.md new file mode 100644 index 00000000..14a2f68c --- /dev/null +++ b/src/civetweb/docs/api/mg_get_connection_info.md @@ -0,0 +1,40 @@ +# Civetweb API Reference + +### `mg_get_connection_info( ctx, idx, buffer, buflen );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`ctx`**|`struct mg_context *`|The server context handle| +|**`idx`**|`int`|Connection index within the context| +|**`buffer**|`char *`|A string buffer to store the information| +|**`buflen**|`int`|Size of the string buffer (including space for a terminating 0)| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|Available context information in bytes (excluding the terminating 0)| + +### Description + +The function `mg_get_connection_info()` returns statistics information collected for +a server connection index. This may be empty if the server has not been built with +statistics support (`#define USE_SERVER_STATS`). +If data is available, the returned string is in JSON format. The exact content may +vary, depending on the connection state and server version. + +### Note + +This is an experimental interface and may be changed, replaced +or even removed in the future. Currently the index `idx` must be +between `0` and `num_threads-1`. The thread is not locked for +performance reasons, so the information may be inconsistent +in rare cases. + +### See Also + +* [`mg_get_system_info();`](mg_get_system_info.md) +* [`mg_get_context_info();`](mg_get_context_info.md) + diff --git a/src/civetweb/docs/api/mg_get_context.md b/src/civetweb/docs/api/mg_get_context.md new file mode 100644 index 00000000..ce6cb2be --- /dev/null +++ b/src/civetweb/docs/api/mg_get_context.md @@ -0,0 +1,24 @@ +# Civetweb API Reference + +### `mg_get_context( conn );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`const struct mg_connection *`|The connection for which the context has to be returned| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`struct mg_context *`|A pointer to the context of the given connection| + +### Description + +The function `mg_get_context()` returns the context associated with a connection. + +### See Also + +* [`mg_start();`](mg_start.md) +* [`mg_stop();`](mg_stop.md) diff --git a/src/civetweb/docs/api/mg_get_context_info.md b/src/civetweb/docs/api/mg_get_context_info.md new file mode 100644 index 00000000..88ffcf74 --- /dev/null +++ b/src/civetweb/docs/api/mg_get_context_info.md @@ -0,0 +1,32 @@ +# Civetweb API Reference + +### `mg_get_context_info( ctx, buffer, buflen );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`ctx`**|`struct mg_context *`|The server context handle| +|**`buffer**|`char *`|A string buffer to store the information| +|**`buflen**|`int`|Size of the string buffer (including space for a terminating 0)| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|Available context information in bytes (excluding the terminating 0)| + +### Description + +The function `mg_get_context_info()` returns statistics information collected for +the server context. This may be empty if the server has not been built with +statistics support (`#define USE_SERVER_STATS`). +If data is available, the returned string is in JSON format. The exact content may +vary, depending on the server state and server version. + +### See Also + +* [`mg_get_system_info();`](mg_get_system_info.md) +* [`mg_get_connection_info();`](mg_get_connection_info.md) + + diff --git a/src/civetweb/docs/api/mg_get_cookie.md b/src/civetweb/docs/api/mg_get_cookie.md new file mode 100644 index 00000000..a738bc07 --- /dev/null +++ b/src/civetweb/docs/api/mg_get_cookie.md @@ -0,0 +1,29 @@ +# Civetweb API Reference + +### `mg_get_cookie( cookie, var_name, buf, buf_len );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`cookie`**|`const char *`|The cookie name| +|**`var_name`**|`const char *`|The variable name| +|**`buf`**|`char *`|The buffer where to store the contents of the cookie| +|**`buf_len`**|`size_t`|The length of the cookie buffer, including the terminating NUL| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|The length of the cookie or an error code| + +### Description + +The function `mg_get_cookie()` tries to fetch the value of a certain cookie variable. The contents will either be stored in an application provided buffer, or an error code will be returned. The destination buffer is guaranteed to be NUL terminated if the pointer of the buffer is not a NULL pointer and the size of the buffer is at least one byte. + +If the function succeeds, the return value of the function is the length in bytes of the cookie. The value **`-1`** is returned if the requested cookie could not be found and **`-2`** if the destination buffer is represented by a NULL pointer, is zero length or too short to store the whole cookie. + +### See Also + +* [`mg_get_var();`](mg_get_var.md) +* [`mg_get_var2();`](mg_get_var2.md) diff --git a/src/civetweb/docs/api/mg_get_header.md b/src/civetweb/docs/api/mg_get_header.md new file mode 100644 index 00000000..8ad1810a --- /dev/null +++ b/src/civetweb/docs/api/mg_get_header.md @@ -0,0 +1,22 @@ +# Civetweb API Reference + +### `mg_get_header( conn, name );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`| A pointer referencing the connection | +|**`name`**|`const char *`| The name of the request header | + +### Return Value + +| Type | Description | +| :--- | :--- | +|`const char *`| A pointer to the value of the request header, or NULL of no matching header count be found | + +### Description + +HTTP and HTTPS clients can send request headers to the server to provide details about the communication. These request headers can for example specify the preferred language in which the server should respond and the supported compression algorithms. The function `mg_get_header()` can be called to return the contents of a specific request header. The function will return a pointer to the value text of the header when succesful, and NULL of no matching request header from the client could be found. + +### See Also diff --git a/src/civetweb/docs/api/mg_get_option.md b/src/civetweb/docs/api/mg_get_option.md new file mode 100644 index 00000000..b731dd74 --- /dev/null +++ b/src/civetweb/docs/api/mg_get_option.md @@ -0,0 +1,24 @@ +# Civetweb API Reference + +### `mg_get_option( ctx, name );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`ctx`**|`const struct mg_context *`| A pointer to the webserver context | +|**`name`**|`const char *`| The name of the option to query | + +### Return Value + +| Type | Description | +| :--- | :--- | +|`const char *`| A pointer to the option value in text, or NULL if an error occured | + +### Description + +When starting the CivetWeb webserver, options are provided to set the wanted behaviour of the server. The options which were used during startup can be queried through the `mg_get_option()` function. Options are read-only and cannot be changed while the webserver is running. The function returns a pointer to a text string containing the value of the queried option, or NULL if an error occured. It is guaranteed however that if a valid option name is provided as a parameter to this function, that a pointer to a string is returned and not NULL. In case an option was empty or NULL during initialisation, `mg_get_option()` will return a pointer to an empty string. + +### See Also + +* [`mg_start();`](mg_start.md) diff --git a/src/civetweb/docs/api/mg_get_ports.md b/src/civetweb/docs/api/mg_get_ports.md new file mode 100644 index 00000000..ba492ca3 --- /dev/null +++ b/src/civetweb/docs/api/mg_get_ports.md @@ -0,0 +1,31 @@ +# Civetweb API Reference + +### ~~`mg_get_ports( ctx, size, ports, ssl );`~~ + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`ctx`**|`const struct mg_context *`|| +|**`size`**|`size_t`|The number of ports which can be stored in the buffer| +|**`ports`**|`int *`|Buffer for storage of the port numbers| +|**`ssl`**|`int *`|Buffer used to store if SSL is used for the ports| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`size_t`|The number of ports stored in the buffer| + +### Description + +This function is deprecated. Use [`mg_get_server_ports()`](mg_get_server_ports.md) instead. + +The function `mg_get_ports()` returns a list of ports the Civetweb server is listening on. The port numbers are stored in a buffer of integers which is supplied by the calling party. The function also stores information if SSL is used on the ports. This information is stored in a second buffer which should be capable of storing the same amount of items as the ports buffer. + +The function returns the number of ports actually stored in the buffer. + +### See Also + +* [`struct mg_server_ports;`](mg_server_ports.md) +* [`mg_get_server_ports();`](mg_get_server_ports.md) diff --git a/src/civetweb/docs/api/mg_get_request_info.md b/src/civetweb/docs/api/mg_get_request_info.md new file mode 100644 index 00000000..b7ddd07a --- /dev/null +++ b/src/civetweb/docs/api/mg_get_request_info.md @@ -0,0 +1,28 @@ +# Civetweb API Reference + +### `mg_get_request_info( conn );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`const struct mg_connection *`|The connection for which the request info is needed| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`const struct mg_request_info *`|Pointer to the requested info, or NULL if an error occured| + +### Description + +The function `mg_get_request_info()` returns information about the request on a given connection. This information is returned as a pointer to a [`mg_request_info`](mg_request_info.md) structure. If an error occurs, a NULL pointer is returned instead. + +Use this function when implementing a server. + +### See Also + +* [`struct mg_request_info;`](mg_request_info.md) +* [`mg_get_response_info();`](mg_get_response_info.md) +* [`struct mg_response_info;`](mg_response_info.md) + diff --git a/src/civetweb/docs/api/mg_get_request_link.md b/src/civetweb/docs/api/mg_get_request_link.md new file mode 100644 index 00000000..d58a5928 --- /dev/null +++ b/src/civetweb/docs/api/mg_get_request_link.md @@ -0,0 +1,29 @@ +# Civetweb API Reference + +### `mg_get_request_link( conn, buf, buflen );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`| A pointer referencing the connection | +|**`buf`**|`char *`| A buffer to store the link | +|**`buflen`**|`size_t`| Size of the buffer | + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`| Return code: <0 for error, >=0 for success | + +### Description + +Store a formatted link corresponding to the current request. + +E.g., returns +`http://mydomain.com:8080/path/to/callback.ext` +or +`http://127.0.0.1:8080/path/to/callback.ext` +depending on the auth check settings. + +### See Also diff --git a/src/civetweb/docs/api/mg_get_response.md b/src/civetweb/docs/api/mg_get_response.md new file mode 100644 index 00000000..3e7b7271 --- /dev/null +++ b/src/civetweb/docs/api/mg_get_response.md @@ -0,0 +1,29 @@ +# Civetweb API Reference + +### `mg_get_response( conn, ebuf, ebuf_len, timeout );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`|The connection to listen on| +|**`ebuf`**|`char *`|Buffer to store an error message| +|**`ebuf_len`**|`size_t`|Size of the error message buffer including the terminating NUL| +|**`timeout`**|`int`|Time to wait for a response in milliseconds| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|Success value of the wait| + +### Description + +The function `mg_get_reponse()` wait for a response from a remote server. A return value equal or greater than zero is an indication for success, a negative value us used to signal an error condition. A timeout can be specified which lets the function return after a specified number of milliseconds, even if no data is received from the remote party. If the timeout value is negative, the function will not return until data has been read or an unrecoverable error occurs. + +Error messages are stored in a caller supplied error message buffer. + +### See Also + +* [`mg_connect_client();`](mg_connect_client.md) +* [`mg_connect_client_secure();`](mg_connect_client_secure.md) diff --git a/src/civetweb/docs/api/mg_get_response_code_text.md b/src/civetweb/docs/api/mg_get_response_code_text.md new file mode 100644 index 00000000..79ffa13c --- /dev/null +++ b/src/civetweb/docs/api/mg_get_response_code_text.md @@ -0,0 +1,25 @@ +# Civetweb API Reference + +### `mg_get_response_code_text( conn, response_code );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`| A pointer referencing the connection | +|**`response_code`**|`int`| Response code for which the text is queried | + +### Return Value + +| Type | Description | +| :--- | :--- | +|`const char *`| A pointer to a human readable text explaining the response code. | + +### Description + +The function `mg_get_response_code_text()` returns a pointer to a human readable text describing the HTTP response code which was provided as a parameter. + +### See Also + +* [`mg_get_builtin_mime_type();`](mg_get_builtin_mime_type.md) +* [`mg_version();`](mg_version.md) diff --git a/src/civetweb/docs/api/mg_get_response_info.md b/src/civetweb/docs/api/mg_get_response_info.md new file mode 100644 index 00000000..40e7ab88 --- /dev/null +++ b/src/civetweb/docs/api/mg_get_response_info.md @@ -0,0 +1,29 @@ +# Civetweb API Reference + +### `mg_get_response_info( conn );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`const struct mg_connection *`|The connection for which the response info is needed| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`const struct mg_request_info *`|Pointer to the requested info, or NULL if an error occured| + +### Description + +The function `mg_response_info()` returns information about a response on a client connection opened by `mg_connect_client()`. If an error occurs, a NULL pointer is returned instead. + +Use this function when implementing a client. + +### See Also + +* [`struct mg_response_info;`](mg_response_info.md) +* [`mg_connect_client();`](mg_connect_client.md) +* [`mg_get_request_info();`](mg_get_request_info.md) +* [`struct mg_request_info;`](mg_request_info.md) + diff --git a/src/civetweb/docs/api/mg_get_server_ports.md b/src/civetweb/docs/api/mg_get_server_ports.md new file mode 100644 index 00000000..323b4701 --- /dev/null +++ b/src/civetweb/docs/api/mg_get_server_ports.md @@ -0,0 +1,28 @@ +# Civetweb API Reference + +### `mg_get_server_ports( ctx, size, ports );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`ctx`**|`const struct mg_context *`|The context for which the server ports are requested| +|**`size`**|`int`|The size of the buffer to store the port information| +|**`ports`**|`struct mg_server_ports *`|Buffer to store the port information| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|The actual number of ports returned, or an error condition| + +### Description + +The `mg_get_server_ports()` returns a list with server ports on which the Civetweb server is listening. The ports are returned for a given context and stored with additional information like the SSL and redirection state in a list of structures. The list of structures must be allocated by the calling routine. The size of the structure is also passed to `mg_get_server_ports()`. + +The function returns the number of items in the list, or a negative value if an error occured. + +### See Also + +* [~~`mg_get_ports();`~~](mg_get_ports.md) +* [`struct mg_server_ports;`](mg_server_ports.md) diff --git a/src/civetweb/docs/api/mg_get_system_info.md b/src/civetweb/docs/api/mg_get_system_info.md new file mode 100644 index 00000000..6add98d5 --- /dev/null +++ b/src/civetweb/docs/api/mg_get_system_info.md @@ -0,0 +1,30 @@ +# Civetweb API Reference + +### `mg_get_system_info( buffer, buflen );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`buffer**|`char *`|A string buffer to store the information| +|**`buflen**|`int`|Size of the string buffer (including space for a terminating 0)| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|Available system information in bytes (excluding the terminating 0)| + +### Description + +The function `mg_get_system_info()` returns information collected for the system +(operating system, compiler, version, ...). +Currently this data is returned as string is in JSON format, but changes to the +format are possible in future versions. The exact content of the JSON object may vary, +depending on the operating system and server version. +This string should be included for support requests. + +### See Also + +* [`mg_get_context_info();`](mg_get_context_info.md) + diff --git a/src/civetweb/docs/api/mg_get_user_connection_data.md b/src/civetweb/docs/api/mg_get_user_connection_data.md new file mode 100644 index 00000000..2e24c134 --- /dev/null +++ b/src/civetweb/docs/api/mg_get_user_connection_data.md @@ -0,0 +1,23 @@ +# Civetweb API Reference + +### `mg_get_user_connection_data( conn );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`const struct mg_connection *`|The connection for which to return the user data| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`void *`|A pointer to the user data, or NULL if no user data was registered with the connection| + +### Description + +The function `mg_get_user_connection_data()` returns the user data associated with a connection. This user data is represented with a pointer which has been prevously registered with a call to [`mg_set_user_connection_data();`](mg_set_user_connection_data.md). With this function it is possible to pass state information between callback functions refering to a specific connection. + +### See Also + +* [`mg_set_user_connection_data();`](mg_set_user_connection_data.md) diff --git a/src/civetweb/docs/api/mg_get_user_data.md b/src/civetweb/docs/api/mg_get_user_data.md new file mode 100644 index 00000000..87bbe04f --- /dev/null +++ b/src/civetweb/docs/api/mg_get_user_data.md @@ -0,0 +1,23 @@ +# Civetweb API Reference + +### `mg_get_user_data( ctx );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`ctx`**|`const struct mg_context *`|The context for which the user data is requested| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`void *`|| + +### Description + +The function `mg_get_user_data()` returns the user data associated with a Civetweb context. This is a pointer value which has previously been used in the call to [`mg_start()`](mg_start.md) to initialize the server context. + +### See Also + +* [`mg_start();`](mg_start.md) diff --git a/src/civetweb/docs/api/mg_get_valid_option_names.md b/src/civetweb/docs/api/mg_get_valid_option_names.md new file mode 100644 index 00000000..c6b43ad7 --- /dev/null +++ b/src/civetweb/docs/api/mg_get_valid_option_names.md @@ -0,0 +1,24 @@ +# Civetweb API Reference + +### ~~`mg_get_valid_option_names();`~~ + +### Parameters + +*none* + +### Return Value + +| Type | Description | +| :--- | :--- | +|`const char **`|An array with strings where the even elements represent the option names, and the odd element the option values The array is NULL terminated.| + +### Description + +The function `mg_get_valid_option_names()` is depricated. Use [`mg_get_valid_options()`](mg_get_valid_options.md) instead. + +This function returns an array with option/value pairs describing the valid configuration options for Civetweb. En element value of NULL signals the end of the list. + +### See Also + +* [`struct mg_option;`](mg_option.md) +* [`mg_get_valid_options();`](mg_get_valid_options.md) diff --git a/src/civetweb/docs/api/mg_get_valid_options.md b/src/civetweb/docs/api/mg_get_valid_options.md new file mode 100644 index 00000000..fd6755eb --- /dev/null +++ b/src/civetweb/docs/api/mg_get_valid_options.md @@ -0,0 +1,22 @@ +# Civetweb API Reference + +### `mg_get_valid_options();` + +### Parameters + +*none* + +### Return Value + +| Type | Description | +| :--- | :--- | +|`const struct mg_option *`|An array with all valid configuration options| + +### Description + +The function `mg_get_valid_options()` returns an array with all valid configuration options of Civetweb. Each element in the array is a structure with three fields which represent the name of the option, the value of the option and the type of the value. The array is terminated with an element for which the name is `NULL`. See for more details about this structure the documentation of [`struct mg_option`](mg_option.md). + +### See Also + +* [`struct mg_option;`](mg_option.md) +* [`mg_start();`](mg_start.md) diff --git a/src/civetweb/docs/api/mg_get_var.md b/src/civetweb/docs/api/mg_get_var.md new file mode 100644 index 00000000..c21c7bbd --- /dev/null +++ b/src/civetweb/docs/api/mg_get_var.md @@ -0,0 +1,30 @@ +# Civetweb API Reference + +### `mg_get_var( data, data_len, var_name, dst, dst_len );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`data`**|`const char *`|Encoded buffer from either POST data or the URI of a GET call| +|**`data_len`**|`size_t`|Size of the encode buffer including the terminating NULL| +|**`var_name`**|`const char *`|Name of the variable to search for| +|**`dst`**|`char *`|Output buffer to store the content of the variable| +|**`dst_len`**|`size_t`|Length of the output buffer| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|The length of the variable or an error code| + +### Description + +The function `mg_get_var()` returns the value of a variable which is passed to the server with either a POST method, or as a parameter in the URI of a GET call. The data pointer passed to the function points to a form-URI encoded buffer. This can either be POST data or the `request_info.query_string`. The name of the searched variable and a buffer to store the results are also parameters to the function. + +The function either returns the length of the variable when successful, **`-1`** if the variable could not be found and **`-2`** if the destination buffer is NULL, has size zero or is too small to store the resulting variable value. + +### See Also + +* [`mg_get_cookie();`](mg_get_cookie.md) +* [`mg_get_var2();`](mg_get_var2.md) diff --git a/src/civetweb/docs/api/mg_get_var2.md b/src/civetweb/docs/api/mg_get_var2.md new file mode 100644 index 00000000..3a47d91a --- /dev/null +++ b/src/civetweb/docs/api/mg_get_var2.md @@ -0,0 +1,31 @@ +# Civetweb API Reference + +### `mg_get_var2( data, data_len, var_name, dst, dst_len, occurrence );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`data`**|`const char *`|Encoded data buffer from either POST data or a GET URI| +|**`data_len`**|`size_t`|The size of the encoded data buffer| +|**`var_name`**|`const char *`|The name of the variable to search for| +|**`dst`**|`char *`|Destination buffer to store the variable content| +|**`dst_len`**|`size_t`|The size of the destination buffer including the terminating NUL| +|**`occurrence`**|`size_t`|The instance index of the wanted variable| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|Length of the variable contents, or an error code| + +### Description + +The function `mg_get_var2()` can be used to return the contents of a variable passed to the server as either POST data, or in the URI in a GET call. The function is somilar to [`mg_get_var()`](mg_get_var.md) but the difference is that `mg_get_var2()` can be used if the same variable is present multiple times in the data. The `occurence` parameter is used to identify which instance of the variable must be returned where **`0`** is used for the first variable with the specified name, **`1`** for the second and so on. + +The function returns the length of the variable content in the return buffer, **`-1`** if a variable with the specified name could not be found and **`-2`** if the pointer to the result buffer is NULL, the size of the result buffer is zero or when the result buffer is too small to contain the variable content and terminating NUL. + +### See Also + +* [`mg_get_cookie();`](mg_get_cookie.md) +* [`mg_get_var();`](mg_get_var.md) diff --git a/src/civetweb/docs/api/mg_handle_form_request.md b/src/civetweb/docs/api/mg_handle_form_request.md new file mode 100644 index 00000000..4a1d888e --- /dev/null +++ b/src/civetweb/docs/api/mg_handle_form_request.md @@ -0,0 +1,24 @@ +# Civetweb API Reference + +### `mg_handle_form_request( conn, fdh );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`|The connection on which form data must be processed| +|**`fdh`**|`struct mg_form_data_handler`|Structure with callback functions to to the heavy work| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|The number of fields processed, or an error code| + +### Description + +The function `mg_handle_form_request()` processes form data on a connection. The function uses callback functions for the heavy lifting which are passed to the function as fields in a [`struct mg_form_data_handler`](mg_form_data_handler.md) structure. The number of processed fields is returned by the function, or a negative value when an error occured. I nthe situation where some fields are processed successfully (for example file downloads) and an error occurs later in the form processing, the function still returns a negative value. It is the responsibility of the calling party to do the necessary cleanup. The calling party should also do the cleanup of any files which are created, but not required anymore later. + +### See Also + +* [`struct mg_form_data_handler;`](mg_form_data_handler.md) diff --git a/src/civetweb/docs/api/mg_header.md b/src/civetweb/docs/api/mg_header.md new file mode 100644 index 00000000..403dc885 --- /dev/null +++ b/src/civetweb/docs/api/mg_header.md @@ -0,0 +1,18 @@ +# Civetweb API Reference + +### `struct mg_header;` + +### Fields + +| Field | Type | Description | +| :--- | :--- | :--- | +|**`name`**|`const char *`| The name of the client request header | +|**`value`**|`const char *`| The value of the client request header | + +### Description + +The structure `mg_header` is used as a sub-structure in the [`struct mg_request_info;`](mg_request_info.md) structure to store the name and value of one HTTP request header as sent by the client. + +### See Also + +* [`struct mg_request_info;`](mg_request_info.md) diff --git a/src/civetweb/docs/api/mg_init_library.md b/src/civetweb/docs/api/mg_init_library.md new file mode 100644 index 00000000..f0d2c469 --- /dev/null +++ b/src/civetweb/docs/api/mg_init_library.md @@ -0,0 +1,44 @@ +# Civetweb API Reference + +### `mg_init_library( feature );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`feature`**|`unsigned`| A bitmask indicating the features to be ininialized | + +### Return Value + +| Type | Description | +| :--- | :--- | +|`unsigned`| A value indicating the initialized features is available. **0** is returned or error | + +### Description + +The function `mg_init_library()` should be called from an application program before using any other function. +It must be called only from one thread (it is not guaranteed to be thread safe). + +This function is new in version 1.9 (as dummy implementation) and effective only from version 1.10. +For compatibility reasons, other functions (such as [`mg_start();`](mg_start.md)) will initialize the required features as well, +but they will no longer do a de-initialization, leaving a memory leak when the library is unloaded. + +The following parameter values can be used: + +| Value | Compilation option | Description | +| :---: | :---: | :--- | +| **1** | NO_FILES | *Able to serve files*. If this feature is available, the webserver is able to serve files directly from a directory tree. | +| **2** | NO_SSL | *Support for HTTPS*. If this feature is available, the webserver van use encryption in the client-server connection. SSLv2, SSLv3, TLSv1.0, TLSv1.1 and TLSv1.2 are supported depending on the SSL library CivetWeb has been compiled with, but which protocols are used effectively when the server is running is dependent on the options used when the server is started. | +| **4** | NO_CGI | *Support for CGI*. If this feature is available, external CGI scripts can be called by the webserver. | +| **8** | USE_IPV6 | *Support IPv6*. The CivetWeb library is capable of communicating over both IPv4 and IPv6, but IPv6 support is only available if it has been enabled at compile time. | +| **16** | USE_WEBSOCKET | Support for web sockets. WebSockets support is available in the CivetWeb library if the proper options has been used during cimpile time. | +| **32** | USE_LUA | *Support for Lua scripts and Lua server pages*. CivetWeb supports server side scripting through the Lua language, if that has been enabled at compile time. Lua is an efficient scripting language which is less resource heavy than for example PHP. | +| **64** | USE_DUKTAPE | *Support for server side JavaScript*. Server side JavaScript can be used for dynamic page generation if the proper options have been set at compile time. Please note that client side JavaScript execution is always available if it has been enabled in the connecting browser. | +| **128** | NO_CACHING | *Support for caching*. The webserver will support caching, if it has not been disabled while compiling the library. | + +The parameters can added using bitwise or. Values above 255 are reserved, the behavior of the function is undefined if any unknown bit is set. + +### See Also + +* [`mg_check_feature( feature );`](api/mg_check_feature.md) +* [`mg_exit_library( feature );`](api/mg_exit_library.md) diff --git a/src/civetweb/docs/api/mg_lock_connection.md b/src/civetweb/docs/api/mg_lock_connection.md new file mode 100644 index 00000000..167f9228 --- /dev/null +++ b/src/civetweb/docs/api/mg_lock_connection.md @@ -0,0 +1,26 @@ +# Civetweb API Reference + +### `mg_lock_connection( conn );` + +### Parameters + +| Parameter | Type | Description | +|**`conn`**|`struct mg_connection *`|The connection to retrieve a lock| + +### Return Value + +*none* + +### Description + +The function `mg_lock_connection()` is specifically for websocket connections to lock connection. Using this function in combination with [`mg_unlock_connection();`](mg_unlock_connection.md) is necessary around [`mg_write()`](mg_write.md) and [`mg_printf()`](mg_printf.md) calls if the code has server-initiated communication, as well as with communication in direct response to a message. + +### See Also + +* [`mg_lock_context();`](mg_lock_context.md) +* [`mg_printf();`](mg_printf.md) +* [`mg_unlock_connection();`](mg_unlock_connection.md) +* [`mg_unlock_context();`](mg_unlock_context.md) +* [`mg_websocket_client_write();`](mg_websocket_client_write.md) +* [`mg_websocket_write();`](mg_websocket_write.md) +* [`mg_write();`](mg_write.md) diff --git a/src/civetweb/docs/api/mg_lock_context.md b/src/civetweb/docs/api/mg_lock_context.md new file mode 100644 index 00000000..8be6bac7 --- /dev/null +++ b/src/civetweb/docs/api/mg_lock_context.md @@ -0,0 +1,23 @@ +# Civetweb API Reference + +### `mg_lock_context( ctx );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`ctx`**|`struct mg_context *`|The context to put the lock on| + +### Return Value + +*none* + +### Description + +The function `mg_lock_context()` can be used to acquire a lock for exclusive access to resources which are shared between connection of threads. The lock is context wide. The lock must be released with a call to [`mg_unlock_context()`](mg_unlock_context.md). + +### See Also + +* [`mg_lock_connection();`](mg_lock_connection.md) +* [`mg_unlock_connection();`](mg_unlock_connection.md) +* [`mg_unlock_context();`](mg_unlock_context.md) diff --git a/src/civetweb/docs/api/mg_md5.md b/src/civetweb/docs/api/mg_md5.md new file mode 100644 index 00000000..067a6a2f --- /dev/null +++ b/src/civetweb/docs/api/mg_md5.md @@ -0,0 +1,24 @@ +# Civetweb API Reference + +### `mg_md5( buf, ... );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`buf`**|`char[33]`|Storage buffer for the calculated MD5 sum| +|**`...`**|`char *, ...`|NULL terminated list of pointers to strings with data| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`char *`|Pointer to the resulting MD5 string| + +### Description + +The function `mg_md5()` caluclates the MD5 checksum of a NULL terminated list of NUL terminated ASCII strings. The MD5 checksum is returned in human readable format as an MD5 string in a caller supplied buffer. + +The function returns a pointer to the supplied result buffer. + +### See Also diff --git a/src/civetweb/docs/api/mg_modify_passwords_file.md b/src/civetweb/docs/api/mg_modify_passwords_file.md new file mode 100644 index 00000000..edb5f021 --- /dev/null +++ b/src/civetweb/docs/api/mg_modify_passwords_file.md @@ -0,0 +1,33 @@ +# Civetweb API Reference + +### `mg_modify_passwords_file( passwords_file_name, domain, user, password );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`passwords_file_name`**|`const char *`|The path to the passwords file| +|**`realm`**|`const char *`|The authentication realm (domain) of the user record| +|**`user`**|`const char *`|Username of the record to be added, changed or deleted| +|**`password`**|`const char *`|Password associated with the user or NULL if the record must be deleted| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|Success or error code| + +### Description + +The function `mg_modify_passwords_file()` allows an application to manipulate .htpasswd files on the fly by adding, deleting and changing user records. This is one of the several ways to implement authentication on the server side. + +If the password parameter is not `NULL` an entry is added to the password file. An existing records is modified in that case. If `NULL` is used as the password the enrty is removed from the file. + +The function returns 1 when successful and 0 if an error occurs. + +### See Also + +* [`mg_check_digest_access_authentication();`](mg_check_digest_access_authentication.md) +* [`mg_send_digest_access_authentication_request();`](mg_send_digest_access_authentication_request.md) + + diff --git a/src/civetweb/docs/api/mg_option.md b/src/civetweb/docs/api/mg_option.md new file mode 100644 index 00000000..dd7f090f --- /dev/null +++ b/src/civetweb/docs/api/mg_option.md @@ -0,0 +1,31 @@ +# Civetweb API Reference + +### `struct mg_option;` + +### Fields + +| Field | Type | Description | +| :--- | :--- | :--- | +|**`name`**|`const char *`|Name of the option| +|**`type`**|`int`|Type of the option| +|**`default_value`**|`const char *`|Value of the option| + +### Description + +A list of valid configuration options of the Civetweb instance can be retrieved with a call to [`mg_get_valid_options()`](mg_get_valid_options.md). This function fills a list of `struct mg_option` structures where the content of each structure represents a configuration option. Each structure contains three fields. One field contains the name of the option, the second contains the value of the option and the third is an identifier used to define the type of the option and how the value contents should be interpreted. + +The field `type` can be one of the following values: + +|Value|Description| +| :--- | :--- | +|**`CONFIG_TYPE_UNKNOWN`**|The type of the option value is unknown| +|**`CONFIG_TYPE_NUMBER`**|The option value is an integer| +|**`CONFIG_TYPE_STRING`**|The option value is a number| +|**`CONFIG_TYPE_FILE`**|The option value is a file name| +|**`CONFIG_TYPE_DIRECTORY`**|The option value is a directory name| +|**`CONFIG_TYPE_BOOLEAN`**|The option value is a boolean| +|**`CONFIG_TYPE_EXT_PATTERN`**|The option value is a list of regular expression patterns| + +### See Also + +* [`mg_get_valid_options();`](mg_get_valid_options.md) diff --git a/src/civetweb/docs/api/mg_printf.md b/src/civetweb/docs/api/mg_printf.md new file mode 100644 index 00000000..8beb9c07 --- /dev/null +++ b/src/civetweb/docs/api/mg_printf.md @@ -0,0 +1,27 @@ +# Civetweb API Reference + +### `mg_printf( conn, fmt, ... );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`|The connection over which the data must be sent| +|**`fmt`**|`const char *`|Format string| +|**`...`**|*various*|Parameters as specified in the format string| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|Number of bytes written or an error code| + +### Description + +The function `mg_printf()` can be used to send formatted strings over a connection. The functionality is comparable to the `printf()` family of functions in the standard C library. The function returns **0** when the connection has been closed, **-1** if an error occurred and otherwise the number of bytes written over the connection. Except for the formatting part, the `mg_printf()` function is identical to the function [`mg_write()`](mg_write.md). + +### See Also + +* [`mg_websocket_client_write();`](mg_websocket_client_write.md) +* [`mg_websocket_write();`](mg_websocket_write.md) +* [`mg_write();`](mg_write.md) diff --git a/src/civetweb/docs/api/mg_read.md b/src/civetweb/docs/api/mg_read.md new file mode 100644 index 00000000..c7ec6c3d --- /dev/null +++ b/src/civetweb/docs/api/mg_read.md @@ -0,0 +1,26 @@ +# Civetweb API Reference + +### `mg_read( conn, buf, len );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`| A pointer referencing the connection | +|**`buf`**|`void *`| A pointer to the location where the received data can be stored | +|**`len`**|`size_t`| The maximum number of bytes to be stored in the buffer | + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`| The number of read bytes, or a status indication | + +### Description + +The function `mg_read()` receives data over an existing connection. The data is handled as binary and is stored in a buffer whose address has been provided as a parameter. The function returns the number of read bytes when successful, the value **0** when the connection has been closed by peer and a negative value when no more data could be read from the connection. + +### See Also + +* [`mg_printf();`](mg_printf.md) +* [`mg_write();`](mg_write.md) diff --git a/src/civetweb/docs/api/mg_request_info.md b/src/civetweb/docs/api/mg_request_info.md new file mode 100644 index 00000000..cad6bbc3 --- /dev/null +++ b/src/civetweb/docs/api/mg_request_info.md @@ -0,0 +1,35 @@ +# Civetweb API Reference + +### `struct mg_request_info;` + +### Fields + +| Field | Type | Description | +| :--- | :--- | :--- | +|**`request_method`**|`const char *`| The request method used by the client for the connection this can be **GET**, **POST** or one of the other common HTTP request methods | +|**`request_uri`**|`const char *`| The absolute, relative or URL-encoded URI as it was sent in the request. Example: "http://mydomain.com:8080/path/to/file.ext" or "/path/to/file.ext", depending on the client. | +|**`local_uri`**|`const char *`| The relative URL-encoded URI as it references the local resource. If the request URI does not reference a resource on the local server, this field is NULL. Example: "/path/to/file.ext" (even if the client used "http://mydomain.com:8080/path/to/file.ext" in the request) | +|~~`uri`~~|`const char *`| *Deprecated. Use* `local_uri` *instead* | +|**`http_version`**|`const char *`| The HTTP version as mentioned in the client request. This can be "1.0", "1.1", etc. | +|**`query_string`**|`const char *`| The HTTP query string, defined as URL part after the first '?' character, not including '?'. NULL if there is no '?'. | +|**`remote_user`**|`const char *`| The name of the authenticated remote user, or NULL if no authentication was used. Only used for HTTP (digest) authentication, not for cookie based authentication. | +|**`remote addr`**|`char[48]`| The IP address of the remote client as a string. This can either represent an IPv4 or an IPv6 address. Example: "127.0.0.1" | +|~~`remote_ip`~~|`long`| *Deprecated. Use* `remote_addr` *instead* | +|**`content_length`**|`long long`| The content length of the request body. This value can be -1 if no content length was provided. The request may still have body data, but the server cannot determine the length until all data has arrived (e.g. when the client closes the connection, or the final chunk of a chunked request has been received). | +|**`remote_port`**|`int`| The port number at the client's side (an integer number between 1 and 65535). | +|**`is_ssl`**|`int`| 1 if the connection is over SSL (https), and 0 if it is a plain connection (http) | +|**`user_data`**|`void *`| A pointer to the `user_data` information which was provided as a parameter to `mg_start()`. | +|**`conn_data`**|`void *`| A pointer to connection specific user data | +|**`num_headers`**|`int`| The number of HTTP request headers sent by the client (see http_headers) | +|**`http_headers`**|`struct mg_header[64]`| Array of structures with the HTTP request headers sent by the client. For the number of filled header fields, ee num_headers. | +|**`client_cert`**|`struct mg_client_cert *`| Pointer to the client certificate information, when available. This field is only filled for https connections using client certificates. | + +### Description + +The `mg_request_info` structure contains the client information of an existing connection. + +### See Also + +* [`struct mg_client_cert;`](mg_client_cert.md) +* [`struct mg_header;`](mg_header.md) +* [`mg_get_request_info();`](mg_get_request_info.md) diff --git a/src/civetweb/docs/api/mg_response_info.md b/src/civetweb/docs/api/mg_response_info.md new file mode 100644 index 00000000..a348dfcd --- /dev/null +++ b/src/civetweb/docs/api/mg_response_info.md @@ -0,0 +1,38 @@ +# Civetweb API Reference + +### `struct mg_response_info;` + +### Fields + +struct mg_response_info { + int status_code; /* E.g. 200 */ + const char *status_text; /* E.g. "OK" */ + const char *http_version; /* E.g. "1.0", "1.1" */ + + long long content_length; /* Length (in bytes) of the request body, + can be -1 if no length was given. */ + + int num_headers; /* Number of HTTP headers */ + struct mg_header + http_headers[MG_MAX_HEADERS]; /* Allocate maximum headers */ +}; + +| Field | Type | Description | +| :--- | :--- | :--- | +|**`status code`**|`int`| The HTTP response code received by the client. | +|**`status_text`**|`const char *`| The textual representation of the HTTP status code. | +|**`http_version`**|`const char *`| The HTTP version as mentioned in the client request. This can be "1.0", "1.1", etc. | +|**`content_length`**|`long long`| The content length of the request body. This value can be -1 if no content length was provided. The request may still have body data, but the server cannot determine the length until all data has arrived (e.g. when the client closes the connection, or the final chunk of a chunked request has been received). | +|**`num_headers`**|`int`| The number of HTTP request headers sent by the client (see http_headers) | +|**`http_headers`**|`struct mg_header[64]`| Array of structures with the HTTP request headers sent by the client. For the number of filled header fields, ee num_headers. | + +Note: This structure is not yet feature complete and will be extended in future versions. + +### Description + +The `mg_response_info` structure contains information on a completed request from a client. + +### See Also + +* [`struct mg_header;`](mg_header.md) +* [`mg_get_response_info();`](mg_get_response_info.md) diff --git a/src/civetweb/docs/api/mg_send_chunk.md b/src/civetweb/docs/api/mg_send_chunk.md new file mode 100644 index 00000000..895ffdc3 --- /dev/null +++ b/src/civetweb/docs/api/mg_send_chunk.md @@ -0,0 +1,31 @@ +# Civetweb API Reference + +### `mg_send_chunk( conn, buf, len );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`| A pointer to the connection to be used to send data | +|**`chunk`**|`const void *`| A pointer to the blob of information to be sent | +|**`chunk_len`**|`size_t`| The amount of bytes to be sent | + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`| An integer indicating the amount of bytes sent, or failure | + +### Description + +The function `mg_send_chunk()` can be used to send a blob of arbitrary data over a connection. +Only use this function after sending a complete HTTP request or response header with "Transfer-Encoding: chunked" set. Otherwise: use `mg_write()`. +The function returns a number **>0** if data was sent, the value **0** when the connection has been closed, and **-1** in case of an error. + +### See Also + +* [`mg_write();`](mg_write.md) +* [`mg_printf();`](mg_print.md) +* [`mg_lock_connection();`](mg_lock_connection.md) +* [`mg_unlock_connection();`](mg_unlock_connection.md) + diff --git a/src/civetweb/docs/api/mg_send_digest_access_authentication_request.md b/src/civetweb/docs/api/mg_send_digest_access_authentication_request.md new file mode 100644 index 00000000..d5af9dad --- /dev/null +++ b/src/civetweb/docs/api/mg_send_digest_access_authentication_request.md @@ -0,0 +1,35 @@ +# Civetweb API Reference + +### `mg_send_digest_access_authentication_request( conn, realm );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`| A pointer to the connection to be used to send data | +|**`realm`**|`const char *`| The requested authentication realm or NULL | + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`| An integer indicating success or failure | + +### Description + +This function can be used to send a HTTP Digest Authentication request to the client. +Browsers will react with repeating the request with user authentication data. +If they do not yet know the user authentication for the requested realm, they will show +a dialog to query username and password. +In case the authentication realm (also called domain) is NULL, the parameter +`authentication_domain` from the server configuration is used. +The function returns a negative number on errors. + +### See Also + +* [`mg_check_digest_access_authentication();`](mg_check_digest_access_authentication.md) +* [`mg_modify_passwords_file();`](mg_modify_passwords_file.md) +* [`mg_send_http_error();`](mg_send_http_error.md) +* [`mg_write();`](mg_write.md) +* [`mg_printf();`](mg_print.md) + diff --git a/src/civetweb/docs/api/mg_send_file.md b/src/civetweb/docs/api/mg_send_file.md new file mode 100644 index 00000000..bffe075d --- /dev/null +++ b/src/civetweb/docs/api/mg_send_file.md @@ -0,0 +1,25 @@ +# Civetweb API Reference + +### `mg_send_file( conn, path );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`|The connection over which the file must be sent| +|**`path`**|`const char *`|The full path and filename of the file| + +### Return Value + +*none* + +### Description + +The function `mg_send_file()` sends the contents of a file over a connection to the remote peer. The function also adds the necessary HTTP headers. + +### See Also + +* [`mg_printf();`](mg_printf.md) +* [`mg_send_mime_file();`](mg_send_mime_file.md) +* [`mg_send_mime_file2();`](mg_send_mime_file2.md) +* [`mg_write();`](mg_write.md) diff --git a/src/civetweb/docs/api/mg_send_http_error.md b/src/civetweb/docs/api/mg_send_http_error.md new file mode 100644 index 00000000..0c18d3e9 --- /dev/null +++ b/src/civetweb/docs/api/mg_send_http_error.md @@ -0,0 +1,32 @@ +# Civetweb API Reference + +### `mg_send_http_error( conn, status_code, fmt, ... );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`|The connection over which the data must be sent| +|**`status_code`**|`int`|The HTTP status code (see HTTP standard)| +|**`fmt`**|`const char *`|Format string for an error message| +|**`...`**|*various*|Parameters as specified in the format string| + +### Return Value + +| Type | Description | +| :--- | :--- | + + +### Description + +The function `mg_send_http_error()` can be used to send HTTP error messages from a server to a client. +The `status_code` must be one of the predefined HTTP standard error codes (e.g., "404" for "Not Found"). +The status text (e.g., "Not Found") for standard error codes is known by this function. +A body of the error message, to explain the error in more detail, can be specified using the `fmt` format specifier and additional arguments. The `fmt` format specifier works like for the `printf()` function in the standard C library. + + +### See Also + +* [`mg_printf();`](mg_printf.md) +* [`mg_write();`](mg_write.md) + diff --git a/src/civetweb/docs/api/mg_send_mime_file.md b/src/civetweb/docs/api/mg_send_mime_file.md new file mode 100644 index 00000000..424b0dc1 --- /dev/null +++ b/src/civetweb/docs/api/mg_send_mime_file.md @@ -0,0 +1,27 @@ +# Civetweb API Reference + +### `mg_send_mime_file( conn, path, mime_type );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`|The connection over which the file must be sent| +|**`path`**|`const char *`|The full path and filename of the file| +|**`mime_type`**|`const char *`|The mime type of the file, or NULL for automatic detection| + +### Return Value + +*none* + +### Description + +The function `mg_send_mime_file()` sends a file over a connection including the HTTP headers. The function is similar to the [`mg_send_file()`](mg_send_file.md) with the additional functionality that the MIME type of the file can be specified. If the `mime_type` parameter is NULL, the routine will try to determine the MIME type based on the extension of the filename. + +### See Also + +* [`mg_get_builtin_mime_type();`](mg_get_builtin_mime_type.md) +* [`mg_printf();`](mg_printf.md) +* [`mg_send_file();`](mg_send_file.md) +* [`mg_send_mime_file2();`](mg_send_mime_file2.md) +* [`mg_write();`](mg_write.md) diff --git a/src/civetweb/docs/api/mg_send_mime_file2.md b/src/civetweb/docs/api/mg_send_mime_file2.md new file mode 100644 index 00000000..1350df8d --- /dev/null +++ b/src/civetweb/docs/api/mg_send_mime_file2.md @@ -0,0 +1,30 @@ +# Civetweb API Reference + +### `mg_send_mime_file2( conn, path, mime_type, additional_headers );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`|The connection over which the file must be sent| +|**`path`**|`const char *`|The full path and filename of the file| +|**`mime_type`**|`const char *`|The mime type or NULL for automatic detection| +|**`additional_headers`**|`const char *`|Additional headers to be sent| + +### Return Value + +*none* + +### Description + +The function `mg_send_mime_file2()` can be used to send a file over a connection. The function is similar to [`mg_send_mime_file()`](mg_send_mime_file.md) with the additional functionality that user specified headers can be sent. The MIME type of the file can be specified in the function call, or will be automatically determined based on the extension of the filename if the `mime_type` parameter has the value NULL. + +Additional custom header fields can be added as a parameter. Please make sure that these header names begin with `X-` to prevent name clashes with other headers. If the `additional_headers` parameter is NULL, no custom headers will be added. + +### See Also + +* [`mg_get_builtin_mime_type();`](mg_get_builtin_mime_type.md) +* [`mg_printf();`](mg_printf.md) +* [`mg_send_file();`](mg_send_file.md) +* [`mg_send_mime_file();`](mg_send_mime_file.md) +* [`mg_write();`](mg_write.md) diff --git a/src/civetweb/docs/api/mg_server_ports.md b/src/civetweb/docs/api/mg_server_ports.md new file mode 100644 index 00000000..e969f032 --- /dev/null +++ b/src/civetweb/docs/api/mg_server_ports.md @@ -0,0 +1,24 @@ +# Civetweb API Reference + +### `struct mg_server_ports;` + +### Fields + +| Field | Type | Description | +| :--- | :--- | :--- | +|**`protocol`**|`int`|The protocol mask where `IPv4` is **1**, `IPv6` is **2** and both `IPv4` and `IPv6` is **3**| +|**`port`**|`int`|The port number on which the service listens| +|**`is_ssl`**|`int`|**0** for `HTTP` communication, **1** for `HTTPS`| +|**`is_redirect`**|`int`|**1** if all requests are redirected, otherwise **0**| +|**`_reserved1`**|`int`|Reserved for internal use| +|**`_reserved2`**|`int`|Reserved for internal use| +|**`_reserved3`**|`int`|Reserved for internal use| +|**`_reserved4`**|`int`|Reserved for internal use| + +### Description + +A call to the function [`mg_get_server_ports()`](mg_get_server_ports.md) returns a list of structures with information about each running Civetweb service. These structures are of type `struct mg_server_ports` and contain the base information of each service. + +### See Also + +* [`mg_get_server_ports();`](mg_get_server_ports.md) diff --git a/src/civetweb/docs/api/mg_set_auth_handler.md b/src/civetweb/docs/api/mg_set_auth_handler.md new file mode 100644 index 00000000..302324ad --- /dev/null +++ b/src/civetweb/docs/api/mg_set_auth_handler.md @@ -0,0 +1,30 @@ +# Civetweb API Reference + +### `mg_set_auth_handler( ctx, uri, handler, cbdata );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`ctx`**|`struct mg_context *`|The context on which the handler must be set| +|**`uri`**|`const char *`|The URI for the authorization handler| +|**`handler`**|`mg_authorization_handler`|Callback function doing the actual authorization| +|**`cbdata`**|`void *`|Optional user data| + +`int mg_authorization_handler( struct mg_connection *conn, void *cbdata );` + +### Return Value + +*none* + +### Description + +The function `mg_set_auth_handler()` hooks an authorization function to an URI to check if a user is authorized to visit that URI. The check is performed by a callback function of type `mg_authorization_handler`. The callback function is passed two parameters: the current connection and a pointer to optional user defined data which was passed to `mg_set_auth_handler()` when the callback was hooked to the URI. + +The callback function can return **0** to deny access, and **1** to allow access. + +The `mg_set_auth_handler()` function is very similar in use to [`mg_set_request_handler()`](mg_set_request_handler.md). + +### See Also + +* [`mg_set_request_handler();`](mg_set_request_handler.md) diff --git a/src/civetweb/docs/api/mg_set_request_handler.md b/src/civetweb/docs/api/mg_set_request_handler.md new file mode 100644 index 00000000..95a09a08 --- /dev/null +++ b/src/civetweb/docs/api/mg_set_request_handler.md @@ -0,0 +1,26 @@ +# Civetweb API Reference + +### `mg_set_request_handler( ctx, uri, handler, cbdata );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`ctx`**|`struct mg_context *`|The context where the handler must be active| +|**`uri`**|`const char *`|The URI to hook the handler on| +|**`handler`**|`mg_request_handler`|Callback function doing the heavy lifting| +|**`cbdata`**|`void *`|Optional user supplied data| + +`int mg_request_handler( struct mg_connection *conn, void *cbdata );` + +### Return Value + +*none* + +### Description + +The function `mg_set_request_handler()` hooks a callback function on a URI. That callback function is called whenever a client requests the specific URI. The callback function receives the connection information and optional user supplied data as parameters and can serve information back to the client. When the callback function does not send any information back to the client, it should return **0** to signal Civetweb that the Civetweb core should handle the request. A return value between 1 and 999 is used to tell Civetweb that the request has been handled and no further processing is necessary. The returned code is stored as the status code in the access log, it is therefore recommended, although not mandatory to return a status code which matches the state of the request. + +### See Also + +* [`mg_set_auth_handler();`](mg_set_auth_handler.md) diff --git a/src/civetweb/docs/api/mg_set_user_connection_data.md b/src/civetweb/docs/api/mg_set_user_connection_data.md new file mode 100644 index 00000000..adafc229 --- /dev/null +++ b/src/civetweb/docs/api/mg_set_user_connection_data.md @@ -0,0 +1,44 @@ +# Civetweb API Reference + +### `mg_set_user_connection_data( conn, data );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`|connection to add the user data| +|**`data`**|`void *`|Pointer to the user data| + +### Return Value + +*none* + +### Description + +The function `mg_set_user_connection_data()` can be used to set a user defined +data pointer attached to a connection. This value can be read using +`mg_get_user_connection_data()`. +Any call to `mg_set_user_connection_data()` will overwrite a previously +assigned user data pointer. + +`mg_set_user_connection_data()` requires a non-const +`struct mg_connection *` to set the user data pointer. It is save to use the +`const struct mg_connection *` passed to a websocket connect handler (with a +const cast), since `const` just means you must not use `mg_read()` or +`mg_write()` in this context. + +Alternatively, you can use the `init_connection` callback in +`struct mg_callbacks` to set the user data pointer. +In this case, typically `init_connection` is used to allocate memory for +a user defined `struct`, while `connection_close` is used to free this +memory again. + + +### See Also + +* [`mg_get_user_connection_data();`](mg_get_user_connection_data.md) +* [`struct mg_callbacks`](mg_callbacks.md) +* [`mg_set_websocket_handler();`](mg_set_websocket_handler.md) +* [`mg_read();`](mg_read.md) +* [`mg_write();`](mg_write.md) + diff --git a/src/civetweb/docs/api/mg_set_websocket_handler.md b/src/civetweb/docs/api/mg_set_websocket_handler.md new file mode 100644 index 00000000..f838c81d --- /dev/null +++ b/src/civetweb/docs/api/mg_set_websocket_handler.md @@ -0,0 +1,30 @@ +# Civetweb API Reference + +### `mg_set_websocket_handler( ctx, uri, connect_handler, ready_handler, data_handler, close_handler, cbdata );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`ctx`**|`mg_context *`|The context in which to add the handlers| +|**`uri`**|`const char *`|The URI for which the handlers should be activated| +|**`connect_handler`**|`mg_websocket_connect_handler`|Handler called when a connect is signalled| +|**`ready_handler`**|`mg_websocket_ready_handler`|Handler called when the connection is ready| +|**`data_handler`**|`mg_websocket_data_handler`|Handler called when data is received| +|**`close_handler`**|`mg_websocket_close_handler`|Handler called when the connection closes| +|**`cbdata`**|`void *`|User defined data| + +`int mg_websocket_connect_handler( const struct mg_connection *conn, void *cbdata );` +`int mg_websocket_ready_handler( struct mg_connection *conn, void *cbdata );` +`int mg_websocket_data_handler( struct mg_connection *conn, int opcode, char * buf, size_t buf_len, void *cbdata );` +`int mg_websocket_close_handler( const struct mg_connection *conn, void *cbdata );` + +### Return Value + +*none* + +### Description + +The function `mg_set_websocket_handler()` connects callback functions to a websocket URI. The callback functions are called when a state change is detected on the URI like an incomming connection or data received from a remote peer. + +### See Also diff --git a/src/civetweb/docs/api/mg_start.md b/src/civetweb/docs/api/mg_start.md new file mode 100644 index 00000000..c597d551 --- /dev/null +++ b/src/civetweb/docs/api/mg_start.md @@ -0,0 +1,39 @@ +# Civetweb API Reference + +### `mg_start( callbacks, user_data, options );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`callbacks`**|`const struct mg_callbacks *`| A structure with optional callback functions to process requests from the web server | +|**`user_data`**|`void *`| A pointer to optional user data | +|**`options`**|`char **`| A list of options used to initialize the web server. The list consists of an NULL terminated list of option-value string pairs. | + +The option list can be used to set the following options: + +| Option | Default | Description | +| :--- | :--- | :--- | +| **`cgi_environment`** | *empty* | The option `cgi_environment` can contain extra variables to be passed to the CGI script in addition to the standard environment variables. The lust must be a comma separated list of name=value pairs like this: `VARIABLE1=VALUE1,VARIABLE2=VALUE2`.| +| **`cgi_interpreter`**| *empty* | The option `cgi_interpreter` can contain a path to an executable which will be used as a CGI interpreter for **all** CGI scripts regardless of the script file extension. If this option is not set (which is the default), CivetWeb looks at the first line of a CGI script to see if an interpreter is defined there. This first line is formatted as a shebang line as common in unix style shell scripts, but this will also work in Windows. For more information about the syntax, please see the Wikipedia page about the [shebang line](http://en.wikipedia.org/wiki/Shebang_(Unix\)).| +| | |For example on a Windows system where both PHP and Perl CGI scripts are used, `#!/path/to/php-cgi.exe` and `#!/path/to/perl.exe` must be the first line of the respective CGI scripts. Note that the paths should be either full file paths, or file paths relative to the current working directory of the CivetWeb server. The current working directory may be dependent on the way the application is started. When started from the command line it is the directory from where the executable was called, but when starting it from a shortcut in a graphical desktop environment, it will be the directory where the executable is located, the default directory of the user or a directory mentioned in the shortcut, depending on the operating system and graphical user interface used.| +| | |If all CGIs use the same interpreter, it is more efficient to set the option `cgi_interpreter` to the path to that executable because in that case no processing of the shebang line is necessary. When using PHP, be sure to point tot php-cgi(.exe) and not the php(.exe) executable, as the latter is a stand alone interpreter which doesn't interface over CGI with CivetWeb. +| **`cgi_pattern`** | `**.cgi$|**.pl$|**.php$` | All files that match `cgi_pattern` are treated as CGI files. The default pattern allows CGI files to be anywhere. To restrict CGIs to a certain directory, use `/path/to/cgi-bin/**.cgi` as a pattern. Note that the full path of the local file is matched against the pattern, not the URI provided in the client request.| +|**`put_delete_auth_file`**| *empty* | The option `put_delete_auth_file` defines the password file to be used for PUT and DELETE requests. Without a password file it is not possible to put new files to the server, or to delete existing ones. This only applies to direct HTTP requests which use the PUT and DELETE methods without server side scripting. PUT and DELETE requests might still be handled by Lua scripts and CGI pages. | + +### Return Value + +| Type | Description | +| :--- | :--- | +|`struct mg_context *`| A pointer to a context structure when successful, or NULL in case of failure | + +### Description + +The function `mg_start()` is the only function needed to call to initialize the webserver. After the function returns and a pointer to a context structure is provided, it is guaranteed that the server has started and is listening on the designated ports. In case of failure a NULL pointer is returned. The behaviour of the web server is controlled by a list of callback functions and a list of options. The callback functions can do application specific processing of events which are encountered by the webserver. If a specific callback function is set to NULL, the webserver uses their default callback routine. The options list controls how the webserver should be started and contains settings for for example the ports to listen on, the maximum number of threads created to handle requests in parallel and if settings for SSL encryption. + +As a side effect on Unix systems, SIGCHLD and SIGPIPE signals will be ignored. If custom processing is needed for these signals, signal handlers must be setup after the call to `mg_start()` has completed. + +### See Also + +* [`struct mg_callbacks;`](mg_callbacks.md) +* [`mg_stop();`](mg_stop.md) diff --git a/src/civetweb/docs/api/mg_start_thread.md b/src/civetweb/docs/api/mg_start_thread.md new file mode 100644 index 00000000..e8172265 --- /dev/null +++ b/src/civetweb/docs/api/mg_start_thread.md @@ -0,0 +1,26 @@ +# Civetweb API Reference + +### `mg_start_thread( func, cbdata );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`func`**|`mg_thread_func_t`|Function to start as a separate thread| +|**`cbdata`**|`void *`|User defined data to be passed to the thread as parameter| + +`void mg_thread_func_t( void *cbdata );` + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|Success or error code| + +### Description + +The function `mg_start_thread()` is a convenience function to create a detached thread. The function returns **0** when successful and another value if an error occured. A pointer to user supplied data can be passed which is then passed further on to the thread function as parameter. + +### See Also + +* [`mg_start();`](mg_start.md) diff --git a/src/civetweb/docs/api/mg_stop.md b/src/civetweb/docs/api/mg_stop.md new file mode 100644 index 00000000..ea0d2466 --- /dev/null +++ b/src/civetweb/docs/api/mg_stop.md @@ -0,0 +1,22 @@ +# Civetweb API Reference + +### `mg_stop( ctx );` + +#### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`ctx`**|**`struct mg_context *`**| A pointer to the current webserver context | + +### Return Value + +*none* + +### Description + +The function `mg_stop()` is used to stop and cleanup a running webserver. A pointer to the context of the running webserver is provided as a parameter. The execution of this function may take some time because it waits until all threads have stopped and returns all memory to the heap. After the function returns, the location the context pointer points to is invalid. The function does not return a return value and it is therefore not possible to know if stopping the webserver succeeded or not. + +### See Also + +* [`mg_start();`](mg_start.md) +* [`mg_start_thread();`](mg_start_thread.md) diff --git a/src/civetweb/docs/api/mg_store_body.md b/src/civetweb/docs/api/mg_store_body.md new file mode 100644 index 00000000..4cde44a9 --- /dev/null +++ b/src/civetweb/docs/api/mg_store_body.md @@ -0,0 +1,24 @@ +# Civetweb API Reference + +### `mg_store_body( conn, path );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`|connection on which to read the data| +|**`path`**|`const char *`|file to store the request body| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`long long`|Number of bytes written to the file, or an error code| + +### Description + +The function `mg_store_body()` stores the body of an incoming request to a data file. The function returns the number of bytes stored in the file, or a negative value to indicate an error. + +### See Also + +* [`mg_read();`](mg_read.md) diff --git a/src/civetweb/docs/api/mg_strcasecmp.md b/src/civetweb/docs/api/mg_strcasecmp.md new file mode 100644 index 00000000..cba6b922 --- /dev/null +++ b/src/civetweb/docs/api/mg_strcasecmp.md @@ -0,0 +1,24 @@ +# Civetweb API Reference + +### `mg_strcasecmp( s1, s2 );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`s1`**|`const char *`|First string to compare| +|**`s2`**|`const char *`|Second string to compare| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|Integer value with the result of the comparison| + +### Description + +The function `mg_strcasecmp()` is a helper function to compare two strings. The comparison is case insensitive. The return value is **0** if both strings are equal, less then zero if the first string is less than the second in a lexical comparison, and greater than zero if the first string is greater than the second. + +### See Also + +* [`mg_strncasecmp();`](mg_strncasecmp.md) diff --git a/src/civetweb/docs/api/mg_strncasecmp.md b/src/civetweb/docs/api/mg_strncasecmp.md new file mode 100644 index 00000000..b4affd66 --- /dev/null +++ b/src/civetweb/docs/api/mg_strncasecmp.md @@ -0,0 +1,25 @@ +# Civetweb API Reference + +### `mg_strncasecmp( s1, s2, len );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`s1`**|`const char *`|First string in the comparison| +|**`s2`**|`const char *`|Second string in the comparison| +|**`len`**|`size_t`|The maximum number of characters to compare| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|The result of the comparison| + +### Description + +The function `mg_strncasecmp()` is a helper function to compare two strings. The comparison is case insensitive and only a limited number of characters are compared. This limit is provided as third parameter in the function call. The return value is **0** if both strings are equal, less then zero if the first string is less than the second in a lexical comparison, and greater than zero if the first string is greater than the second. + +### See Also + +* [`mg_strcasecmp();`](mg_strcasecmp.md) diff --git a/src/civetweb/docs/api/mg_unlock_connection.md b/src/civetweb/docs/api/mg_unlock_connection.md new file mode 100644 index 00000000..b74138fd --- /dev/null +++ b/src/civetweb/docs/api/mg_unlock_connection.md @@ -0,0 +1,27 @@ +# Civetweb API Reference + +### `mg_unlock_connection( conn );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`|Connection to remove the lock from| + +### Return Value + +*none* + +### Description + +The function `mg_unlock_connection()` removes the lock on a connection which was previously set with a call to [`mg_lock_connection()`](mg_lock_connection.md). Locking may be necessary when using [`mg_write()`](mg_write.md) or [`mg_printf()`](mg_printf.md) on websocket connections to prevent data corruption. + +### See Also + +* [`mg_lock_connection();`](mg_lock_connection.md) +* [`mg_lock_context();`](mg_lock_context.md) +* [`mg_printf();`](mg_printf.md) +* [`mg_unlock_context();`](mg_unlock_context.md) +* [`mg_websocket_client_write();`](mg_websocket_client_write.md) +* [`mg_websocket_write();`](mg_websocket_write.md) +* [`mg_write();`](mg_write.md) diff --git a/src/civetweb/docs/api/mg_unlock_context.md b/src/civetweb/docs/api/mg_unlock_context.md new file mode 100644 index 00000000..a630acd7 --- /dev/null +++ b/src/civetweb/docs/api/mg_unlock_context.md @@ -0,0 +1,23 @@ +# Civetweb API Reference + +### `mg_unlock_context( ctx );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`ctx`**|`struct mg_context *`|The context to remove the lock from| + +### Return Value + +*none* + +### Description + +The function `mg_unlock_contect()` removes a lock put previously on a context with a call to [`mg_lock_context()`](mg_lock_context.md). Locking a context may be necessary when accessing shared resources. + +### See Also + +* [`mg_lock_connection();`](mg_lock_connection.md) +* [`mg_lock_context();`](mg_lock_context.md) +* [`mg_unlock_connection();`](mg_unlock_connection.md) diff --git a/src/civetweb/docs/api/mg_upload.md b/src/civetweb/docs/api/mg_upload.md new file mode 100644 index 00000000..de7f1c8d --- /dev/null +++ b/src/civetweb/docs/api/mg_upload.md @@ -0,0 +1,22 @@ +# Civetweb API Reference + +### ~~`mg_upload( conn, destination_dir );`~~ + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`|Connection on which files to upload| +|**`destination_dir`**|`const char *`|The destination directory to upload to| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|Success or error code| + +### Description + +The function `mg_upload()` is deprecated and may be removed from future releases. Use of this function is therefore highly discouraged. + +### See Also diff --git a/src/civetweb/docs/api/mg_url_decode.md b/src/civetweb/docs/api/mg_url_decode.md new file mode 100644 index 00000000..67940884 --- /dev/null +++ b/src/civetweb/docs/api/mg_url_decode.md @@ -0,0 +1,27 @@ +# Civetweb API Reference + +### `mg_url_decode( src, src_len, dst, dst_len, is_form_url_encoded );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`src`**|`const char *`|Source data to convert| +|**`src_len`**|`int`|Length of the source buffer| +|**`dst`**|`char *`|Destination buffer to store the result| +|**`dst_len`**|`int`|Length of the destination buffer| +|**`is_form_url_encoded`**|`int`|Not equal zero when form decoding must be used| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|The number of bytes stored in the destination buffer, or **-1** if the buffer doesn't exist or is too small| + +### Description + +The function `mg_url_decode()` Decodes a in input buffer. Both normal URIs and form URIs can be decoded. In the latter case the space character is converted to a `+` as defined in [RFC 1866](http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt) in section 8.2.1. + +### See Also + +* [`mg_url_encode();`](mg_url_encode.md) diff --git a/src/civetweb/docs/api/mg_url_encode.md b/src/civetweb/docs/api/mg_url_encode.md new file mode 100644 index 00000000..465af122 --- /dev/null +++ b/src/civetweb/docs/api/mg_url_encode.md @@ -0,0 +1,25 @@ +# Civetweb API Reference + +### `mg_url_encode( src, dst, des_len );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`src`**|`const char *`|Input string to encode| +|**`dst`**|`char *`|Destination buffer to store the encoded result| +|**`dst_len`**|`size_t`|Length of the destination buffer including the terminating NUL| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|The number of characters written in the destination buffer| + +### Description + +The function `mg_url_encode()` encodes a in input buffer. Both normal URIs and form URIs can be encoded. In the latter case the space character is converted to a `+` as defined in [RFC 1866](http://ftp.ics.uci.edu/pub/ietf/html/rfc1866.txt) in section 8.2.1. + +### See Also + +* [`mg_url_decode();`](mg_url_decode.md) diff --git a/src/civetweb/docs/api/mg_version.md b/src/civetweb/docs/api/mg_version.md new file mode 100644 index 00000000..a31128b5 --- /dev/null +++ b/src/civetweb/docs/api/mg_version.md @@ -0,0 +1,19 @@ +# Civetweb API Reference + +### `mg_version();` + +### Parameters + +*none* + +### Return Value + +| Type | Description | +| :--- | :--- | +|`const char *`| A pointer to a text with the current CivetWeb version | + +### Description + +The function `mg_version()` can be used to return the current CivetWeb version. The function returns a pointer to a string with the current major and minor version number separated with a dot, for example "1.9". + +### See Also diff --git a/src/civetweb/docs/api/mg_websocket_client_write.md b/src/civetweb/docs/api/mg_websocket_client_write.md new file mode 100644 index 00000000..f792f4c7 --- /dev/null +++ b/src/civetweb/docs/api/mg_websocket_client_write.md @@ -0,0 +1,32 @@ +# Civetweb API Reference + +### `mg_websocket_client_write( conn, opcode, data, data_len );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`|Connection on which to send data| +|**`opcode`**|`int`|Opcode| +|**`data const`**|`char *`|The data to be written| +|**`data_len`**|`size_t`|Length of the data buffer| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|Number of bytes written or an error code| + +### Description + +The function `mg_websocket_client_write()` sends data to a websocket server wrapped in a masked websocket frame. The function issues calls to [`mg_lock_connection()`](mg_lock_connection.md) and [`mg_unlock_connection()`](mg_unlock_connection.md) to ensure that the transmission is not interrupted. Interruption can happen the the application is proactively communicating and responding to a request simultaneously. This function is available only, if Civetweb is compiled with the option `-DUSE_WEBSOCKET`. + +The return value is the number of bytes written on success, **0** when the connection has been closed and **-1** if an error occured. + +### See Also + +* [`mg_lock_connection();`](mg_lock_connection.md) +* [`mg_printf();`](mg_printf.md) +* [`mg_unlock_connection();`](mg_unlock_connection.md) +* [`mg_websocket_write();`](mg_websocket_write.md) +* [`mg_write();`](mg_write.md) diff --git a/src/civetweb/docs/api/mg_websocket_write.md b/src/civetweb/docs/api/mg_websocket_write.md new file mode 100644 index 00000000..3c7eadc7 --- /dev/null +++ b/src/civetweb/docs/api/mg_websocket_write.md @@ -0,0 +1,34 @@ +# Civetweb API Reference + +### `mg_websocket_write( conn, opcode, data, data_len );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`|Connection on which the data must be written| +|**`opcode`**|`int`|Opcode| +|**`data`**|`const char *`|Data to be written to the client| +|**`data_len`**|`size_t`|Length of the data| + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`|Number of bytes written or an error code| + +### Description + +The function `mg_websocket_write()` sends data to a websocket client wrapped in a websocket frame. The function issues calls to [`mg_lock_connection()`](mg_lock_connection.md) and [`mg_unlock_connection()`](mg_unlock_connection.md) to ensure that the transmission is not interrupted. Data corruption can otherwise happen if the application is proactively communicating and responding to a request simultaneously. + +The function is available only when Civetweb is compiled with the `-DUSE_WEBSOCKET` option. + +The function returns the number of bytes written, **0** when the connection has been closed and **-1** if an error occurred. + +### See Also + +* [`mg_lock_connection();`](mg_lock_connection.md) +* [`mg_printf();`](mg_printf.md) +* [`mg_unlock_connection();`](mg_unlock_connection.md) +* [`mg_websocket_client_write();`](mg_websocket_client_write.md) +* [`mg_write();`](mg_write.md) diff --git a/src/civetweb/docs/api/mg_write.md b/src/civetweb/docs/api/mg_write.md new file mode 100644 index 00000000..d501857b --- /dev/null +++ b/src/civetweb/docs/api/mg_write.md @@ -0,0 +1,29 @@ +# Civetweb API Reference + +### `mg_write( conn, buf, len );` + +### Parameters + +| Parameter | Type | Description | +| :--- | :--- | :--- | +|**`conn`**|`struct mg_connection *`| A pointer to the connection to be used to send data | +|**`buf`**|`const void *`| A pointer to the blob of information to be sent | +|**`len`**|`size_t`| The amount of bytes to be sent | + +### Return Value + +| Type | Description | +| :--- | :--- | +|`int`| An integer indicating the amount of bytes sent, or failure | + +### Description + +The function `mg_write()` can be used to send a blob of arbitrary data over a connection. The size of the data is provided as a parameter. The only length limitation on this function is `MAX_INT`, because the return value of this function will turn negative with larger blocks of data, although they may have been sent correctly. The function returns the amount of bytes sent in case of success, the value **0** when the connection has been closed, and **-1** in case of an error. + +### See Also + +* [`mg_lock_connection();`](mg_lock_connection.md) +* [`mg_printf();`](mg_print.md) +* [`mg_unlock_connection();`](mg_unlock_connection.md) +* [`mg_websocket_client_write();`](mg_websocket_client_write.md) +* [`mg_websocket_write();`](mg_websocket_write.md) diff --git a/src/civetweb/docs/yaSSL.md b/src/civetweb/docs/yaSSL.md new file mode 100644 index 00000000..7f2e85f8 --- /dev/null +++ b/src/civetweb/docs/yaSSL.md @@ -0,0 +1,87 @@ +Adding wolfSSL (formerly CyaSSL) support +===== + +In order to support SSL *HTTPS* connections in Civetweb, +you may wish to use the GPLv2 licensed CyaSSL library. By using this +library, the resulting binary may have to have the GPL license unless +you buy a commercial license from [wolfSSL](http://www.yassl.com/). + +*Note: The following instructions have not been checked for the most recent versions of CivetWeb and wolfSSL. Some information might be outdated.* + + +Getting Started +---- + +- Download Cayssl at https://www.wolfssl.com (formerly http://www.yassl.com/) +- Extract the zip file + - To make this seemless, extract to a directory parallel to with Civetweb is + +### Example Project + +If you download cyaSSL to cyassl-2.7.0 in a directory parallel to Civetweb, you can open the *VS/civetweb_yassl* solution in Visual Studio. + +Build Configuration +---- + +#### Required include paths for both civetweb and cyassl + - *cyassl_directory*\ + - *cyassl_directory*\cyassl\ + +#### Required civetweb preprocessor defines + - USE_YASSL + - NO_SSL_DL + +#### Required cySSL preprocessor defines + - OPENSSL_EXTRA + - HAVE_ERRNO_H + - HAVE_GETHOSTBYNAME + - HAVE_INET_NTOA + - HAVE_LIMITS_H + - HAVE_MEMSET + - HAVE_SOCKET + - HAVE_STDDEF_H + - HAVE_STDLIB_H + - HAVE_STRING_H + - HAVE_SYS_STAT_H + - HAVE_SYS_TYPES_H + +#### Required CyaSSL source files + + - ctaocrypt/src/aes.c + - ctaocrypt/src/arc4.c + - ctaocrypt/src/asn.c + - ctaocrypt/src/coding.c + - ctaocrypt/src/des3.c + - ctaocrypt/src/dh.c + - ctaocrypt/src/dsa.c + - ctaocrypt/src/ecc.c + - ctaocrypt/src/error.c + - ctaocrypt/src/hc128.c + - ctaocrypt/src/hmac.c + - ctaocrypt/src/integer.c + - ctaocrypt/src/logging.c + - ctaocrypt/src/md2.c + - ctaocrypt/src/md4.c + - ctaocrypt/src/md5.c + - ctaocrypt/src/memory.c + - ctaocrypt/src/misc.c + - ctaocrypt/src/pwdbased.c + - ctaocrypt/src/rabbit.c + - ctaocrypt/src/random.c + - ctaocrypt/src/ripemd.c + - ctaocrypt/src/rsa.c + - ctaocrypt/src/sha.c + - ctaocrypt/src/sha256.c + - ctaocrypt/src/sha512.c + - ctaocrypt/src/tfm.c + - src/crl.c + - src/internal.c + - src/io.c + - src/keys.c + - src/ocsp.c + - src/sniffer.c + - src/ssl.c + - src/tls.c + + + |