Appweb

Appweb Service.

Description:: There is one instance of MaAppweb per application. It manages a list of HTTP servers running in the application.

API Stability:: Evolving.

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

Fields:

void maAddDirective (MaAppweb *appweb, cchar *directive, MaDirective proc)

Define a new config 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:

appweb	Appweb object created via maCreateAppweb
directive	Directive name.
proc	Directive callback procedure of the type MaDirective

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

void maAddEndpoint (MaServer *server, HttpEndpoint *endpoint)

Add a listening endpoint.

Parameters:

server	Server object to modify.
endpoint	Listening endpoint to add to the server.

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

void maAddServer (MaAppweb *appweb, struct MaServer *server)

Add a server.

Description:: Add a server to the list of appweb managed web servers.

Parameters:

appweb	Appweb object created via maCreateAppweb
server	MaServer object.

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

See Also:: Http, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maApplyChangedGroup (MaAppweb *appweb)

Apply the changed group.

Description:: Apply configuration changes and actually change the Appweb group id.

Parameters:

appweb

Appweb object created via maCreateAppweb

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

See Also:: Http, maAddServer, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maApplyChangedUser (MaAppweb *appweb)

Apply the changed user.

Description:: Apply configuration changes and actually change the Appweb user id.

Parameters:

appweb

Appweb object created via maCreateAppweb

See Also:: Http, maAddServer, maApplyChangedGroup, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

MaAppweb * maCreateAppweb ()

Create the Appweb object.

Description:: Appweb uses a singleton Appweb object to manage multiple web servers instances.

Returns:: A Http object. Use mprFree to close and release.

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

void maGetUserGroup (MaAppweb *appweb)

Get the user group.

Description:: Get the user name and ID for appweb.

Parameters:

appweb

