MaRequest Class Reference

#include

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.


Public Member Functions
char *	getFileName ()
char *	getVar (char var, char defaultValue)
int	readPostData (char *buf, int bufsize)
void	redirect (int code, char *url)
void	requestError (int code, char *fmt,...)
void	setHeader (char *value, bool allowMultiple=0)
void	setHeaderFlags (int flags)
int	setFileName (char *fileName)
void	setPullPost ()
int	write (char *buf, int size)
int	write (char *s)
int	writeFmt (char *fmt,...)
void	setVar (char var, char value)
char *	getCookie ()
int	getCrackedCookie (char name, char value, char **path)
void	setCookie (char name, char value, int lifetime, char *path, bool secure)
void	createSession (int timeout)
void	destroySession ()
MaSession *	getSession ()
char *	getSessionData (char key, char defaultValue)
char *	getSessionId ()
void	setSessionData (char key, char value)
int	unsetSessionData (char *key)
void	insertAfter (MprLink *item)
void	insertPrior (MprLink *item)

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.

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.

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

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

See also:: getCookie, setCookie

char* MaRequest::getFileName ( ) [inline]

Synopsis:: Return the document file name to satisfy the current HTTP request.

Overview:: Certain URLs are mapped to corresponding documents in the file system. These may be HTML pages, CSS files or GIF/JPEG graphic files, among other file types. getFileName will return the local file system path to the document to return to the user. If the URL does not map to a local document, for example: EGI requests are served internally and do not map onto a local file name, then this call will not return meaningful data.

Returns:: Pointer to the local file name for the document. Returns empty string if the handler does not map the URL onto a local document.

Stability Classification:: Evolving.

Library:: libappWeb

See also:: setFileName

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.

char * MaRequest::getSessionData	(	char *	key,
		char *	defaultValue
	)

Synopsis:: Get the value of a session data item.

Overview:: Get the value of the session data item specified by key. If no item is yet defined, return the defaultValue.

Parameters:

key	Key value to retrieve.
defaultValue	The default value to return if the key is not defined.

Returns:: Returns a pointer to the value of the key. Do not free.

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.

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

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

void MprLink::insertAfter ( MprLink * item ) [inline, inherited]

Insert after this member.

void MprLink::insertPrior ( MprLink * item ) [inline, inherited]

Insert prior to this member.

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 *	url
	)

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 with the current web, or it may be to a different server. This request 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.
url	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

See also:: getCookie, getCrackedCookie

int MaRequest::setFileName

(

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

Parameters:

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

flags

)

Synopsis:: Set various HTTP header response values

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

Parameters:

flags

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::setSessionData	(	char *	key,
		char *	value
	)

Synopsis:: Update a session value

Overview:: Update the session value for a given key.

Parameters:

key	The name of the session data item to update.
value	The value of the session data item.

void MaRequest::setVar	(	char *	var,
		char *	value
	)	`[inline]`

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:

var	Name of environment variable to set.
value	Value to set.

Stability Classification:: Evolving.

Library:: libappWeb

See also:: getVar

int MaRequest::unsetSessionData

(

char *

key

)

Synopsis:: Unset a session data item.

Overview:: Unset and undefine a session data item.

Parameters:

key

The name of the session data item to update.

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

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

MaRequest Class Reference

Detailed Description

Public Member Functions

Member Function Documentation

See Also