http/capi.h File Reference

Detailed Description

C language API.

Overview:: See capi.dox for additional documentation.

Typedefs

typedef void(*) MaEgiCb (MaRequest *rq, char *script, char *uri, char *query, char *postData, int postLen)

typedef int(*) MaEspCb (MaRequest *rq, int argc, char **argv)

Functions

int maClientDoGetRequest (MaClient *cp, char *url)

int maClientDoHeadRequest (MaClient *cp, char *url)

int maClientDoOptionsRequest (MaClient *cp, char *url)

int maClientDoPostRequest (MaClient *cp, char *url, char *postData, int postLen)

int maClientDoTraceRequest (MaClient *cp, char *url)

int maClientGetFd (MaClient *cp)

char * maClientGetHeaderVar (MaClient *cp, char *key)

char * maClientGetHost (MaClient *cp)

int maClientGetPort (MaClient *cp)

int maClientGetResponseCode (MaClient *cp)

char * maClientGetResponseContent (MaClient *cp, int *contentLen)

char * maClientGetResponseHeader (MaClient *cp)

char * maClientGetResponseMessage (MaClient *cp)

void maClientLock (MaClient *cp)

void maClientResetAuth (MaClient *cp)

void maClientSetHost (MaClient *cp, char *host)

void maClientSetKeepAlive (MaClient *cp, int on)

void maClientSetPort (MaClient *cp, int num)

void maClientSetProxy (MaClient *cp, char *host, int port)

void maClientSetRetries (MaClient *cp, int count)

void maClientSetTimeout (MaClient *cp, int timeout)

void maClientUnlock (MaClient *cp)

int maConfigureServer (MaServer *server, char *configFile)

MaClient * maCreateClient ()

void maCreateEnvVars (MaRequest *rq, char *buf, int len)

MaHttp * maCreateHttp ()

MaServer * maCreateServer (MaHttp *http, char *name, char *serverRoot)

int maDefineEgiForm (char *name, MaEgiCb fn)

int maDefineEsp (char *name, MaEspCb fn)

void maDeleteHttp (MaHttp *http)

void maDeleteServer (MaServer *server)

void maDestroyClient (MaClient *cp)

int maGetConfigErrorLine (MaServer *server)

char * maGetCookie (MaRequest *rq)

void maGetCrackedCookie (MaRequest *rq, char **name, char **value, char **path)

char * maGetVar (MaRequest *rq, MaEnvType objType, char *var, char *defaultValue)

void maRedirect (MaRequest *rq, int code, char *url)

void maRequestError (MaRequest *rq, int code, char *fmt,...)

void maSetCookie (MaRequest *rq, char *name, char *value, int lifetime, char *path, bool secure)

int maSetFileName (MaRequest *rq, char *fileName)

void maSetResponseCode (MaRequest *rq, int code)

void maSetResult (MaRequest *rq, char *s)

void maSetVar (MaRequest *rq, MaEnvType objType, char *var, char *value)

int maStartServers (MaHttp *http)

void maStopServers (MaHttp *http)

int maWrite (MaRequest *rq, char *buf, int size)

int maWriteFmt (MaRequest *rq, char *fmt,...)

int maWriteStr (MaRequest *rq, char *s)

void mprAddLogFileListener ()

int mprCreateMpr (char *appName)

int mprGetAsyncSelectMode ()

int mprGetFds (fd_set *readInterest, fd_set *writeInterest, fd_set *exceptInterest, int *maxFd, int *lastGet)

int mprGetIdleTime ()

int mprIsExiting ()

int mprRunTasks ()

int mprRunTimers ()

void mprServiceEvents (int loopOnce, int maxTimeout)

void mprServiceIO (int readyFds, fd_set *readFds, fd_set *writeFds, fd_set *exceptFds)

void mprServiceWinIO (int sock, int winMask)

void mprSetAsyncSelectMode (int on)

void mprSetHwnd (HWND appHwnd)

void mprSetLogSpec (char *logSpec)

void mprSetSocketHwnd (HWND socketHwnd)

void mprSetSocketMessage (int msgId)

int mprStartMpr (int startFlags)

void mprStopMpr ()

void mprTerminate (int graceful)

void mprTrace (int level, char *fmt,...)

Typedef Documentation

typedef void(* MaEgiCb)(MaRequest *rq, char *script, char *uri, char *query, char *postData, int postLen)

Synopsis:: Callback function prototype for EGI forms.

