Aliases.

API Stability:

Evolving.

See Also:

Fields:

char *		filename	Alias to a physical path name.
char *		prefix	Original URI prefix.
int		prefixLen	Prefix length.
char *		uri	Redirect to a uri.

Authorization The MaAuth struct is the foundation authorization object and is used as base class by MaDirectory and MaLocation.

API Stability:

Evolving.

See Also:

Fields:

Current config parse state.

API Stability:

Evolving.

See Also:

Http Connections.

Description:

The MaConn object represents a TCP/IP connection to the client. A connection object is created for each socket connection initiated by the client. One MaConn object may service many Http requests due to HTTP/1.1 keep-alive.

API Stability:

Evolving.

See Also:

MaQueue, MaRequest, MaResponse, MaStage

Fields:

MaHostAddress *		address	Host address structure for this connection.
MprHeap *		arena	Connection memory arena.
int		canProceed	State machine should continue to process the request.
int		connectionFailed	Request failed and connection protocol is compromised.
int		disconnected	Connection is disconnected. Abandon current request.
MprTime		expire	When the connection should expire.
int		flags	Connection flags.
MaPacket *		freePackets	Free list of packets.
MaHost *		host	Owning host for this request.
MaHttp *		http	Http handle.
MaPacket *		input	Header packet.
int		keepAliveCount	Count of remaining keep alive requests for this connection.
MprMutex *		mutex	Optional multi-thread sync.
MaHost *		originalHost	Owning host for this connection. May be changed by Host header.
int		protocol	HTTP protocol version 0 == HTTP/1.0, 1 == HTTP/1.1.
char *		remoteIpAddr	Remote client IP address (REMOTE_ADDR).
int		remotePort	Remote client IP port number.
struct MaRequest *		request	Request object.
int		requestFailed	Request failed. Abbreviate request processing.
struct MaResponse *		response	Response object.
int		seqno	Unique connection sequence number.
struct MaQueue		serviceq	List of queues that require service for request pipeline.
MprSocket *		sock	Underlying socket handle.
MprTime		started	When the connection started.
int		state	Connection state.
MprTime		time	Cached current time.
int		timeout	Timeout period in msec.
int		trace	Current request should be traced.

Directory Control.

API Stability:

Evolving.

See Also:

Filter Stages.

API Stability:

Evolving.

See Also:

Fields:

Group Authorization.

API Stability:

Evolving.

See Also:

Fields:

Host Object A Host object represents a single listening HTTP connection endpoint.

API Stability:

Evolving.

See Also:

Host Address Mapping.

API Stability:

Evolving.

See Also:

Fields:

int		flags	Mapping flags.
char *		ipAddr	IP Address for this endpoint.
int		port	Port for this endpoint.
MprList *		vhosts	Vhosts using this address.

Http Service.

Description:

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

API Stability:

Evolving.

See Also:

maCreateHttp, maStartHttp, maStopHttp

Fields:

struct MaStage *		authFilter	Authorization filter (digest and basic).
struct MaStage *		chunkFilter	Chunked transfer encoding filter.
struct MaServer *		defaultServer	Default web server object.
struct MaStage *		dirHandler	Directory listing handler.
struct MaStage *		egiHandler	Embedded Gateway Interface (EGI) handler.
struct MaStage *		ejsHandler	Ejscript Web Framework handler.
struct MaStage *		fileHandler	Static file handler.
int		gid	Group Id.
char *		groupname	Http server group name.
MaLimits		limits	Security and resource limits.
MprMutex *		mutex	Multi-thread sync.
struct MaStage *		netConnector	Network connector.
struct MaStage *		passHandler	Pass through handler.
struct MaStage *		rangeFilter	Ranged requests filter.
struct MaStage *		sendConnector	Send file connector.
MprList *		servers	List of web servers objects.
MprHashTable *		stages	Hash table of stages.
int		uid	User Id.
char *		username	Http server user name.

Create the MaHttp object.

Description:

The Appweb library uses a singleton MaHttp object to manage multiple embedded web servers.

Parameters:

ctx	Any memory context object returned by mprAlloc.

Returns:

A MaHttp object. Use mprFree to close and release.

See Also:

MaHttp, maStartHttp, maStopHttp

Set the Http Group.

Description:

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

Parameters:

http	MaHttp object created via maCreateHttp.
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:

MaHttp, maCreateHttp, maStartHttp, maStopHttp

