MaRequest Struct Reference

Inheritance diagram for MaRequest:

List of all members.

Detailed Description

Manage a HTTP request from a client.

The Request class manages a HTTP client request to the server. If TCP/IP Keep-Alive is used, the Request object may be reused for subsequent requests from the client on the same TCP/IP socket connection.

Stability classification:: Evolving


Public Member Functions
void	createSession (int timeout)
void	destroySession ()
char *	getCookie ()
int	getCrackedCookie (char name, char value, char **path)
MaSession *	getSession ()
char *	getSessionId ()
char *	getVar (MaEnvType objType, char var, char defaultValue)
void	insertAfter (MprLink *item)
	Insert after this member.
void	insertPrior (MprLink *item)
	Insert prior to this member.
int	readPostData (char *buf, int bufsize)
void	redirect (int code, char *targetUrl)
void	requestError (int code, char *fmt,...)
void	setCookie (char name, char value, int lifetime, char *path, bool secure)
int	setFileName (char *newPath)
void	setHeader (char *value, bool allowMultiple=0)
void	setHeaderFlags (int headerFlags)
void	setPullPost ()
void	setVar (MaEnvType objType, char var, char value)
int	write (char *s)
int	write (char *buf, int size)
int	writeFmt (char *fmt,...)

Member Function Documentation

void MaRequest::createSession

(

int

timeout

)

Synopsis:: Create a new session data store

Overview:: Create a new session data store and associate it with this request.

Parameters:

timeout

Time in seconds for the session data store to live.

Configure options:: Requires BLD_FEATURE_SESSION

void MaRequest::destroySession

(

)

Synopsis:: Destroy the session data store

Overview:: Destroy the session data store associated with this request. This call will have no effect if a store has not been created.

Configure options:: Requires BLD_FEATURE_SESSION

char * MaRequest::getCookie

(

)

Synopsis:: Get any cookie sent with this request.

Overview:: This call returns the cookie string sent by the client with the request.

Returns:: NULL if no cookie is defined. Otherwise it returns a pointer to the cookie string. The caller must NOT free this string.

Stability classification:: Evolving.

Library:: libappWeb

Configure options:: Requires BLD_FEATURE_COOKIE or BLD_FEATURE_SESSION

See also:: getCrackedCookie, setCookie

int MaRequest::getCrackedCookie	(	char **	name,
		char **	value,
		char **	path
	)

Synopsis:: Decode a cookie string and return the cookie components.

Overview:: This call tokenizes the cookie string sent by the client with the request and it returns the cookie name, value and path.

Parameters:

name	Name of the cookie.
value	Value associated with this name.
path	URL prefix path for which this cookie applies.

Stability classification:: Evolving.

Library:: libappWeb

Configure options:: Requires BLD_FEATURE_COOKIE or BLD_FEATURE_SESSION

See also:: getCookie, setCookie

MaSession * MaRequest::getSession ( ) [inline]

Synopsis:: Get the session data store

Overview:: Get the session data store associated with this request.

Returns:: Returns a pointer to the Session object. Return zero if no session data store has been created.

Configure options:: Requires BLD_FEATURE_SESSION

char * MaRequest::getSessionId ( ) [inline]

Synopsis:: Return the Session ID

Overview:: Return the session ID associated with this session. Session IDs are strings that are unique in the server responding to the request.

Returns:: Returns a pointer to the Session ID string. Do not free.

Configure options:: Requires BLD_FEATURE_SESSION