Overview:: The Embedded Gateway Interface is an in-memory replacement for CGI. The MaEgiCb callback function will be called when the designated URL is posted to.

Library:: libcapiModule

See also:: MaEspCb

typedef int(* MaEspCb)(MaRequest *rq, int argc, char **argv)

char *query, char *postData, int postLen);

Deprecated:

Deprecated in release 2.0. Use EspCMethod instead.

Synopsis:: Callback function prototype for ESP procedures.

Overview:: Embedded Server Pages will call procedure callbacks when the corresponding scripting function is encountered in an ESP page. This interface is deprecated. Use the maEspDefineCMethod instead.

Library:: libcapiModule

Configure options:: Requires BLD_FEATURE_LEGACY_API.

See also:: EspCMethod, maEspDefineCMethod

Function Documentation

int maClientDoGetRequest	(	MaClient *	cp,
		char *	url
	)

Synopsis:: Issue a HTTP GET request

Overview:: Issue a HTTP GET request for the given url and wait for a response.

Parameters:

	cp	Client object handle
	url	Server URL to get

Returns:: Returns zero if successful or else a non-zero error code.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoHeadRequest, maClientDoOptionsRequest, maClientDoTraceRequest, maClientGetResponseCode, maClientGetResponseContent, maClientGetResponseHeader, maClientGetResponseMessage

int maClientDoHeadRequest	(	MaClient *	cp,
		char *	url
	)

Synopsis:: Issue a HTTP HEAD request

Overview:: Issue a HTTP HEAD request for the given url and wait for a response. The HEAD request returns only the HTTP headers and no content body.

Parameters:

	cp	Client object handle
	url	Server URL to request the headers for.

Returns:: Returns zero if successful or else a non-zero error code.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoGetRequest, maClientDoOptionsRequest, maClientDoTraceRequest, maClientGetResponseCode, maClientGetResponseContent, maClientGetResponseHeader, maClientGetResponseMessage

int maClientDoOptionsRequest	(	MaClient *	cp,
		char *	url
	)

Synopsis:: Issue a HTTP OPTIONS request

Overview:: Issue a HTTP OPTIONS request for the given url and wait for a response. The OPTIONS request returns what HTTP methods are supported by the server.

Parameters:

	cp	Client object handle
	url	Server URL to request the options for.

Returns:: Returns zero if successful or else a non-zero error code.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoHeadRequest, maClientDoGetRequest, maClientDoTraceRequest, maClientGetResponseCode, maClientGetResponseContent, maClientGetResponseHeader, maClientGetResponseMessage

int maClientDoPostRequest	(	MaClient *	cp,
		char *	url,
		char *	postData,
		int	postLen
	)

Synopsis:: Issue a HTTP POST request

Overview:: Issue a HTTP POST request for the given url and wait for a response. Post data may be supplied via the postData argument.

Parameters:

	cp	Client object handle.
	url	Server URL to post to.
	postData	Pointer to post data block
	postLen	Length of post data block

Returns:: Returns zero if successful or else a non-zero error code.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientDoGetRequest, maClientDoHeadRequest, maClientDoOptionsRequest, maClientDoTraceRequest, maClientGetResponseCode, maClientGetResponseContent, maClientGetResponseHeader, maClientGetResponseMessage

int maClientDoTraceRequest	(	MaClient *	cp,
		char *	url
	)

Synopsis:: Issue a HTTP TRACE request

Overview:: Issue a HTTP TRACE request for the given url and wait for a response.

Parameters:

	cp	Client object handle
	url	Server URL to request a trace of.

Returns:: Returns zero if successful or else a non-zero error code.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoHeadRequest, maClientDoOptionsRequest, maClientDoGetRequest, maClientGetResponseCode, maClientGetResponseContent, maClientGetResponseHeader, maClientGetResponseMessage

int maClientGetFd ( MaClient * cp )

Synopsis:: Get the underlying socket file handle

Overview:: Return the O/S socket file handle for a connection. This call should only be issued and the socket handle only be used when the underlying socket is open.

Parameters:

Client object handle

Returns:: Returns a socket handle.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientGetHost, maCreateClientGetPort

char* maClientGetHeaderVar	(	MaClient *	cp,
		char *	key
	)

Synopsis:: Get the value of a client HTTP response header

Overview:: HTTP requests have headers which detail information about the request itself.

Parameters:

	cp	Client object handle
	key	Lower case header value

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient

char* maClientGetHost ( MaClient * cp )

Synopsis:: Return the underlying host name for the client connection

Overview:: The default host can be set via maClientSetHost. This call returns the default host.

Parameters:

Client object handle

Returns:: Returns a pointer to the default host string. The caller should not modify or free the returned string.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientGetFd, maCreateClientGetPort

int maClientGetPort ( MaClient * cp )

Synopsis:: Get the underlying socket port number

Overview:: This call returns the TCP/IP port number of the server for this client request.

Parameters:

Client object handle

Returns:: A positive integer port number.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientGetHost, maCreateClientGetFd

int maClientGetResponseCode ( MaClient * cp )

Synopsis:: Return the response HTTP code.

Overview:: Return the HTTP response code for a completed client request. This call should only be issued after calling maClientDoGetRequest or one of the other DoXxxRequest APIs.

Parameters:

Client object handle

Returns:: Returns the HTTP response code. 200 normally means success.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoHeadRequest, maClientDoOptionsRequest, maClientDoTraceRequest, maClientDoGetRequest, maClientGetResponseContent, maClientGetResponseHeader, maClientGetResponseMessage

char* maClientGetResponseContent	(	MaClient *	cp,
		int *	contentLen
	)

Synopsis:: Get the response content

Overview:: Return the HTTP response data for a completed client request. This call should only be issued after calling maClientDoRequest or or one of the other DoXxxRequest APIs.

Parameters:

	cp	Client object handle
	contentLen	Pointer to an integer to hold the length of the content buffer.

Returns:: Returns a pointer to the response content buffer. The caller should not free or modify the content data.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoHeadRequest, maClientDoOptionsRequest, maClientDoTraceRequest, maClientGetResponseCode, maClientDoGetRequest, maClientGetResponseHeader, maClientGetResponseMessage

char* maClientGetResponseHeader ( MaClient * cp )

Synopsis:: Get the HTTP response header set

Overview:: Return the HTTP response header buffer.

Parameters:

Client object handle

Returns:: Returns a pointer to a string representing the HTTP response headers. Each header will be terminated by "\r\n" or "\n". The last header will have an additional null character appended.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoHeadRequest, maClientDoOptionsRequest, maClientDoTraceRequest, maClientGetResponseCode, maClientGetResponseContent, maClientDoGetRequest, maClientGetResponseMessage

char* maClientGetResponseMessage ( MaClient * cp )

Synopsis:: Get the response error message.

Overview:: If the client request fails, the maClientGetResponseMessage API will return a text message describing the error.

Parameters:

Client object handle

Returns:: Returns a pointer to the error message. The caller should not free or modify the error message.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientDoPostRequest, maClientDoHeadRequest, maClientDoOptionsRequest, maClientDoTraceRequest, maClientGetResponseCode, maClientGetResponseContent, maClientGetResponseHeader, maClientDoGetRequest

void maClientLock ( MaClient * cp )

Synopsis:: Lock the client request object

Overview:: Lock the client so that it will be thread-safe.

Parameters:

Client object handle

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientGetHost, maCreateClientGetPort, maClientUnlock

void maClientResetAuth ( MaClient * cp )

Synopsis:: Reset the authorization defaults defined for the client.

Overview:: This call will reset any settings defined via the maClientSetAuth API.

Parameters:

Client object handle

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientGetHost, maCreateClientSetAuth

void maClientSetHost	(	MaClient *	cp,
		char *	host
	)

Synopsis:: Set the default host.

Overview:: Set the default host to use for subsequent client requests. If a client URL does not contain a host portion, the default host is used.

Parameters:

	cp	Client object handle
	host	Default host name

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientGetHost,

void maClientSetKeepAlive	(	MaClient *	cp,
		int	on
	)

Synopsis:: Enable or disable the use of Keep-Alive by the client.

Overview:: Keep-Alive enables the client to reuse a network connection for subsequent requests. This results in a significant performance boost.

Parameters:

	cp	Client object handle
	on	Set to non-zero to enable Keep-Alive.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maClientSetTimeout, maClientSetRetries, maCreateClient, maDestroyClient

void maClientSetPort	(	MaClient *	cp,
		int	port
	)

Synopsis:: Set the default port

Overview:: Set the default port to use for subsequent client requests. If a client URL does not contain a port portion, the default port is used. It defaults to port 80.

