fastcgi++
Classes | Public Member Functions | Public Attributes | Protected Member Functions | Private Member Functions | Private Attributes | Friends
Fastcgipp::Request< charT > Class Template Reference

Request handling class More...

#include <request.hpp>

List of all members.

Classes

class  Messages
 Queue type for pending messages. More...

Public Member Functions

 Request (const size_t maxPostSize=0)
 Initializes what it can. set() must be called by Manager before the data is usable.
const Http::Environment< charT > & environment () const
 Accessor for the data structure containing all HTTP environment data.
virtual void errorHandler (const std::exception &error)
 Called when an exception is caught.
virtual void bigPostErrorHandler ()
 Called when too much post data is recieved.
Protocol::Role role () const
 See the requests role.
const boost::function< void(Message)> & callback () const
 Accessor for the callback function for dealings outside the fastcgi++ library.
void setloc (std::locale loc_)
 Set the requests locale.
const std::locale & getloc ()
 Retrieves the requests locale.

Public Attributes

Fcgistream< charT > out
 Standard output stream to the client.
Fcgistream< charT > err
 Output stream to the HTTP server error log.

Protected Member Functions

virtual bool response ()=0
 Response generator.
virtual void inHandler (int bytesReceived)
 Generate a data input response.
const Messagemessage () const
 The message associated with the current handler() call.

Private Member Functions

bool handler ()
 Request Handler.
void complete ()
 Generates an END_REQUEST FastCGI record.
void set (Protocol::FullId id_, Transceiver &transceiver_, Protocol::Role role_, bool killCon_, boost::function< void(Message)> callback_)
 Set's up the request with the data it needs.

Private Attributes

std::locale loc
 The locale associated with the request. Should be set with setloc(), not directly.
Message m_message
 The message associated with the current handler() call.
boost::function< void(Message)> m_callback
 The callback function for dealings outside the fastcgi++ library.
Http::Environment< charT > m_environment
 The data structure containing all HTTP environment data.
Messages messages
 A queue of messages to be handler by the request.
const size_t m_maxPostSize
 The maximum amount of post data that can be recieved.
Transceivertransceiver
 Pointer to the transceiver object that will send data to the other side.
Protocol::Role m_role
 The role that the other side expects this request to play.
Protocol::FullId id
 The complete ID (request id & file descriptor) associated with the request.
bool killCon
 Boolean value indicating whether or not the file descriptor should be closed upon completion.
Protocol::RecordType state
 What the request is current doing.

Friends

class Manager

Detailed Description

template<class charT>
class Fastcgipp::Request< charT >

Request handling class

Derivations of this class will handle requests. This includes building the environment data, processing post/get data, fetching data (files, database), and producing a response. Once all client data is organized, response() will be called. At minimum, derivations of this class must define response().

If you want to use UTF-8 encoding pass wchar_t as the template argument, use setloc() to setup a UTF-8 locale and use wide character unicode internally for everything. If you want to use a 8bit character set encoding pass char as the template argument and setloc() a locale with the corresponding character set.

Template Parameters:
charTCharacter type for internal processing (wchar_t or char)

Definition at line 61 of file request.hpp.


Constructor & Destructor Documentation

template<class charT >
Fastcgipp::Request< charT >::Request ( const size_t  maxPostSize = 0)
inline

Initializes what it can. set() must be called by Manager before the data is usable.

Parameters:
maxPostSizeThis would be the maximum size you want to allow for post data. Any data beyond this size would result in a call to bigPostErrorHandler(). A value of 0 represents unlimited.

Definition at line 70 of file request.hpp.

References Fastcgipp::Request< charT >::m_environment, Fastcgipp::Request< charT >::out, and Fastcgipp::Request< charT >::setloc().


Member Function Documentation

template<class charT >
void Fastcgipp::Request< charT >::bigPostErrorHandler ( )
virtual

Called when too much post data is recieved.

Definition at line 190 of file request.cpp.

template<class charT >
const boost::function<void(Message)>& Fastcgipp::Request< charT >::callback ( ) const
inline

Accessor for the callback function for dealings outside the fastcgi++ library.

The purpose of the callback object is to provide a thread safe mechanism for functions and classes outside the fastcgi++ library to talk to the requests. Should the library wish to have another thread process or fetch some data, that thread can call this function when it is finished. It is equivalent to this:

void callback(Message msg);

The sole parameter is a Message that contains both a type value for processing by response() and the raw castable data.

Definition at line 118 of file request.hpp.

References Fastcgipp::Request< charT >::m_callback.

template<class charT >
void Fastcgipp::Request< charT >::complete ( )
private

Generates an END_REQUEST FastCGI record.

Definition at line 25 of file request.cpp.

References Fastcgipp::Block::data, Fastcgipp::Protocol::END_REQUEST, Fastcgipp::Protocol::REQUEST_COMPLETE, and Fastcgipp::version.

template<class charT >
const Http::Environment<charT>& Fastcgipp::Request< charT >::environment ( ) const
inline

Accessor for the data structure containing all HTTP environment data.

Definition at line 73 of file request.hpp.

References Fastcgipp::Request< charT >::m_environment.

template<class charT >
void Fastcgipp::Request< charT >::errorHandler ( const std::exception &  error)
virtual

Called when an exception is caught.

This function is called whenever an exception is caught inside the request. By default it will output some data to the error log and send a standard 500 Internal Server Error message to the user. Override for more specialized purposes.

Parameters:
[in]errorException caught

Definition at line 170 of file request.cpp.

template<class charT >
const std::locale& Fastcgipp::Request< charT >::getloc ( )
inline

Retrieves the requests locale.

Returns:
Constant reference to the requests locale

Definition at line 136 of file request.hpp.

References Fastcgipp::Request< charT >::loc.

template<class charT >
bool Fastcgipp::Request< charT >::handler ( )
private

Request Handler.

This function is called by Manager::handler() to handle messages destined for the request. It deals with FastCGI messages (type=0) while passing all other messages off to response().

Returns:
Boolean value indicating completion (true means complete)
See also:
callback

Definition at line 49 of file request.cpp.

References Fastcgipp::Protocol::ABORT_REQUEST, Fastcgipp::Protocol::AUTHORIZER, Fastcgipp::Block::data, Fastcgipp::Protocol::END_REQUEST, Fastcgipp::Http::HTTP_METHOD_POST, Fastcgipp::Protocol::IN, Fastcgipp::Protocol::OUT, Fastcgipp::Protocol::PARAMS, Fastcgipp::Protocol::RESPONDER, Fastcgipp::Protocol::UNKNOWN_ROLE, and Fastcgipp::version.

template<class charT >
virtual void Fastcgipp::Request< charT >::inHandler ( int  bytesReceived)
inlineprotectedvirtual

Generate a data input response.

This function exists should the library user wish to do something like generate a partial response based on bytes received from the client. The function is called by handler() every time a FastCGI IN record is received. The function has no access to the data, but knows exactly how much was received based on the value that was passed. Note this value represents the amount of data received in the individual record, not the total amount received in the environment. If the library user wishes to have such a value they would have to keep a tally of all size values passed.

Parameters:
[in]bytesReceivedAmount of bytes received in this FastCGI record

Definition at line 161 of file request.hpp.

template<class charT >
const Message& Fastcgipp::Request< charT >::message ( ) const
inlineprotected

The message associated with the current handler() call.

This is only of use to the library user when a non FastCGI (type=0) Message is passed by using the requests callback.

See also:
callback

Definition at line 170 of file request.hpp.

References Fastcgipp::Request< charT >::m_message.

template<class charT >
virtual bool Fastcgipp::Request< charT >::response ( )
protectedpure virtual

Response generator.

This function is called by handler() once all request data has been received from the other side or if a Message not of a FastCGI type has been passed to it. The function shall return true if it has completed the response and false if it has not (waiting for a callback message to be sent).

Returns:
Boolean value indication completion (true means complete)
See also:
callback
template<class charT >
Protocol::Role Fastcgipp::Request< charT >::role ( ) const
inline

See the requests role.

Definition at line 104 of file request.hpp.

References Fastcgipp::Request< charT >::m_role.

template<class charT >
void Fastcgipp::Request< charT >::set ( Protocol::FullId  id_,
Transceiver transceiver_,
Protocol::Role  role_,
bool  killCon_,
boost::function< void(Message)>  callback_ 
)
inlineprivate

Set's up the request with the data it needs.

This function is an "after-the-fact" constructor that build vital initial data for the request.

Parameters:
[in]id_Complete ID of the request
[in]transceiver_Transceiver object the request will use
[in]role_The role that the other side expects this request to play
[in]killCon_Boolean value indicating whether or not the file descriptor should be closed upon completion
[in]callback_Callback function capable of passing messages to the request

Definition at line 247 of file request.hpp.

References Fastcgipp::Protocol::ERR, Fastcgipp::Request< charT >::err, Fastcgipp::Request< charT >::killCon, Fastcgipp::Request< charT >::m_callback, Fastcgipp::Request< charT >::m_role, Fastcgipp::Request< charT >::out, Fastcgipp::Protocol::OUT, and Fastcgipp::Request< charT >::transceiver.

template<class charT >
void Fastcgipp::Request< charT >::setloc ( std::locale  loc_)
inline

Set the requests locale.

This function both sets loc to the locale passed to it and imbues the locale into the out and err stream. The user should always call this function as opposed to setting the locales directly is this functions insures the utf8 code conversion is functioning properly.

Parameters:
[in]loc_New locale
See also:
loc
out

Definition at line 130 of file request.hpp.

References Fastcgipp::Request< charT >::err, and Fastcgipp::Request< charT >::out.

Referenced by Fastcgipp::Request< charT >::Request().


Friends And Related Function Documentation

template<class charT >
friend class Manager
friend

Definition at line 173 of file request.hpp.


Member Data Documentation

template<class charT >
Fcgistream<charT> Fastcgipp::Request< charT >::err

Output stream to the HTTP server error log.

To dump data directly through the stream without it being code converted and bypassing the stream buffer call Fcgistream::dump()

Definition at line 88 of file request.hpp.

Referenced by Fastcgipp::Request< charT >::set(), and Fastcgipp::Request< charT >::setloc().

template<class charT >
Protocol::FullId Fastcgipp::Request< charT >::id
private

The complete ID (request id & file descriptor) associated with the request.

Definition at line 230 of file request.hpp.

template<class charT >
bool Fastcgipp::Request< charT >::killCon
private

Boolean value indicating whether or not the file descriptor should be closed upon completion.

Definition at line 232 of file request.hpp.

Referenced by Fastcgipp::Request< charT >::set().

template<class charT >
std::locale Fastcgipp::Request< charT >::loc
private

The locale associated with the request. Should be set with setloc(), not directly.

Definition at line 176 of file request.hpp.

Referenced by Fastcgipp::Request< charT >::getloc().

template<class charT >
boost::function<void(Message)> Fastcgipp::Request< charT >::m_callback
private

The callback function for dealings outside the fastcgi++ library.

The purpose of the callback object is to provide a thread safe mechanism for functions and classes outside the fastcgi++ library to talk to the requests. Should the library wish to have another thread process or fetch some data, that thread can call this function when it is finished. It is equivalent to this:

void callback(Message msg);

The sole parameter is a Message that contains both a type value for processing by response() and the raw castable data.

Definition at line 199 of file request.hpp.

Referenced by Fastcgipp::Request< charT >::callback(), and Fastcgipp::Request< charT >::set().

template<class charT >
Http::Environment<charT> Fastcgipp::Request< charT >::m_environment
private

The data structure containing all HTTP environment data.

Definition at line 202 of file request.hpp.

Referenced by Fastcgipp::Request< charT >::environment(), and Fastcgipp::Request< charT >::Request().

template<class charT >
const size_t Fastcgipp::Request< charT >::m_maxPostSize
private

The maximum amount of post data that can be recieved.

Definition at line 214 of file request.hpp.

template<class charT >
Message Fastcgipp::Request< charT >::m_message
private

The message associated with the current handler() call.

This is only of use to the library user when a non FastCGI (type=0) Message is passed by using the requests callback.

See also:
callback

Definition at line 185 of file request.hpp.

Referenced by Fastcgipp::Request< charT >::message().

template<class charT >
Protocol::Role Fastcgipp::Request< charT >::m_role
private

The role that the other side expects this request to play.

Definition at line 228 of file request.hpp.

Referenced by Fastcgipp::Request< charT >::role(), and Fastcgipp::Request< charT >::set().

template<class charT >
Messages Fastcgipp::Request< charT >::messages
private

A queue of messages to be handler by the request.

Definition at line 211 of file request.hpp.

template<class charT >
Fcgistream<charT> Fastcgipp::Request< charT >::out

Standard output stream to the client.

To dump data directly through the stream without it being code converted and bypassing the stream buffer call Fcgistream::dump()

Definition at line 82 of file request.hpp.

Referenced by Fastcgipp::Request< charT >::Request(), Fastcgipp::Request< charT >::set(), and Fastcgipp::Request< charT >::setloc().

template<class charT >
Protocol::RecordType Fastcgipp::Request< charT >::state
private

What the request is current doing.

Definition at line 234 of file request.hpp.

template<class charT >
Transceiver* Fastcgipp::Request< charT >::transceiver
private

Pointer to the transceiver object that will send data to the other side.

Definition at line 226 of file request.hpp.

Referenced by Fastcgipp::Request< charT >::set().


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