Set the Http User.

Description:

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

Parameters:

http	MaHttp object created via maCreateHttp.
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:

MaHttp, maCreateHttp, maStartHttp, maStopHttp

Start Http services.

Description:

This starts listening for requests on all configured servers.

Parameters:

http	MaHttp object created via maCreateHttp.

Returns:

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

See Also:

MaHttp, maCreateHttp, maStopHttp

Stop Http services.

Description:

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

Parameters:

http	MaHttp object created via maCreateHttp.

Returns:

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

See Also:

MaHttp, maCreateHttp, maStartHttp

Server limits.

API Stability:

Evolving.

See Also:

Fields:

int		maxBody	Max size of an incoming request.
int		maxChunkSize	Max chunk size for transfer encoding.
int		maxHeader	Max size of the total header.
int		maxNumHeaders	Max number of lines of header.
int		maxResponseBody	Max size of generated response content.
int		maxStageBuffer	Max buffering by any pipeline stage.
int		maxThreads	Max number of pool threads.
int		maxUploadSize	Max size of an uploaded file.
int		maxUrl	Max size of a URL.
int		minThreads	Min number of pool threads.
int		threadStackSize	Stack size for each pool thread.

Listen endpoint.

API Stability:

Evolving.

See Also:

Fields:

int		flags	Listen flags.
char *		ipAddr	IP address on which to listen.
int		port	Port number to listen on.
struct MaServer *		server	Server owning this listening endpoint.
MprSocket *		sock	Underlying socket.
struct MprSsl *		ssl	SSL configuration.

Location Control.

API Stability:

Evolving.

See Also:

Fields:

MaAuth *		auth	Per location block authentication.
int		autoDelete	Auto delete uploaded files.
struct MaStage *		connector	Network connector.
char *		ejsPath	EjsPath search path.
MprHashTable *		extensions	Hash of handlers by extensions.
int		flags	Location flags.
struct MaStage *		handler	Set handler.
void *		handlerData	Data reserved for the handler.
MprList *		handlers	List of handlers for this location.
MprList *		inputStages	Input stages.
MprList *		outputStages	Output stages.
struct MaLocation *		parent	Parent location.
char *		prefix	Location prefix name.
int		prefixLen	Length of the prefix name.
int		sessionTimeout	Session timeout for this location.
struct MprSsl *		ssl	SSL configuration.
char *		uploadDir	Upload directory.

Mime Type hash table entry (the URL extension is the key).

API Stability:

Evolving.

See Also:

Fields:

Content range structure.

Range: 0, 49 First 50 bytes Range: -1, -50 Last 50 bytes Range: 1, -1 Skip first byte then select content to the end.

API Stability:

Evolving.

See Also:

Http Requests.

Description:

Most of the APIs in the Request group still take a MaConn object as their first parameter. This is to make the API easier to remember - APIs take a connection object rather than a request or response object.

API Stability:

Evolving.

See Also:

MaConn, MaResponse, maCompareFormVar, maGetCookies, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar, maTestFormVar

Fields:

char *		accept	Accept header.
char *		acceptCharset	Accept-Charset header.
char *		acceptEncoding	Accept-Encoding header.
MaAlias *		alias	Matching alias.
MprHeap *		arena	Request memory arena.
MaAuth *		auth	Set to either dir or location auth information.
char *		authType	Authorization type (basic|digest) (ENV: AUTH_TYPE).
int		chunkRemainingData	Remaining chunk data to read.
int		chunkSize	Size of the next chunk.
int		chunkState	Chunk encoding state.
struct MaConn *		conn	Connection object.
char *		connection	Connection header.
char *		contentLengthStr	Content length string value.
char *		cookie	Request cookie header.
MaDir *		dir	Best matching dir (PTR only).
MprList *		etags	Document etag to uniquely identify the document version.
MprHashTable *		files	Uploaded files. Managed by the upload filter.
int		flags	Request modifiers.
MprHashTable *		formVars	Query and post data variables.
char *		forwarded	Forwarded header.
char *		group	Supplied via basic / digest auth.
MaPacket *		headerpacket	Packet containing all headers ( == conn->input).
MaPacket *		headerPacket	HTTP headers.
MprHashTable *		headers	Header variables.
MaHost *		host	Owning host for this request.
char *		hostName	Client supplied host name.
char *		httpProtocol	HTTP/1.0 or HTTP/1.1.
bool		ifMatch	If-Match processing requested.
bool		ifModified	If-Modified processing requested.
MprList *		inputPipeline	Input processing.
MaRange *		inputRange	Specified range for input (post) data.
int		length	Declared content length (ENV: CONTENT_LENGTH).
MaLocation *		location	Location block.
int		method	Request method.
char *		methodName	Protocol method GET|PUT. (ENV: REQUEST_METHOD).
char *		mimeType	Mime type of the request payload (ENV: CONTENT_TYPE).
MaPacket *		packet	Current input packet.
MprUri *		parsedUri	Parsed query string. parsedUri->query is the query string.
char *		pathInfo	Extra path information (ENV: PATH_INFO).
char *		pathTranslated	Mapped extraPath to storage (ENV: PATH_TRANSLATED).
char *		pragma	Pragma header.
MaRange *		ranges	Requested ranges for response data.
int		receivedContent	Length of content actually received.
char *		referer	Refering URL.
int		remainingContent	Remaining content data to read.
MprTime		since	If-Modified date.
char *		url	Decoded URL. Doesn't include scheme, host, extra path, query or fragments.
char *		user	Remote user (ENV: REMOTE_USER).
char *		userAgent	User-Agent header.