Parameters:

	cp	Client object handle.
	port	Default port number.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientGetHost, maCreateClientGetPort

void maClientSetProxy	(	MaClient *	cp,
		char *	host,
		int	port
	)

Synopsis:: Set the HTTP proxy.

Overview:: Set the HTTP proxy to use for subsequent client requests.

Parameters:

	cp	Client object handle
	host	HTTP proxy host name.
	port	HTTP proxy TCP/IP port number.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientGetHost, maClientGetPort, maClientSetPort

void maClientSetRetries	(	MaClient *	cp,
		int	count
	)

Synopsis:: Set the number of times the client will retry a request.

Overview:: Sometimes the client must retry a request. For example, the server may close a Keep-Alive socket connection just as the client is issuing another request.

Parameters:

	cp	Client object handle
	count	Retry count.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maClientSetTimeout, maCreateClient, maDestroyClient

void maClientSetTimeout	(	MaClient *	cp,
		int	timeout
	)

Synopsis:: Set the client request timeout

Overview:: The client request will wait for the server to respond. The timeout period is the maximum time the client will be idle waiting for the server to respond with data.

Parameters:

	cp	Client object handle
	timeout	Timeout in milliseconds.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maClientSetRetries, maCreateClient, maDestroyClient

void maClientUnlock ( MaClient * cp )

Synopsis:: Unlock the client request object

Overview:: Unlock the client so that it will be thread-safe.

Parameters:

Client object handle

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient, maDestroyClient, maClientGetHost, maCreateClientGetPort, maClientUnlock

int maConfigureServer	(	MaServer *	server,
		char *	configFile
	)

Synopsis:: configure the entire server from a configuration file.

Overview:: Servers are configured via an Apache-style configuration file. A server may listen on multiple ports and may contain multiple virtual hosts.

Parameters:

	server	Pointer to the MaServer object created via maCreateServer.
	configFile	Path of the configuration file.

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

Library:: libcapiModule

Configure options:: Requires BLD_FEATURE_CONFIG_PARSE.

See also:: maDeleteHttp

MaClient* maCreateClient ( )

Synopsis:: Create a client object

Overview:: Creates a client object to use for a HTTP client request session

Returns:: A pointer to the MaClient object. Must call maDestroyClient to free.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maDestroyClient

void maCreateEnvVars	(	MaRequest *	rq,
		char *	buf,
		int	len
	)

Synopsis:: Decode a buffer and create environment variables.

Overview:: This call will URL decode the buffer and create Appweb environment variables for each keyword.

Parameters:

	rq	Request handle
	buf	Buffer to decode into environment variables. Does not need to be null terminated.
	len	Length of buffer.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maDeleteHttp

MaHttp* maCreateHttp ( )

Synopsis:: Create the application's HTTP object

Overview:: One MaHttp object is needed per application to manage all servers.

Returns:: Pointer to the MaHttp object.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maDeleteHttp

MaServer* maCreateServer	(	MaHttp *	http,
		char *	name,
		char *	serverRoot
	)

Synopsis:: Create a HTTP server.

Overview:: Creates a logical HTTP server that may consist of multiple virtual servers.

Parameters:

	http	Pointer to the MaHttp object created by maCreateHttp.
	name	Descriptive name to give to the server.
	serverRoot	Top level path of the directory containing the server.

Returns:: Pointer to the MaServer object

Stability classification:: Evolving.

Library:: libcapiModule

See also:

int maDefineEgiForm	(	char *	name,
		MaEgiCb	fn
	)

Synopsis:: Defines a C language EGI form

Overview:: This call links a C procedure to an EGI name. When a URL referencing the form is invoked, the EGI handler will ensure the nominated code is called. E.g. The URL:

        http://localhost/egi/myForm?name=Julie

Could be enabled by calling maDefineEgiForm("myForm", myFormProc);

Parameters:

	name	Name to publish the form as. This appears in the URL. Names must therefore only contain valid URL characters.
	fn	C callback function to invoke.

Returns:: Zero if successful. Otherwise it returns an MPR error code.

Stability classification:: Deprecated.

Library:: libcapiModule

See also:: maEspDefineCMethod

int maDefineEsp	(	char *	name,
		MaEspCb	fn
	)

Deprecated:

Deprecated in release 2.0. Use maEspDefineCMethod instead.

Synopsis:: Defines a C lanaguage ESP procedure

Overview:: This call links a C procedure to an ESP name. When a web page containing a call to the procedure, the ESP handler will ensure the nominated code is called.

