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:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Stop access logging.

Parameters:

route

HttpRoute object.

See Also:

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

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

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

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.

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

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

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

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

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.

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.

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.

Stop a server.

Parameters:

server

Object created via maCreateServer

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