fastcgi++  3.1alpha
A C++ FastCGI/Web API
Fastcgipp::Request< charT > Class Template Referenceabstract

Request handling class More...

#include <fastcgi++/request.hpp>

Inheritance diagram for Fastcgipp::Request< charT >:
[legend]
Collaboration diagram for Fastcgipp::Request< charT >:
[legend]

Public Member Functions

 Request (const size_t maxPostSize=0)
 Initializes what it can. configure() to finish. More...
 
void configure (const Protocol::RequestId &id, const Protocol::Role &role, bool kill, const std::function< void(const Socket &, Block &&, bool)> send, const std::function< void(Message)> callback)
 Configures the request with the data it needs. More...
 
std::unique_lock< std::mutex > handler ()
 Request Handler. More...
 
virtual ~Request ()
 
void push (Message &&message)
 Send a message to the request. More...
 

Public Attributes

std::mutex mutex
 Only one thread is allowed to handle the request at a time. More...
 

Protected Member Functions

const Http::Environment< charT > & environment () const
 Const accessor for the HTTP environment data. More...
 
Http::Environment< charT > & environment ()
 Accessor for the HTTP environment data. More...
 
virtual void errorHandler ()
 Called when a processing error occurs. More...
 
virtual void bigPostErrorHandler ()
 Called when too much post data is recieved. More...
 
virtual void unknownContentErrorHandler ()
 Called when receiving an unknown content type. More...
 
Protocol::Role role () const
 See the requests role. More...
 
const std::function< void(Message)> & callback () const
 Callback function for dealings outside the fastcgi++ library. More...
 
virtual bool response ()=0
 Response generator. More...
 
virtual void inHandler (int bytesReceived)
 Generate a data input response. More...
 
virtual bool inProcessor ()
 Process custom POST data. More...
 
void dump (const char *data, size_t size)
 Dumps raw data directly into the FastCGI protocol. More...
 
void dump (const unsigned char *data, size_t size)
 Dumps raw data directly into the FastCGI protocol. More...
 
void dump (std::basic_istream< char > &stream)
 Dumps an input stream directly into the FastCGI protocol. More...
 
unsigned pickLocale (const std::vector< std::string > &locales)
 Pick a locale. More...
 
void setLocale (const std::string &locale)
 Set the output stream's locale. More...
 

Protected Attributes

std::basic_ostream< charT > out
 Standard output stream to the client. More...
 
std::basic_ostream< charT > err
 Output stream to the HTTP server error log. More...
 
Message m_message
 The message associated with the current handler() call. More...
 
std::queue< Messagem_messages
 A queue of message for the request. More...
 
std::mutex m_messagesMutex
 Thread safe our message queue. More...
 

Private Member Functions

void complete ()
 Generates an END_REQUEST FastCGI record. More...
 
const char * codepage () const
 Codepage. More...
 
const char * codepage () const
 
const char * codepage () const
 

Private Attributes

std::function< void(Message)> m_callback
 The callback function for dealings outside the fastcgi++ library. More...
 
Http::Environment< charT > m_environment
 The data structure containing all HTTP environment data. More...
 
const size_t m_maxPostSize
 The maximum amount of post data, in bytes, that can be recieved. More...
 
Protocol::Role m_role
 The role that the other side expects this request to play. More...
 
Protocol::RequestId m_id
 The complete ID (request id & file descriptor) associated with the request. More...
 
bool m_kill
 Should the socket be closed upon completion. More...
 
Protocol::RecordType m_state
 What the request is current doing. More...
 
std::function< void(const Socket &, Block &&, bool kill)> m_send
 Function to actually send the record. More...
 
Protocol::ProtocolStatus m_status
 Status to end the request with. More...
 
FcgiStreambuf< charT > m_outStreamBuffer
 Stream buffer for the out stream. More...
 
FcgiStreambuf< charT > m_errStreamBuffer
 Stream buffer for the err stream. More...
 

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 utf8 encoding pass wchar_t as the template argument and use wide character unicode internally for everything. If you want to use a 8bit character set pass char as the template argument and use char for everything internally.

Template Parameters
charTCharacter type for internal processing (wchar_t or char)
Date
October 13, 2018
Author
Eddie Carle <eddie.nosp@m.@isa.nosp@m.tec.c.nosp@m.a>

Definition at line 117 of file request.hpp.

Constructor & Destructor Documentation

◆ Request()

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

Initializes what it can. configure() to finish.

Parameters
maxPostSizeThis would be the maximum size, in bytes, you want to allow for post data. Any data beyond this size would result in a call to bigPostErrorHandler(). With the default being 0, POST uploading is by default prohibited. Should you wish to have the limit as large as possible, pass either (size_t)-1, std::string::npos or std::numeric_limits<size_t>::max().

Definition at line 131 of file request.hpp.

◆ ~Request()

template<class charT >
virtual Fastcgipp::Request< charT >::~Request ( )
inlinevirtual

Definition at line 166 of file request.hpp.

Member Function Documentation

◆ bigPostErrorHandler()

template<class charT >
void Fastcgipp::Request< charT >::bigPostErrorHandler
protectedvirtual

Called when too much post data is recieved.

This function is called when the client sends too much data the request. By default it will send a standard 413 Request Entity Too Large Error message to the user. Override for more specialized purposes.

Definition at line 187 of file request.cpp.

◆ callback()

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

Callback function for dealings outside the fastcgi++ library.

The purpose of the callback function 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 a Block for some data.

Definition at line 231 of file request.hpp.

◆ codepage() [1/3]

const char * Fastcgipp::Request< wchar_t >::codepage ( ) const
private

Definition at line 291 of file request.cpp.

◆ codepage() [2/3]

const char * Fastcgipp::Request< char >::codepage ( ) const
private

Definition at line 296 of file request.cpp.

◆ codepage() [3/3]

template<class charT >
const char* Fastcgipp::Request< charT >::codepage ( ) const
inlineprivate

Codepage.

◆ complete()

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

Generates an END_REQUEST FastCGI record.

Definition at line 32 of file request.cpp.

References Fastcgipp::Protocol::EndRequest::appStatus, Fastcgipp::Block::begin(), Fastcgipp::Logging::header(), Fastcgipp::Protocol::EndRequest::protocolStatus, and Fastcgipp::version.

Here is the call graph for this function:

◆ configure()

template<class charT >
void Fastcgipp::Request< charT >::configure ( const Protocol::RequestId id,
const Protocol::Role role,
bool  kill,
const std::function< void(const Socket &, Block &&, bool)>  send,
const std::function< void(Message)>  callback 
)

Configures 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]idComplete ID of the request
[in]roleThe role that the other side expects this request to4 play
[in]killBoolean value indicating whether or not the socket should be closed upon completion
[in]sendFunction for sending data out of the stream buffers
[in]callbackCallback function capable of passing messages to the request

Definition at line 219 of file request.cpp.

◆ dump() [1/3]

template<class charT >
void Fastcgipp::Request< charT >::dump ( const char *  data,
size_t  size 
)
inlineprotected

Dumps raw data directly into the FastCGI protocol.

This function exists as a mechanism to dump raw data out the stream bypassing the stream buffer or any code conversion mechanisms. If the user has any binary data to send, this is the function to do it with.

Parameters
[in]dataPointer to first byte of data to send
[in]sizeSize in bytes of data to be sent

Definition at line 305 of file request.hpp.

◆ dump() [2/3]

template<class charT >
void Fastcgipp::Request< charT >::dump ( const unsigned char *  data,
size_t  size 
)
inlineprotected

Dumps raw data directly into the FastCGI protocol.

This function exists as a mechanism to dump raw data out the stream bypassing the stream buffer or any code conversion mechanisms. If the user has any binary data to send, this is the function to do it with.

Parameters
[in]dataPointer to first byte of data to send
[in]sizeSize in bytes of data to be sent

Definition at line 319 of file request.hpp.

◆ dump() [3/3]

template<class charT >
void Fastcgipp::Request< charT >::dump ( std::basic_istream< char > &  stream)
inlineprotected

Dumps an input stream directly into the FastCGI protocol.

This function exists as a mechanism to dump a raw input stream out this stream bypassing the stream buffer or any code conversion mechanisms. Typically this would be a filestream associated with an image or something. The stream is transmitted until an EOF.

Parameters
[in]streamReference to input stream that should be transmitted.

Definition at line 334 of file request.hpp.

◆ environment() [1/2]

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

Accessor for the HTTP environment data.

Definition at line 176 of file request.hpp.

◆ environment() [2/2]

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

Const accessor for the HTTP environment data.

Definition at line 170 of file request.hpp.

◆ errorHandler()

template<class charT >
void Fastcgipp::Request< charT >::errorHandler
protectedvirtual

Called when a processing error occurs.

This function is called whenever a processing error happens inside the request. By default it will send a standard 500 Internal Server Error message to the user. Override for more specialized purposes.

Definition at line 171 of file request.cpp.

◆ handler()

template<class charT >
std::unique_lock< std::mutex > Fastcgipp::Request< charT >::handler ( )
virtual

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
A lock locking the requests message queue. If the request completes this will be unlocked. If the request isn't complete it will be locked. If locked, makes sure to unlock it after unlocking Request::mutex.
See also
callback

Implements Fastcgipp::Request_base.

Definition at line 56 of file request.cpp.

References Fastcgipp::Block::begin(), Fastcgipp::Message::data, ERROR_LOG, Fastcgipp::Logging::header(), Fastcgipp::Message::type, and WARNING_LOG.

Here is the call graph for this function:

◆ inHandler()

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 264 of file request.hpp.

◆ inProcessor()

template<class charT >
virtual bool Fastcgipp::Request< charT >::inProcessor ( )
inlineprotectedvirtual

Process custom POST data.

Override this function should you wish to process non-standard post data. The library will on it's own process post data of the types "multipart/form-data" and "application/x-www-form-urlencoded". To use this function, your raw post data is fully assembled in environment().postBuffer() and the type string is stored in environment().contentType. Should the content type be what you're looking for and you've processed it, simply return true. Otherwise return false. Do not worry about freeing the data in the post buffer. Should you return false, the system will try to internally process it.

Returns
Return true if you've processed the data.

Definition at line 282 of file request.hpp.

◆ pickLocale()

template<class charT >
unsigned Fastcgipp::Request< charT >::pickLocale ( const std::vector< std::string > &  locales)
protected

Pick a locale.

Basically this finds the first language in environment().acceptLanguages that matches a locale in the container passed as a parameter. It returns the index in the parameters that points to the chosen locale.

Definition at line 244 of file request.cpp.

◆ push()

void Fastcgipp::Request_base::push ( Message &&  message)
inlineinherited

Send a message to the request.

Definition at line 102 of file request.hpp.

◆ response()

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

◆ role()

template<class charT >
Protocol::Role Fastcgipp::Request< charT >::role ( ) const
inlineprotected

See the requests role.

Definition at line 213 of file request.hpp.

◆ setLocale()

template<class charT >
void Fastcgipp::Request< charT >::setLocale ( const std::string &  locale)
protected

Set the output stream's locale.

Definition at line 275 of file request.cpp.

References ERROR_LOG.

◆ unknownContentErrorHandler()

template<class charT >
void Fastcgipp::Request< charT >::unknownContentErrorHandler
protectedvirtual

Called when receiving an unknown content type.

This function is called when the client sends an unknown content type. By default it will send a standard 415 Unsupported Media Type message to the user. Override for more specialized purposes.

Definition at line 203 of file request.cpp.

Member Data Documentation

◆ err

template<class charT >
std::basic_ostream<charT> Fastcgipp::Request< charT >::err
protected

Output stream to the HTTP server error log.

Definition at line 185 of file request.hpp.

◆ m_callback

template<class charT >
std::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 365 of file request.hpp.

◆ m_environment

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

The data structure containing all HTTP environment data.

Definition at line 368 of file request.hpp.

◆ m_errStreamBuffer

template<class charT >
FcgiStreambuf<charT> Fastcgipp::Request< charT >::m_errStreamBuffer
private

Stream buffer for the err stream.

Definition at line 398 of file request.hpp.

◆ m_id

template<class charT >
Protocol::RequestId Fastcgipp::Request< charT >::m_id
private

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

Definition at line 377 of file request.hpp.

◆ m_kill

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

Should the socket be closed upon completion.

Definition at line 380 of file request.hpp.

◆ m_maxPostSize

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

The maximum amount of post data, in bytes, that can be recieved.

Definition at line 371 of file request.hpp.

◆ m_message

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

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 294 of file request.hpp.

◆ m_messages

std::queue<Message> Fastcgipp::Request_base::m_messages
protectedinherited

A queue of message for the request.

Definition at line 110 of file request.hpp.

◆ m_messagesMutex

std::mutex Fastcgipp::Request_base::m_messagesMutex
protectedinherited

Thread safe our message queue.

Definition at line 113 of file request.hpp.

◆ m_outStreamBuffer

template<class charT >
FcgiStreambuf<charT> Fastcgipp::Request< charT >::m_outStreamBuffer
private

Stream buffer for the out stream.

Definition at line 395 of file request.hpp.

◆ m_role

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 374 of file request.hpp.

◆ m_send

template<class charT >
std::function<void(const Socket&, Block&&, bool kill)> Fastcgipp::Request< charT >::m_send
private

Function to actually send the record.

Definition at line 389 of file request.hpp.

◆ m_state

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

What the request is current doing.

Definition at line 383 of file request.hpp.

◆ m_status

template<class charT >
Protocol::ProtocolStatus Fastcgipp::Request< charT >::m_status
private

Status to end the request with.

Definition at line 392 of file request.hpp.

◆ mutex

std::mutex Fastcgipp::Request_base::mutex
inherited

Only one thread is allowed to handle the request at a time.

Definition at line 99 of file request.hpp.

◆ out

template<class charT >
std::basic_ostream<charT> Fastcgipp::Request< charT >::out
protected

Standard output stream to the client.

Definition at line 182 of file request.hpp.


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