Parameters:

	name	Name to use in the ESP web page for this ESP procedure.
	fn	C callback function to invoke.

Returns:: Zero if successful. Otherwise it returns an MPR error code.

Stability classification:: Deprecated.

Library:: libcapiModule

Configure options:: Requires BLD_FEATURE_LEGACY_API.

See also:: maEspDefineCMethod

void maDeleteHttp ( MaHttp * http )

Synopsis:: Delete the MaHttp object

Overview:: Before exiting an application, maDeleteHttp should be called to delete the MaHttp object.

Parameters:

http

MaHttp application object returned from maCreateHttp.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateHttp, maCreateServer, maDeleteServer

void maDeleteServer ( MaServer * server )

Synopsis:: Delete the MaServer object

Overview:: Before exiting an application, maDeleteServer should be called to delete the maServer object.

Parameters:

server

MaServer object returned from maCreateServer

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateHttp, maCreateServer, maDeleteHttp

void maDestroyClient ( MaClient * cp )

Synopsis:: Destroy a client object

Overview:: Destroy and release all resources associated with a client object.

Parameters:

Pointer to client object created via maCreateClient

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maCreateClient

int maGetConfigErrorLine ( MaServer * server )

Synopsis:: Return the current configuration file line number

Overview:: If a error is encountered when parsing the configuration file, maGetConfigErrorLine will return the current line number for error reporting purposes.

Parameters:

server

MaServer object returned from maCreateServer.

Returns:: The current line number (origin 1).

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maConfigureServer

char* maGetCookie ( MaRequest * rq )

Synopsis:: Return the request cookie.

Overview:: A client request may optionally include a HTTP cookie. This request returns a pointer to the cookie string.

Parameters:

Request object handle

Returns:: Pointer to the cookie for the current request.

Configure options:: Requires BLD_FEATURE_COOKIE or BLD_FEATURE_SESSION

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maGetFileName, maGetCrackedCookie, maSetCookie

void maGetCrackedCookie	(	MaRequest *	rq,
		char **	name,
		char **	value,
		char **	path
	)

Synopsis:: Parse the request cookie.

Overview:: Parse the cookie and return the cookie's name, value and path.

Parameters:

	rq	Request object handle
	name	Pointer to store allocated cookie's name. Caller must free.
	value	Pointer to store allocated cookie's value. Caller must free.
	path	Pointer to store allocated cookie's path. Caller must free.

Configure options:: Requires BLD_FEATURE_COOKIE or BLD_FEATURE_SESSION

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maGetCookie, maSetCookie

char* maGetVar	(	MaRequest *	rq,
		MaEnvType	objType,
		char *	var,
		char *	defaultValue
	)

Synopsis:: Return the value of the specified HTTP environment variable

Overview:: This call will query the value of HTTP environment variables. These variables are used by CGI, EGI and ESP handlers. ESP pages and EGI forms may access these variables.

Parameters:

	rq	Request object handle
	objType	Type of environment variable. Select from: MA_SERVER_OBJ MA_SESSION_OBJ MA_REQUEST_OBJ MA_HEADER_OBJ MA_COOKIE_OBJ MA_FILES_OBJ MA_FORM_OBJ MA_APPLICATION_OBJ MA_GLOBAL_OBJ MA_LOCAL_OBJ.
	var	Name of the variable to access.
	defaultValue	Default value to return if the variable is not defined.

Returns:: The value of the variable if it is defined. Otherwise the defaultValue is returned.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maSetVar

void maRedirect	(	MaRequest *	rq,
		int	code,
		char *	url
	)

Synopsis:: Redirect the user's browser to a new location

Overview:: maRedirect will respond to the current request with a HTTP redirection (code 301). The redirection may be to another page with the current web, or it may be to a different server.

Parameters:

	rq	Request object handle
	code	HTTP redirection code
	url	URL representing the new location. May omit the "http://server/" prefix for redirections within the exiting web.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maRequestError

void maRequestError	(	MaRequest *	rq,
		int	code,
		char *	fmt,
			...
	)