char * MaRequest::getVar	(	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:

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:: libappWeb

See also:: setVar

int MaRequest::readPostData	(	char *	buf,
		int	bufsize
	)

Synopsis:: Read post data sent by the client in a HTTP POST request.

Overview:: This call is used by AppWeb handlers to read post data sent by the client. Handlers may operate in PUSH or PULL mode with respect to post data. In PUSH mode, appWeb will call the handlers postData method whenever post data arrives. In PULL mode, the handler calls readPostData when it is ready to accept post data. To enable PULL mode, a handler should call setPullPost.

readPostData may block while reading POST data. As such it should only be used when AppWeb is running in multi-threaded mode.

Note:: In PUSH mode, the postData method will be called when the handler is idle. It will never be issued on another thread while the handler is active.

Parameters:

buf	Pointer to buffer to store the post data
bufsize	Length of buf

Returns:: Returns the number of bytes read. It will return 0 on EOF and will return a negative MPR error code on errors.

Stability classification:: Evolving.

Library:: libappWeb

See also:: MaHandler::postData, setPullPost

void MaRequest::redirect	(	int	code,
		char *	targetUrl
	)

Synopsis:: Redirect the client to a new location

Overview:: This call will respond to the current request with a HTTP redirection. The redirection may be to another page within the current web, or it may be to a different server. This call will set the "Location" HTTP header and the HTTP response code. The caller must still call flushOutput to send the response and to close the request.

Parameters:

code	The HTTP response code to return to the client.
targetUrl	URL representing the new location. May omit the "http://server/" prefix for redirections within the exiting web.

Stability classification:: Evolving.

Library:: libappWeb

See also:: requestError

void MaRequest::requestError	(	int	code,
		char *	fmt,
		...
	)

Synopsis:: Return an error to the client

Overview:: If a handler encounters an error, it can call requestError to return the appropriate HTTP error code and message to the client.

Parameters:

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:: libappWeb

See also:: Request, write, redirect

void MaRequest::setCookie	(	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.

Parameters:

name	Name of the cookie. Must not contain a leading "$". Must contain no spaces.
value	Value of the cookie. Must not contain any spaces.
lifetime	Time in seconds that the cookie should live.
path	URL prefix path for which the cookie will be included in subsequent requests.
secure	If defined, the cookie is only valid when used with SSL connections.

Stability classification:: Evolving.

Library:: libappWeb

Configure options:: Requires BLD_FEATURE_COOKIE or BLD_FEATURE_SESSION

See also:: getCookie, getCrackedCookie

int MaRequest::setFileName

(

char *

newPath

)

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

Parameters:

newPath

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:: libappWeb

See also:: getFileName, getUri, setUri

void MaRequest::setHeader	(	char *	value,
		bool	allowMultiple = 0
	)

Synopsis:: Set a HTTP header in the response to the client.

Overview:: This call will define a header that will be included in the HTTP response to the client. AppWeb automatically creates headers such as Server, Date and Content-Length. If setHeader is called to define one of these standard headers, the defined value will override the AppWeb default. setHeader can also be used to create custom headers.

Parameters:

value

Complete header string. This is of the format

Precondition:: Key: Value Do not include a carriage return or newline in the string.

Parameters:

allowMultiple

If omitted or set to FALSE, then each call to setHeader will replace any previously defined headers. If TRU setHeader will allow muliple headers for a given key value.

Stability classification:: Evolving.

Library:: libappWeb

See also:: setResponseCode, setHeaderFlags

void MaRequest::setHeaderFlags

(

int

headerFlags

)

Synopsis:: Set various HTTP header response values

Overview:: This call is a convenience function to alter the standard HTTP response headers.

Parameters:

headerFlags

Flags may be set to MPR_HTTP_DONT_CACHE which will cause AppWeb to emit a "Cache-control: no-cache" header. This instructs downstream caches, proxies and browsers not to cache the response. If flags is set to MPR_HTTP_HEADER_WRITTEN, AppWeb will not write any standard headers and it is assumed that the handler will manually construct the HTTP headers in the response.

Stability classification:: Evolving.

Library:: libappWeb

See also:: setHeader

void MaRequest::setPullPost

(

)

Synopsis:: Switch the handler to manually pull the HTTP POST data.

Overview:: This call is used by handlers to tell AppWeb that post data must not be sent asynchronously via the postData method. Instead, the handler desires to read the post data manually.

Stability classification:: Evolving.

Library:: libappWeb

See also:: getVar

void MaRequest::setVar	(	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:

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:: libappWeb

See also:: getVar

int MaRequest::write

(

char *

)

Synopsis:: Write a string back to the client.

Overview:: Write a string back to the client.

Parameters:

s	Pointer to string to write.

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

Stability classification:: Evolving.

Library:: libappWeb

See also:: redirect, requestError, write, writeFmt

int MaRequest::write	(	char *	buf,
		int	size
	)

Synopsis:: Write a block of data back to the client.

Overview:: This call is the most efficient way to return data back to the client.

Parameters:

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:: libappWeb

See also:: redirect, requestError, write, writeFmt

int MaRequest::writeFmt	(	char *	fmt,
		...
	)

Synopsis:: Write a formatted string back to the client.

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

Parameters:

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:: libappWeb

See also:: redirect, requestError, write

The documentation for this struct was generated from the following files:

http/capi.dox
http/http.h
http/http.dox
http/request.cpp

MaRequest Struct Reference

Detailed Description

Public Member Functions

Member Function Documentation

See Also