civetweb/docs/APIReference.md

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. This document describes the public C API. Basic usage examples of the API can be found in Embedding.md, as well as in the examples directory.

A C++ wrapper for some basic features is also available. Note that only a small subset of the functionality available through the C API can be accessed using this C++ wrapper. The C++ wrapper is not unit tested, and there is no C++ API documentation equivalent to this C API documentation.

Macros

Macro	Description
CIVETWEB_VERSION	The current version of the software as a string with the major and minor version number separated with a dot. For version 1.9, this string will have the value "1.9", for the 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_callbacks;
• struct mg_client_cert;
• struct mg_client_options;
• struct mg_error_data;
• struct mg_form_data_handler;
• struct mg_header;
• struct mg_init_data;
• struct mg_option;
• struct mg_request_info;
• struct mg_response_info;
• struct mg_server_port;
• struct mg_websocket_subprotocols;

Library API Functions

• mg_init_library( feature );

• mg_exit_library( feature );

• mg_check_feature( feature );

• mg_version();

Server API Functions

• mg_start( callbacks, user_data, options );

• mg_start2( init, error );

• mg_start_domain( ctx, configuration_options );

• mg_start_domain2( ctx, configuration_options, error );

• mg_stop( ctx );

• mg_get_builtin_mime_type( file_name );

• mg_get_option( ctx, name );

• mg_get_server_ports( ctx, size, ports );

• mg_get_user_data( ctx );

• mg_set_auth_handler( ctx, uri, handler, cbdata );

• mg_set_request_handler( ctx, uri, handler, cbdata );

• mg_set_websocket_handler( ctx, uri, connect_handler, ready_handler, data_handler, close_handler, cbdata );

• mg_set_websocket_handler_with_subprotocols( ctx, uri, subprotocols, connect_handler, ready_handler, data_handler, close_handler, cbdata );

• mg_lock_context( ctx );

• mg_unlock_context( ctx );

• mg_get_context( conn );

• mg_send_http_error( conn, status_code, fmt, ... );

• mg_send_http_ok( conn, mime_type, content_length );

• mg_send_http_redirect( conn, target_url, redirect_code );

• mg_send_digest_access_authentication_request( conn, realm );

• mg_check_digest_access_authentication( conn, realm, filename );

• mg_modify_passwords_file( passwords_file_name, realm, user, password );

• mg_modify_passwords_file_ha1( passwords_file_name, realm, user, ha1 );

• mg_get_request_info( conn );

• mg_get_request_link( conn, buf, buflen );

• mg_handle_form_request( conn, fdh );

• mg_send_file( conn, path );

• mg_send_mime_file( conn, path, mime_type );

• mg_send_mime_file2( conn, path, mime_type, additional_headers );

• mg_websocket_write( conn, opcode, data, data_len );

• mg_response_header_*();

Client API Functions

• mg_connect_client( host, port, use_ssl, error_buffer, error_buffer_size );

• mg_connect_client_secure( client_options, error_buffer, error_buffer_size );

• mg_connect_websocket_client( host, port, use_ssl, error_buffer, error_buffer_size, path, origin, data_func, close_func, user_data);

• mg_websocket_client_write( conn, opcode, data, data_len );

• mg_download( host, port, use_ssl, error_buffer, error_buffer_size, fmt, ... );

• mg_get_response( conn, ebuf, ebuf_len, timeout );

• mg_get_response_info( conn );

• mg_connect_client2( host, protocol, port, path, init, error );

• mg_get_response2( conn, error, timeout );

Common API Functions

• mg_close_connection( conn );

• mg_cry( conn, fmt, ... );

• mg_get_cookie( cookie, var_name, buf, buf_len );

• mg_get_header( conn, name );

• mg_get_response_code_text( conn, response_code );

• mg_get_user_connection_data( conn );

• mg_get_valid_options();

• mg_get_var( data, data_len, var_name, dst, dst_len );

• mg_get_var2( data, data_len, var_name, dst, dst_len, occurrence );

• mg_lock_connection( conn );

• mg_md5( buf, ... );

• mg_printf( conn, fmt, ... );

• mg_read( conn, buf, len );

• mg_send_chunk( conn, buf, len );

• mg_send_file_body( conn, path );

• mg_set_user_connection_data( conn, data );

• mg_split_form_urlencoded( data, form_fields, num_form_fields);

• mg_start_thread( f, p );

• mg_store_body( conn, path );

• mg_strcasecmp( s1, s2 );

• mg_strncasecmp( s1, s2, len );

• mg_unlock_connection( conn );

• mg_url_decode( src, src_len, dst, dst_len, is_form_url_encoded );

• mg_url_encode( src, dst, dst_len );

• mg_write( conn, buf, len );

Diagnosis Functions

• mg_get_system_info( buffer, buf_len );
• mg_get_context_info( ctx, buffer, buf_len );
• mg_get_connection_info( ctx, idx, buffer, buf_len );

Deprecated / removed:

• mg_get_valid_option_names();
• mg_upload( conn, destination_dir );
• mg_get_ports( ctx, size, ports, ssl);