Appweb object created via maCreateAppweb

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maLoadModule (MaAppweb *appweb, 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:

appweb	Appweb object created via maCreateAppweb
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.

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

struct MaServer * MaServer* maLookupServer (MaAppweb *appweb, cchar *name)

Lookup a server.

Description:: Lookup a server by name and return the MaServer object.

Parameters:

appweb	Appweb object created via maCreateAppweb
name	Server name.

Returns:: MaServer object.

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maMatchDir (HttpConn *conn, HttpRoute *route, int direction)

Match routine for the dirHandler.

Parameters:

conn	Connection object.
route	Matching route object.
direction	Set to HTTP_STAGE_TX or HTTP_STAGE_RX.

Returns:: HTTP_ROUTE_OK if the request matches.

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maParseConfig (MaServer *server, cchar *path, int flags)

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:

server	MaServer object created via maCreateServer
path	Configuration file pathname.
flags	Parse control flags. Reserved. Set to zero.

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

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maParseInit (MaAppweb *appweb)

Initialize the config file parser.

Parameters:

appweb

Appweb object created via maCreateAppweb

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

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

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.

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

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.

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

void maSetAccessLog (HttpRoute *route, cchar *path, cchar *format)

Define the access log.

Description:: The access log is used to log details about requests to the web server. Errors are logged in the error log.

Parameters:

route	HttpRoute object for which to define the logging characteristics.
path	Pathname for the log file.
format	Log file format. The format string argument defines how Appweb will record HTTP accesses to the access log. The following log format specifiers are supported: %% - Percent sign a - Remote IP address b - Response bytes written to the client include headers. If zero, "-" is written. B - Response bytes written excluding headers h - Remote hostname O - Bytes written include headers. If zero bytes, "0" is written. r - First line of the request s - HTTP response status code t - Time the request was completed u - Authenticated username %{header}i -

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

void maSetDefaultServer (MaAppweb *appweb, struct MaServer *server)

Set the default server.

Parameters:

appweb	Appweb object created via maCreateAppweb
server	MaServer object.

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maSetHttpGroup (MaAppweb *appweb, cchar *group)

Set the Http Group.

Description:: Define the group name under which to run the Appweb service.

Parameters:

appweb	Appweb object created via maCreateAppweb
group	Group name. Must be defined in the system group file.

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

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpUser, maStartAppweb, maStopAppweb

int maSetHttpUser (MaAppweb *appweb, cchar *user)

Set the Http User.

Description:: Define the user name under which to run the Appweb service.

Parameters:

appweb	Appweb object created via maCreateAppweb
user	User name. Must be defined in the system password file.

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

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maStartAppweb, maStopAppweb

void maSetServerAddress (MaServer *server, cchar *ip, int port)

Set the server listen address.

Description:: Set the internet addresses for all endpoints managed by the server.

Parameters:

server	MaServer object created via maCreateServer
ip	IP address to set for the server.
port	Port number to use for the server.

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

void maSetServerHome (MaServer *server, cchar *path)

Set the server home directory.

Parameters:

server	MaServer object created via maCreateServer
path	Path to the directory for the server configuration.

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maStartAccessLogging (HttpRoute *route)

Start access logging.

Description:: Start access logging for a host.

Parameters:

route

HttpRoute object.

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

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maStartAppweb (MaAppweb *appweb)

Start Appweb services.

Description:: This starts listening for requests on all configured servers.

Parameters:

appweb

Appweb object created via maCreateAppweb

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

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStopAppweb

void maStopAccessLogging (HttpRoute *route)

Stop access logging.

Parameters:

route

HttpRoute object.

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

int maStopAppweb (MaAppweb *appweb)

Stop Appweb services.

Description:: This stops listening for requests on all configured servers. Shutdown is somewhat graceful.

Parameters:

appweb

Appweb object created via maCreateAppweb

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

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb

bool maValidateServer (MaServer *server)

Validate the configuration of a server.

Parameters:

server

Server object to validate.

Returns:: True if the configuration is valid.

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

MaServer

The MaServer object.

Description:: An application may have any number of HTTP servers, each managed by a MaServer instance.

API Stability:: Evolving.

See Also:: maAddEndpoint, maConfigureServer, maCreateServer, maParseConfig, maRunSimpleWebServer, maRunWebServer, maSetServerAddress, maSetServerHome, maValidateServer

Fields:

MaAppweb *	appweb	Appweb control object.
MprList *	endpoints	List of HttpEndpoints.
char *	home	Server root.
Http *	http	Http service object (copy of appweb->http).
HttpLimits *	limits	Limits for this server.
char *	name	Unique name for this server.

int maConfigureServer (MaServer *server, 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:

server	MaServer object created via maCreateServer
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.

See Also:: MaServer, maAddEndpoint, maCreateServer, maParseConfig, maRunSimpleWebServer, maRunWebServer, maSetServerAddress, maSetServerHome, maValidateServer

MaServer * maCreateServer (MaAppweb *appweb, cchar *name)

Create a MaServer object.

Description:: Create new MaServer object. This routine creates a bare MaServer object, loads any required static modules and performs minimal configuration. To use the server object created, more configuration will be required before starting Http services. If you want a one-line embedding of Appweb, use maRunWebServer or maRunSimpleWebServer

Parameters:

appweb	Http object returned from maCreateAppweb
name	Name of the web server. This name is used as the initial server name.

Returns:: MaServer A newly created MaServer object. Use mprFree to free and release.

See Also:: MaServer, maAddEndpoint, maConfigureServer, maParseConfig, maRunSimpleWebServer, maRunWebServer, maSetServerAddress, maSetServerHome, maValidateServer

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.

See Also:: MaServer, maAddEndpoint, maConfigureServer, maCreateServer, maParseConfig, maRunWebServer, maSetServerAddress, maSetServerHome, maValidateServer

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.

See Also:: MaServer, maAddEndpoint, maConfigureServer, maCreateServer, maParseConfig, maRunSimpleWebServer, maSetServerAddress, maSetServerHome, maValidateServer

MaState

Current configuration parse state.

API Stability:: Evolving.

See Also:: MaDirective, maAddDirective, maPopState, maPushState, maSetAccessLog, maStartAccessLogging, maStopAccessLogging

Fields:

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

Functions

int maArchiveLog (cchar *path, int count, int maxSize)

Archive a log file.

Description:: The current log file is archived by appending ".1" to the log path name. If a "path.1" exists, it will be renamed first to "path.2" and so on up to "path.count".

Parameters:

path	Current log file name.
count	Number of archived log files to preserve.
maxSize	Reserved.

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

int maStartServer (MaServer *server)

Start a server.

Parameters:

server

Object created via maCreateServer

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

void maStopServer (MaServer *server)

Stop a server.

Parameters:

server

Object created via maCreateServer

Typedefs

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

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

See Also:: Http, maAddServer, maApplyChangedGroup, maApplyChangedUser, maCreateAppweb, maGetUserGroup, maLoadModule, maLookupServer, maMatchDir, maParseInit, maSetDefaultServer, maSetHttpGroup, maSetHttpUser, maStartAppweb, maStopAppweb

#define	HTTP_NAME MA_SERVER_NAME
	Default web server software identification.
#define	MA_MAX_ACCESS_LOG 20971520
	Access file size (20 MB).
#define	MA_MAX_CONFIG_DEPTH 16
	Max nest of directives in config file.
#define	MA_MAX_REWRITE 10
	Maximum recursive URI rewrites.
#define	MA_PARSE_NON_SERVER 0x1
	Command file being parsed by a utility program.
#define	MA_SDB_MEMORY (20 * 1024 * 1024)
	SDB heap memory.
#define	MA_SDB_TIMEOUT (20 * 1000)
	SDB busy timeout.
#define	MA_UNLOAD_TIMEOUT "5mins"
	Default module inactivity unload timeout.

APPWEB - Appweb API Native API

Components

Functions

Typedefs

Defines

Appweb

MaServer

MaState

Functions

Typedefs

void	maAddDirective(MaAppweb appweb, cchar directive, MaDirective proc)
	Define a new config directive.
void	maAddEndpoint(MaServer server, HttpEndpoint endpoint)
	Add a listening endpoint.
void	maAddServer(MaAppweb appweb, struct MaServer server)
	Add a server.
int	maApplyChangedGroup(MaAppweb *appweb)
	Apply the changed group.
int	maApplyChangedUser(MaAppweb *appweb)
	Apply the changed user.
int	maArchiveLog(cchar *path, int count, int maxSize)
	Archive a log file.
int	maConfigureServer(MaServer server, cchar configFile, cchar home, cchar documents, cchar *ip, int port)
	Configure a web server.
MaAppweb*	maCreateAppweb()
	Create the Appweb object.
MaServer*	maCreateServer(MaAppweb appweb, cchar name)
	Create a MaServer object.
void	maGetUserGroup(MaAppweb *appweb)
	Get the user group.
int	maLoadModule(MaAppweb appweb, cchar name, cchar *libname)
	Load an appweb module.
struct MaServer*	maLookupServer(MaAppweb appweb, cchar name)
	Lookup a server.
int	maMatchDir(HttpConn conn, HttpRoute route, int direction)
	Match routine for the dirHandler.
int	maParseConfig(MaServer server, cchar path, int flags)
	Parse an Appweb configuration file.
int	maParseInit(MaAppweb *appweb)
	Initialize the config file parser.
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.
void	maSetAccessLog(HttpRoute route, cchar path, cchar *format)
	Define the access log.
void	maSetDefaultServer(MaAppweb appweb, struct MaServer server)
	Set the default server.
int	maSetHttpGroup(MaAppweb appweb, cchar group)
	Set the Http Group.
int	maSetHttpUser(MaAppweb appweb, cchar user)
	Set the Http User.
void	maSetServerAddress(MaServer server, cchar ip, int port)
	Set the server listen address.
void	maSetServerHome(MaServer server, cchar path)
	Set the server home directory.
int	maStartAccessLogging(HttpRoute *route)
	Start access logging.
int	maStartAppweb(MaAppweb *appweb)
	Start Appweb services.
int	maStartServer(MaServer *server)
	Start a server.
void	maStopAccessLogging(HttpRoute *route)
	Stop access logging.
int	maStopAppweb(MaAppweb *appweb)
	Stop Appweb services.
void	maStopServer(MaServer *server)
	Stop a server.
bool	maValidateServer(MaServer *server)
	Validate the configuration of a server.