MaRequest Class Reference

Inheritance diagram for MaRequest:

MprLink 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 ()
MprListgetList ()
 Destructor.
MaSessiongetSession ()
char * getSessionId ()
char * getVar (MaEnvType objType, char *var, char *defaultValue)
void insertAfter (MprLink *item)
 Return the owning list Insert after this member.
void insertPrior (MprLink *item)
 Insert prior to this member.
bool matchEtag (char *realEtag)
bool matchModified (uint realModTime)
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 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

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

bool MaRequest::matchEtag ( char *  realEtag  )  [inline]

Synopsis:
Returns whether conditional request should be performed
Overview:
This call compares ETag-fields sent with request with the ETag supplied by the client, and returns true or false depending on was a match requested or not.
Parameters:
realEtag ETag regenerated from the file
Returns:
true if the etag matches, otherwise returns false.

bool MaRequest::matchModified ( uint  realModTime  )  [inline]

Synopsis:
Returns whether conditional request should be performed
Overview:
This call compares value from last modification time sent with request towards the real last modification time of the file, and returns true or false depending on was a modification requested or not.
Parameters:
realModTime Last modified time of the resource in the client's cache.
Returns:
true if the modified header supplied by the client has been satisfied and no full response is required.

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::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 *  s  ) 

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 class was generated from the following files:

© Mbedthis Software LLC, 2003-2006. All rights reserved. Mbedthis is a trademark of Mbedthis Software LLC.