Appweb API

Embedthis Appweb HTTP Web Server header.

Description:

This header provides the core API for the Embedthis Appweb embedded web server. Appweb is a compact, fast embedded web server supporting HTTP/1 and HTTP/2 protocols. It includes configuration parsing, module loading, and server management functionality.

API Stability:

Stable

Function Index

int	httpCgiInit(Http http, MprModule mp)
	Initialize the CGI handler module.
void	maAddDirective(cchar *directive, MaDirective proc)
	Define a new appweb configuration file directive.
int	maConfigureServer(cchar configFile, cchar home, cchar documents, cchar ip, int port)
	Configure a web server.
char *	maGetNextArg(char s, char *tok)
	Get the next argument in a directive.
int	maLoadModule(cchar name, cchar libname)
	Load an appweb module.
int	maLoadModules(void)
	Load default modules.
int	maParseConfig(cchar *path)
	Parse an Appweb configuration file.
int	maParseFile(MaState state, cchar path)
	Parse a configuration file with state context.
MaState *	maPopState(MaState *state)
	Pop the state.
MaState *	maPushState(MaState *state)
	Push the state.
int	maRunSimpleWebServer(cchar ip, int port, cchar home, cchar *documents)
	Create and run a simple web server listening on a single IP address.
int	maRunWebServer(cchar *configFile)
	Create and run a web server based on a configuration file.
bool	maTokenize(MaState state, cchar str, cchar *fmt, ...)
	Tokenize a string based on route data.
int	maTraceDirective(MaState state, HttpTrace trace, cchar key, cchar value)
	Process trace directive.
int	maTraceLogDirective(MaState state, HttpTrace trace, cchar key, cchar value)
	Process trace log directive.
int	maWriteAuthFile(HttpAuth auth, char path)
	Save the authorization configuration to a file.

Typedef Index

MaDirective	Appweb configuration file directive parsing callback function.
MaState	Current configuration parse state.

Defines

#define	MA_PARSE_NON_SERVER 0x1
	Command file being parsed by a utility program.
#define	MA_UNLOAD_TIMEOUT "5mins"
	Default module inactivity timeout.
#define	ME_COM_ESP 0
	Enable ESP web framework (separate add-on product).
#define	ME_COM_FAST 0
	Enable FastCGI protocol support.
#define	ME_COM_MDB 0
	Enable Memory Database support.
#define	ME_COM_PROXY 0
	Enable HTTP proxy functionality.
#define	ME_COM_SDB 0
	Enable SQLite Database support.
#define	ME_COM_SSL 0
	Enable SSL/TLS secure communications.
#define	ME_COM_TEST 1
	Enable test handler module.
#define	ME_COM_TEST_WEBSOCKETS 1
	Enable WebSocket test functionality.

Typedefs

typedef int() MaDirective(MaState *state, cchar *key, cchar *value)

Appweb configuration file directive parsing callback function.

Description:: Directive callbacks are invoked to parse a directive. Directive callbacks are registered using maAddDirective. The callback receives the current parsing state and the directive key-value pair to process. The function should parse the directive value and update the configuration accordingly.

Parameters:

state	Current config parse state.
key	Directive key name.
value	Directive key value.

Returns:: Zero if successful, otherwise a negative MPR error code. See the Appweb log for diagnostics.

API Stability:: Stable.

MaState

Current configuration parse state.

Description:: Structure that maintains the parsing state when processing Appweb configuration files. This state is used to track the current host, route, authentication settings, and other context information during configuration file parsing. The state can be pushed and popped to handle nested configuration blocks and include files.

Fields:

HttpAuth *	auth	Quick alias for route->auth.
char *	configDir	Directory containing config file.
struct MaState *	current	Current state.
char *	data	Config data (managed).
int	enabled	True if the current block is enabled.
char *	endpoints	Virtual host endpoints.
MprFile *	file	Config file handle.
char *	filename	Config file name.
int	flags	Parsing flags.
HttpHost *	host	Current host.
char *	key	Current directive being parsed.
int	lineNumber	Current line number.
struct MaState *	prev	Previous (inherited) state.
HttpRoute *	route	Current route.
struct MaState *	top	Top level state.

API Stability:: Internal.

Functions

int httpCgiInit (Http *http, MprModule *mp)

Initialize the CGI handler module.

Description:: Initialize the CGI (Common Gateway Interface) handler module for processing CGI scripts.

Parameters:

http	HTTP service object.
mp	Module object for the CGI handler.

Returns:: Zero if successful, otherwise a negative MPR error code.

API Stability:: Internal.

void maAddDirective (cchar *directive, MaDirective proc)

Define a new appweb configuration file directive.

Description:: The appweb configuration file parser is extensible. New directives can be registered by this call. When encountered in the config file, the given callback procedure will be invoked to parse the directive. This allows custom modules to extend the configuration syntax.

Parameters:

directive	Directive name.
proc	Directive callback procedure of the type MaDirective.

API Stability:: Stable.

int maConfigureServer (cchar *configFile, cchar *home, cchar *documents, cchar *ip, int port)

Configure a web server.

Description:: This will configure a web server based on either a configuration file or using the supplied IP address and port. Parameters provided will override corresponding values in the configuration file. This function provides a convenient way to programmatically configure the server while still using a base configuration file.

Parameters:

configFile	File name of the Appweb configuration file (appweb.conf) that defines the web server configuration.
home	Admin directory for the server. This overrides the value in the config file.
documents	Default directory for web documents to serve. This overrides the value in the config file.
ip	IP address to listen on. This overrides the value specified in the config file.
port	Port address to listen on. This overrides the value specified in the config file.

Returns:: Zero if successful, otherwise a negative MPR error code. See the Appweb log for diagnostics.

API Stability:: Stable.

char * maGetNextArg (char *s, char **tok)

Get the next argument in a directive.

Description:: Break a string into arguments. Arguments may be quoted and an outer quoting of the entire argument is removed. This function modifies the input string by inserting null terminators to separate arguments.

Parameters:

s	String to examine and tokenize.
tok	Pointer to store the reference to the next token.

Returns:: Pointer to the current token (not allocated, points into the original string).

API Stability:: Stable.

int maLoadModule (cchar *name, cchar *libname)

Load an appweb module.

Description:: Load an appweb module. If the module is already loaded, this call will return successfully without reloading. Modules can be dynamically loaded or may also be pre-loaded using static linking. The module name should correspond to the module's initialization function name.

Parameters:

name	Module name used for identification and to locate the initialization function.
libname	Library path name for dynamic loading, or NULL for statically linked modules.

Returns:: Zero if successful, otherwise a negative MPR error code. See the Appweb log for diagnostics.

API Stability:: Stable.

int maLoadModules (void )

Load default modules.

Description:: Load all the default Appweb modules including CGI, ESP, proxy, and test modules based on the compile-time configuration. This function is typically called during server initialization.

Returns:: Zero if successful, otherwise a negative MPR error code. See the Appweb log for diagnostics.

API Stability:: Stable.

int maParseConfig (cchar *path)

Parse an Appweb configuration file.

Description:: Parse the configuration file and configure the server. This creates a default host and route and then configures the server based on config file directives. This is the primary function for initializing the server from a configuration file.

Parameters:

path	Configuration file pathname.

Returns:: Zero if successful, otherwise a negative MPR error code. See the Appweb log for diagnostics.

API Stability:: Stable.

int maParseFile (MaState *state, cchar *path)

Parse a configuration file with state context.

Description:: Parse a configuration file within the context of the given state. This is used internally for parsing include files and nested configuration blocks. The state maintains the parsing context including current host, route, and authentication settings.

Parameters:

state	Current state level object containing parsing context.
path	Filename to parse.

Returns:: Zero if successful, otherwise a negative MPR error code. See the Appweb log for diagnostics.

API Stability:: Stable.

