APPWEB API

Extensions

Current configuration parse state.

Functions

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 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.
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.

Typedefs

MaDirective

Appweb configuration file directive parsing callback function.

Defines

#define	MA_PARSE_NON_SERVER 0x1
	Command file being parsed by a utility program.
#define	MA_UNLOAD_TIMEOUT "5mins"
	Default module inactivity timeout.

MaState

Current configuration parse state.

API Stability:: Evolving.

See Also:: MaDirective, maAddDirective, maPopState, maPushState, maTokenize

API Stability:: Evolving.

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.

void maAddDirective (cchar *directive, MaDirective proc)

Define a new appweb configuration file directive.

Description:: The appweb configuration file parse is extensible. New directives can be registered by this call. When encountered in the config file, the given callback proc will be invoked to parse.

Parameters:

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

API Stability:: Evolving.

See Also:: MaDirective, MaState, maPopState, maPushState, maTokenize

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:

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:: Evolving.

See Also:: MaDirective, MaState, maAddDirective, maPopState, maPushState, maTokenize

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

Get the argument in a directive.

Description:: Break into arguments. Args may be quoted. An outer quoting of the entire arg is removed.

Parameters:

s	String to examine.
tok	Next token reference.

Returns:: Reference to the next token. (Not allocate.

API Stability:: Evolving.

See Also:: MaDirective, MaState, maAddDirective, maPopState, maPushState, maTokenize

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.

Parameters:

name	User name. Must be defined in the system password file.
libname	Library path name.

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

API Stability:: Evolving.

See Also:: MaDirective, MaState, maAddDirective, maPopState, maPushState, maTokenize

int maLoadModules (void )

Load default modules.

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

API Stability:: Prototype.

See Also:: MaDirective, MaState, maAddDirective, maPopState, maPushState, maTokenize

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.

Parameters:

path	Configuration file pathname.

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

API Stability:: Evolving.

See Also:: MaDirective, MaState, maAddDirective, maPopState, maPushState, maTokenize

int maParseFile (MaState *state, cchar *path)

Parse a configuration file.

Parameters:

state	Current state level object.
path	Filename to parse.

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

API Stability:: Prototype.

See Also:: MaDirective, MaState, maAddDirective, maPopState, maPushState, maTokenize

MaState * * maPopState (MaState *state)

Pop the state.

Description:: This is used when parsing config files to handle nested include files and block level directives.

Parameters:

state

Current state.

Returns:: The next lower level state object.

API Stability:: Evolving.

See Also:: MaDirective, MaState, maAddDirective, maPushState, maTokenize

MaState * * maPushState (MaState *state)

Push the state.

Description:: This is used when parsing config files to handle nested include files and block level directives.

Parameters:

state

Current state.

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

API Stability:: Evolving.

See Also:: MaDirective, MaState, maAddDirective, maPopState, maTokenize

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 to.
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:: Evolving.

See Also:: MaDirective, MaState, maAddDirective, maPopState, maPushState, maTokenize

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:: Evolving.

See Also:: MaDirective, MaState, maAddDirective, maPopState, maPushState, maTokenize

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 expand.
fmt	Format string specifier Supported tokens: 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:: Evolving.

See Also:: MaDirective, MaState, maAddDirective, maPopState, maPushState

Functions

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

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:: Evolving.

See Also:: MaState, maAddDirective, maPopState, maPushState, maTokenize