Synopsis:: Return an error to the client (user's browser)

Overview:: If a handler encounters an error, it can call maRequestError to return the appropriate HTTP error code and message to the user's browser.

Parameters:

	rq	Request handle
	code	HTTP error code. E.g. 500 for an internal server error.
	fmt	Printf style format string followed by assocated arguments.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maWrite

void maSetCookie	(	MaRequest *	rq,
		char *	name,
		char *	value,
		int	lifetime,
		char *	path,
		bool	secure
	)

Synopsis:: Set a cookie to be defined in the client's browser

Overview:: This call will define a cookie which will be sent with the response to the client. Subsequent requests from the browser should then contain the cookie. It can be used to create and track user sessions.

int maSetFileName	(	MaRequest *	rq,
		char *	fileName
	)

Synopsis:: Set the local file name for the document that satisfies this request.

Overview:: This call defines the local file name for a document which will be returned to the user's browser.

Parameters:

	rq	Request object handle.
	fileName	Path name in the local file system for the document.

Returns:: Returns zero if successful. Otherwise a negative MPR error code will be returned. On errors, maSetFileName will call requestError and will terminate the request.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maGetFileName

void maSetResponseCode	(	MaRequest *	rq,
		int	code
	)

Synopsis:: Set the HTTP request response code

Overview:: MOB

Parameters:

	rq	Request object handle
	code	Numeric HTTP response code

Library:: libcapiModule

See also:

void maSetResult	(	MaRequest *	rq,
		char *	s
	)

Deprecated:

Deprecated in release 2.0. Use maEspSetReturnValue instead.

Synopsis:: Set the result of an ESP procedure call.

Overview:: Set the result of an ESP procedure call. This value is returned from the ESP script call.

Parameters:

	rq	Request object handle.
	s	Pointer to string to use as the result.

Stability classification:: Deprecated.

Library:: libappweb

See also:: maEspSetReturnValue

void maSetVar	(	MaRequest *	rq,
		MaEnvType	objType,
		char *	var,
		char *	value
	)

Synopsis:: Set the value of a HTTP environment variable

Overview:: This call will define the value of an HTTP environment variable. These variables are used by CGI, EGI and ESP handlers. ESP pages and EGI forms may access these variables. The variable will be created if it does not exist. If it already exists, its value will be updated.

Parameters:

	rq	Request object handle.
	objType	Type of environment variable. Select from: MA_SERVER_OBJ MA_SESSION_OBJ MA_REQUEST_OBJ MA_HEADER_OBJ MA_COOKIE_OBJ MA_FILES_OBJ MA_FORM_OBJ MA_APPLICATION_OBJ MA_GLOBAL_OBJ MA_LOCAL_OBJ.
	var	Name of environment variable to set.
	value	Value to set.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maGetVar

int maStartServers ( MaHttp * http )

Synopsis:: Activate HTTP servers.

Synopsis:: Start all the logical servers corresponding to the supplied MaHttp object. Once stared, the default server an any virtual servers will be activated and begin responding to HTTP requests.

Parameters:

http

MaHttp object created via maCreateHttp.

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

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maStopServers

void maStopServers ( MaHttp * http )

Synopsis:: Deactivate HTTP servers

Overview:: Stop all the logical servers corresponding to the supplied MaHttp object. The servers will cease serving new requests immediately. Existing requests will continue to be processed by the handlers.

Parameters:

http

MaHttp object created via maCreateHttp

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maStartServers

int maWrite	(	MaRequest *	rq,
		char *	buf,
		int	size
	)

Synopsis:: Write a block of data back to the user's browser.

Overview:: This call is the most efficient way to return data back to a user's browser.

Parameters:

	rq	Request object handle
	buf	Pointer to the data buffer to write
	size	Size of the buffer in bytes

Returns:: Number of bytes written. Should equal size. On errors, returns a negative MPR error code.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maWriteFmt, maWriteStr

int maWriteFmt	(	MaRequest *	rq,
		char *	fmt,
			...
	)

Synopsis:: Write a formatted string back to the user's browser.

Overview:: Format a printf style string and write back to the browser.

Parameters:

	rq	Request object handle.
	fmt	Printf style format string followed by assocated arguments.

Returns:: Number of bytes written. On errors, returns a negative MPR error code.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maWrite, maWriteStr

int maWriteStr	(	MaRequest *	rq,
		char *	s
	)

Synopsis:: Write a string back to the user's browser.

Overview:: Write the string back to the browser.

Parameters:

	rq	Request object handle.
	s	Pointer to string to write.

Returns:: Number of bytes written. On errors, returns a negative MPR error code.

Stability classification:: Evolving.

Library:: libcapiModule

See also:: maWrite, maWriteFmt

void mprAddLogFileListener ( &