MaState * maPopState (MaState *state)

Pop the state.

Description:: This is used when parsing config files to handle nested include files and block level directives. When exiting a configuration block or include file, this function restores the previous parsing state.

Parameters:

state

Current state to pop.

Returns:: The next lower level state object, or NULL if at the top level.

API Stability:: Stable.

MaState * maPushState (MaState *state)

Push the state.

Description:: This is used when parsing config files to handle nested include files and block level directives. When entering a configuration block or include file, this function saves the current state and creates a new parsing context.

Parameters:

state

Current state to push.

Returns:: The state passed as a parameter which becomes the new top level state.

API Stability:: Stable.

int maRunSimpleWebServer (cchar *ip, int port, cchar *home, cchar *documents)

Create and run a simple web server listening on a single IP address.

Description:: Create a simple web server without using a configuration file. The server is created to listen on the specified IP address and port. This routine provides a one-line embedding of Appweb. If you want to use a config file, try the maRunWebServer instead.

Parameters:

ip	IP address on which to listen. Set to "0.0.0.0" to listen on all interfaces.
port	Port number to listen on.
home	Home directory for the web server.
documents	Directory containing the documents to serve.

Returns:: Zero if successful, otherwise a negative MPR error code. See the Appweb log for diagnostics.

API Stability:: Stable.

int maRunWebServer (cchar *configFile)

Create and run a web server based on a configuration file.

Description:: Create a web server configuration based on the supplied config file. This routine provides a one-line embedding of Appweb. If you don't want to use a config file, try the maRunSimpleWebServer instead.

Parameters:

configFile

File name of the Appweb configuration file (appweb.conf) that defines the web server configuration.

Returns:: Zero if successful, otherwise a negative MPR error code. See the Appweb log for diagnostics.

API Stability:: Stable.

bool maTokenize (MaState *state, cchar *str, cchar *fmt, ...)

Tokenize a string based on route data.

Description:: This is a utility routine to parse a string into tokens given a format specifier. Mandatory tokens can be specified with "%" format specifier. Optional tokens are specified with "?" format. Values wrapped in quotes will have the outermost quotes trimmed.

Parameters:

state	Current config parsing state.
str	String to tokenize and parse.
fmt	Format string specifier defining expected token types Supported token format specifiers: B - Boolean. Parses: on/off, true/false, yes/no N - Number. Parses numbers in base 10 S - String. Removes quotes P - Path string. Removes quotes and expands ${PathVars}. Resolved relative to host->dir (ServerRoot) W - Parse words into a list %! - Optional negate. Set value to HTTP_ROUTE_NOT present, otherwise zero

Returns:: True if the string can be successfully parsed.

API Stability:: Stable.

int maTraceDirective (MaState *state, HttpTrace *trace, cchar *key, cchar *value)

Process trace directive.

Description:: Internal function to process trace configuration directives for HTTP request/response tracing.

Parameters:

state	Current configuration parsing state.
trace	HTTP trace object.
key	Directive key name.
value	Directive value.

Returns:: Zero if successful, otherwise a negative MPR error code.

API Stability:: Internal.

int maTraceLogDirective (MaState *state, HttpTrace *trace, cchar *key, cchar *value)

Process trace log directive.

Description:: Internal function to process trace log configuration directives for configuring trace logging.

Parameters:

state	Current configuration parsing state.
trace	HTTP trace object.
key	Directive key name.
value	Directive value.

Returns:: Zero if successful, otherwise a negative MPR error code.

API Stability:: Internal.

int maWriteAuthFile (HttpAuth *auth, char *path)

Save the authorization configuration to a file.

Description:: Write the current authorization configuration to a file using the AuthFile schema format. The file format consists of user and role definitions with their associated capabilities. AuthFile schema: User name password abilities... Role name abilities.

Parameters:

auth	Auth object allocated by httpCreateAuth.
path	Path name of file to write.

Returns:: Zero if successful, otherwise a negative MPR error code.

API Stability:: Internal.