Add query and post form variables.

Description:

Add new variables encoded in the supplied buffer.

Parameters:

conn	MaConn connection object.
buf	Buffer containing www-urlencoded data.
len	Length of buf.

See Also:

MaConn, MaRequest, MaResponse, maCompareFormVar, maGetCookies, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar, maTestFormVar

Compare a form variable.

Description:

Compare a form variable and return true if it exists and its value matches.

Parameters:

conn	MaConn connection object.
var	Name of the form variable.
value	Value to compare.

Returns:

True if the value matches.

See Also:

MaConn, MaRequest, MaResponse, maGetCookies, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar, maTestFormVar

Get the cookies.

Description:

Get the cookies defined in the current requeset.

Parameters:

conn	MaConn connection object.

Returns:

Return a string containing the cookies sent in the Http header of the last request.

See Also:

MaConn, MaRequest, MaResponse, maCompareFormVar, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar, maTestFormVar

Get a form variable.

Description:

Get the value of a named form variable. Form variables are define via www-urlencoded query or post data contained in the request.

Parameters:

conn	MaConn connection object.
var	Name of the form variable to retrieve.
defaultValue	Default value to return if the variable is not defined. Can be null.

Returns:

String containing the form variable's value. Caller should not free.

See Also:

MaConn, MaRequest, MaResponse, maCompareFormVar, maGetCookies, maGetIntFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar, maTestFormVar

Get a form variable as an integer.

Description:

Get the value of a named form variable as an integer. Form variables are define via www-urlencoded query or post data contained in the request.

Parameters:

conn	MaConn connection object.
var	Name of the form variable to retrieve.
defaultValue	Default value to return if the variable is not defined. Can be null.

Returns:

Integer containing the form variable's value.

See Also:

MaConn, MaRequest, MaResponse, maCompareFormVar, maGetCookies, maGetFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar, maTestFormVar

Get the request query string.

Description:

Get query string sent with the current request.

Parameters:

conn	MaConn connection object.

Returns:

String containing the request query string. Caller should not free.

See Also:

MaConn, MaRequest, MaResponse, maCompareFormVar, maGetCookies, maGetFormVar, maGetIntFormVar, maSetFormVar, maSetIntFormVar, maTestFormVar

Set a form variable value.

Description:

Set the value of a named form variable to a string value. Form variables are define via www-urlencoded query or post data contained in the request.

Parameters:

conn	MaConn connection object.
var	Name of the form variable to retrieve.
value	Default value to return if the variable is not defined. Can be null.

See Also:

MaConn, MaRequest, MaResponse, maCompareFormVar, maGetCookies, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetIntFormVar, maTestFormVar

Set a form variable value.

Description:

Set the value of a named form variable to an integer value. Form variables are define via www-urlencoded query or post data contained in the request.

Parameters:

conn	MaConn connection object.
var	Name of the form variable to retrieve.
value	Default value to return if the variable is not defined. Can be null.

See Also:

MaConn, MaRequest, MaResponse, maCompareFormVar, maGetCookies, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetFormVar, maTestFormVar

Test if a form variable is defined.

Parameters:

conn	MaConn connection object.
var	Name of the form variable to retrieve.

Returns:

True if the form variable is defined.

See Also:

MaConn, MaRequest, MaResponse, maCompareFormVar, maGetCookies, maGetFormVar, maGetIntFormVar, maGetQueryString, maSetFormVar, maSetIntFormVar

Http Response.

Description:

Most of the APIs in the Response group still take a MaConn object as their first parameter. This is to make the API easier to remember - APIs take a connection object rather than a request or response object.

API Stability:

Evolving.

See Also:

MaConn, MaRequest, maFailRequest, maFormatBody, maSetCookie

Fields:

char *		altBody	Alternate response for errors.
int		bytesWritten	Bytes written including headers.
int		chunkSize	Chunk size to use when using transfer encoding.
int		code	HTTP response code.
struct MaConn *		conn	Current connection object.
MaStage *		connector	Response connector.
MaRange *		currentRange	Current range being fullfilled.
int		entityLength	Original content length before range subsetting.
char *		etag	Unique identifier tag.
cchar *		extension	Filename extension.
MprFile *		file	File to be served.
MprPath		fileInfo	File information if there is a real file to serve.
char *		filename	Name of a real file being served.
int		flags	Response flags.
MaPacket *		freePackets	List of free packets.
MaStage *		handler	Response handler.
void *		handlerData	Data reserved for the handler.
char *		header	HTTP response header.
MprHashTable *		headers	Custom response headers.
int		headerSize	Size of the header written.
int		length	Response content length.
cchar *		mimeType	Mime type of the response document.
MprList *		outputPipeline	Output processing.
int		pos	Current I/O position.
MaQueue		queue[2]	Dummy head for the response queues.
char *		rangeBoundary	Inter-range boundary.

Dont cache the response.

Description:

Instruct the client not to cache the response body. This is done by setting the Cache-control Http header.

Parameters:

conn	MaConn connection object.

See Also:

MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie

Fail a request.

Description:

Fail a request with the specified http status code. The formatted message is logged to the appweb error log.

Parameters:

conn	MaConn connection object.
code	Http status code.
fmt	Printf style formatted string.
...	Arguments for fmt.

See Also:

MaConn, MaRequest, MaResponse, maFormatBody, maSetCookie

Create the response headers.

Description:

Fill the given empty packet with the Http response headers. This should only be called by connectors just prior to sending output to the client. It should be delayed as long as possible if the content length is not yet known to give the pipeline a chance to determine the response length. This way, a non-chunked response can be sent with a content-length header. This is the fastest HTTP response.

Parameters:

conn	MaConn connection object.
packet	Packet into which to place the headers.

See Also:

MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie

Format an alternate response body.

Description:

Format a response body to use instead of data generated by the request processing pipeline. This is typically used to send error responses and redirections.

Parameters:

conn	MaConn connection object.
title	Title string to format into the HTML response body.
fmt	Printf style formatted string. This string may contain HTML tags and is not HTML encoded before sending to the user. NOTE: Do not send user input back to the client using this method. Otherwise you open large security holes.
...	Arguments for fmt.

Returns:

A count of the number of bytes in the response body.

See Also:

MaConn, MaRequest, MaResponse, maFailRequest, maSetCookie

Redirect the client.

Description:

Redirect the client to a new uri.

Parameters:

conn	MaConn connection object.
code	Http status code to send with the response.
uri	New uri for the client.

See Also:

MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie

Set a response cookie.

Description:

Define a cookie to send in the response Http header.

Parameters:

conn	MaConn connection object.
name	Cookie name.
value	Cookie value.
path	URI path to which the cookie applies.
domain	Domain in which the cookie applies. Must have 2-3 dots.
lifetime	Duration for the cookie to persist in seconds.
secure	Set to true if the cookie only applies for SSL based connections.

See Also:

MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody

Set a response header.

Description:

Set the response header. If allowMultiple is true, then duplicate keys can be defined. Otherwise, prior key headers are overwritten.

Parameters:

conn	MaConn connection object.
allowMultiple	If true, allow duplicate keys of the same value.
key	Http response header key.
fmt	Printf style formatted string to use as the header key value.
...	Arguments for fmt.

See Also:

MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie

Set a Http response code.

Description:

Set the Http response code for the request. This defaults to 200 (OK).

Parameters:

conn	MaConn connection object.
code	Http status code.

See Also:

MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie

Set the response mime type.

Description:

Set the response mime type Http header.

Parameters:

conn	MaConn connection object.
mimeType	Mime type string.

See Also:

MaConn, MaRequest, MaResponse, maFailRequest, maFormatBody, maSetCookie

Http Server Control An application may have any number of HTTP servers, each managed by an instance of the Server class.

API Stability:

Evolving.

See Also:

maConfigureServer, maCreateServer, maCreateWebServer, maLoadStaticModules, maRunSimpleWebServer, maRunWebServer, maServiceWebServer

Fields:

bool		alreadyLogging	Already logging.
struct MaHost *		defaultHost	Primary host.
MprList *		hostAddresses	List of HostAddress objects.
MprList *		hosts	List of host objects.
MprList *		listens	List of listening sockets.
int		maxConcurrentRequests	Maximum number of clients.
char *		name	Unique name for this server.
char *		serverRoot	Server root.

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:

ctx	Any memory context object returned by mprAlloc.
http	MaHttp object created via maCreateHttp.
server	MaServer object created via maCreateServer.
configFile	File name of the Appweb configuration file (appweb.conf) that defines the web server configuration.
ipAddr	If using a config file, set to null. Otherwise, set to a host name or IP address.
port	If using a config file, set to -1. Otherwise, set to the port number to listen on.
documentRoot	If not using a config file, set this to the directory containing the web documents to serve.

Returns:

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

See Also:

MaServer, maCreateServer, maCreateWebServer, maLoadStaticModules, maRunSimpleWebServer, maRunWebServer, maServiceWebServer

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:

http	Http object returned from maCreateHttp.
name	Name of the web server. This name is used as the initial server name.
root	Server root directory.
ipAddr	If not-null, create and open a listening endpoint on this IP address. If you are configuring via a config file, use maConfigureServer and set ipAddr to null.
port	Port number to listen on. Set to -1 if you do not want to open a listening endpoint on ipAddr:port.

Returns:

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

See Also:

MaServer, maConfigureServer, maCreateWebServer, maLoadStaticModules, maRunSimpleWebServer, maRunWebServer, maServiceWebServer

Create a web server.

Description:

Create a web server configuration based on the supplied config file. Once created, the web server should be run by calling maServiceWebServer. Use this routine when you need access to the MaHttp object. If you want a one-line embedding of Appweb, use maRunWebServer or maRunSimpleWebServer.

Parameters:

configFile

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

Returns:

MaHttp object.

See Also:

MaServer, maConfigureServer, maCreateServer, maLoadStaticModules, maRunSimpleWebServer, maRunWebServer, maServiceWebServer

Load static modules.

Description:

Load the statically configured modules, handlers, filters and connectors. The configure program can specify a static or shared build of Appweb. The maCreateServer routine will call maLoadStaticModules automatically. It should not be called by in user programs.

Parameters:

http	MaHttp object created via maCreateHttp.

See Also:

MaServer, maConfigureServer, maCreateServer, maCreateWebServer, maRunSimpleWebServer, maRunWebServer, maServiceWebServer

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 addresss and port. This routine provides is a one-line embedding of Appweb. If you want to use a config file, try the maRunWebServer instead. If you need more control, try maCreateWebServer which exposes the MaHttp object.

Parameters:

ipAddress	IP address on which to listen. Set to "0.0.0.0" to listen on all interfaces.
port	Port number to listen to.
docRoot	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, maConfigureServer, maCreateServer, maCreateWebServer, maLoadStaticModules, maRunWebServer, maServiceWebServer

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 is a one-line embedding of Appweb. If you don't want to use a config file, try the maRunSimpleWebServer instead. If you need more control, try maCreateWebServer which exposes the MaHttp object.

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, maConfigureServer, maCreateServer, maCreateWebServer, maLoadStaticModules, maRunSimpleWebServer, maServiceWebServer

Service a web server.

Description:

Run a web server configuration. This is will start http services via maStartHttp and will service incoming Http requests until instructed to exit. This is often used in conjunction with maCreateWebServer.

Parameters:

http	Http object created via maCreateWebServer or maCreateHttp.

Returns:

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

See Also:

MaServer, maConfigureServer, maCreateServer, maCreateWebServer, maLoadStaticModules, maRunSimpleWebServer, maRunWebServer

Upload File Each uploaded file has an MaUploadedFile entry.

API Stability:

Evolving.

See Also:

Fields:

User Authorization File based authorization backend.

API Stability:

Evolving.

See Also:

Fields: