Representation of a HTTP client connection request. More...

#include <httpd.h>

Inheritance diagram for mlib::http_connection:

Public Member Functions
const char *	get_uri () const
	Return URI of this connection.

const char *	get_method () const
	Return HTTP method (GET, POST, etc.)

const char *	get_all_ihdr () const
	Return all incoming headers.

void	add_ohdr (const char hdr, const char value)
	Add or modify a response header.

const char *	get_ihdr (const char *hdr) const
	Returns the value of a request header.

const char *	get_ohdr (const char *hdr) const
	Returns the value of a response header.

const char *	get_query () const
	Return URI query string (everything after '?' and before '#')

const char *	get_body () const
	Return request body.

int	get_content_length () const
	Return request body.

const std::string &	get_qparam (const char *key)
	Return the value of a query parameter or the empty string if the query doesn't have the parameter.

bool	has_qparam (const char *key)
	Return true if the query contains the given parameter.

const std::string &	get_bparam (const char *key)
	Return the value of a form parameter or the empty string if the body doesn't have the parameter.

bool	has_bparam (const char *key)
	Return true if the body contains the given parameter.

sockstream &	out ()
	Return socket object associated with this connection.

void	respond (unsigned int code, const char *reason=0)
	Send the beginning of HTTP response.

void	redirect (const char *uri, unsigned int code=303)
	Generate a HTTP redirect response to a new uri.

void	serve404 (const char *text=0)
	Sends a 404 (page not found) response.

int	serve_file (const std::string &full_path)
	Send the content of a file.

int	serve_shtml (const std::string &full_path)
	Send the content of a file, processing any SSI directives.

int	serve_buffer (const BYTE *buffer, size_t sz)
	Send the content of a buffer.

int	serve_buffer (const std::string &str)
	Send the content of a string.

void	respond_part (const char part_type, const char bound)
	Send first part of a multi-part response.

void	respond_next (bool last)
	Send subsequent parts of a multi-part response.

Public Member Functions inherited from mlib::thread
	thread (std::function< unsigned int()> func)
	Make a thread with the given function body.

virtual	~thread ()
	Destructor.

virtual void	start ()
	Begin execution of a newly created thread.

void	fork ()
	Another name for start () function.

void	join ()
	Another name for wait () function.

DWORD	wait (DWORD time_limit=INFINITE)
	Wait for thread to finish execution.

DWORD	wait_alertable (DWORD time_limit=INFINITE)
	Wait for thread to finish or an APC, or IO completion routine to occur.

DWORD	wait_msg (DWORD time_limit=INFINITE, DWORD mask=QS_ALLINPUT)
	Wait for thread to finish or a message to be queued.

void	rethrow_exception () const
	Rethrow an exception usually in the context of another thread.

DWORD	id () const
	Return thread's ID.

UINT	result () const
	Return thread's exit code.

bool	is_running () const
	Return true if thread is running.

state	get_state () const
	Return thread's execution status.

int	priority () const
	Return thread's priority.

void	priority (int pri)
	Set thread's priority.

virtual void	name (const std::string &nam)
	Set thread's name.

virtual const std::string &	name () const
	Return object's name.

virtual void	name (const std::string &nam)
	Change object's name.

Public Member Functions inherited from mlib::syncbase
	syncbase ()
	Default constructor.

	syncbase (const syncbase &e)
	Copy constructor.

	syncbase (syncbase &&e) noexcept
	Move constructor.

virtual	~syncbase ()
	Destructor.

syncbase &	operator= (const syncbase &rhs)
	Assignment operator.

syncbase &	operator= (syncbase &&rhs) noexcept
	Move assignment operator.

int	operator== (const syncbase &rhs) const
	Equality operator.

virtual void	wait ()
	Wait for object to become signaled.

virtual DWORD	wait (std::chrono::milliseconds limit)
	Wait a number of milliseconds for the object to become signaled.

	operator bool ()
	Check if object is signaled.

virtual bool	is_signaled ()
	Try to wait on the object.

HANDLE	handle () const
	Return OS handle of this object.

Protected Member Functions
	http_connection (sock &socket, httpd &server)
	Protected constructor used by httpd class to create a new connection thread.

void	run () override
	Thread run loop.

void	term () override
	Finalization function called after run.

Protected Member Functions inherited from mlib::thread
	thread (const std::string &name=std::string(), DWORD stack_size=0, PSECURITY_DESCRIPTOR sd=NULL, bool inherit=false)
	Protected constructor for use of thread-derived objects.

virtual bool	init ()
	Initialization function called before run.

Protected Member Functions inherited from mlib::syncbase
	syncbase (const std::string &name)
	Protected constructor.

void	set_handle (HANDLE h)
	Change object's handle. Closes the previous one.

Protected Attributes
httpd &	parent

sockstream	ws

Protected Attributes inherited from mlib::thread
unsigned int	exitcode
	exit code

Friends
class	httpd

Additional Inherited Members
Public Types inherited from mlib::thread
enum class	state { ready , starting , running , ending , finished }
	Execution state of a thread. More...

Detailed Description

Representation of a HTTP client connection request.

This is the thread created by the httpd server object in response to a new connection request.

After construction, the thread is started automatically by the server and it begins listening to its connection socket and process HTTP requests. When the HTTP client closes the connection the thread is stopped and destructed.

Users can create derived classes but the parent server must also be a class derived from httpd with an overridden httpd::make_thread function.

The request processing cycle starts with the receiving a client request, validating, processing it and sending back the reply. The processing part implies either calling a user handler function if one was registered for the URI or serving a file.

Most of the public functions are designed for the benefit of user handler functions. The handler function is called before sending any type of reply to the HTTP client.

Constructor & Destructor Documentation

◆ http_connection()

mlib::http_connection::http_connection	(	sock &	socket,
		httpd &	server
	)

protected

Protected constructor used by httpd class to create a new connection thread.

Parameters

socket	connecting socket
server	parent server object

As it has only a protected constructor it is not possible for users of this class to directly create this object. Derived classes should maintain this convention.

Member Function Documentation

◆ add_ohdr()

void mlib::http_connection::add_ohdr	(	const char *	hdr,
		const char *	value
	)

Add or modify a response header.

Parameters

hdr	header name
value	header value

To have any effect, this function should be called before calling the response() (or serve_...) function as all headers are sent at that time.

◆ get_ihdr()

const char * mlib::http_connection::get_ihdr ( const char * hdr ) const

Returns the value of a request header.

Parameters

hdr	header name

Returns: header value or 0 if the request does not have this header

◆ get_ohdr()

const char * mlib::http_connection::get_ohdr ( const char * hdr ) const

Returns the value of a response header.

The header can belong either to server or to connection.

Parameters

hdr	header name

Returns: header field value or 0 if there is no such header defined.

◆ get_qparam()

const std::string & mlib::http_connection::get_qparam ( const char * key )

Return the value of a query parameter or the empty string if the query doesn't have the parameter.

Parameters

key	query parameter to look for

Returns: parameter value or empty string if parameter is not found.

Even though query parameters and their values are URL encoded, the returned value is decoded.

The function also returns an empty string if the parameter exists but it doesn't have a value. For instance get_qparam("mypar") will return an empty string for any of these queries: http://example.com/page/ and http://examplre.com/page?mypar. You can use the function http_connection::has_qparam() to distinguish between the two cases.

◆ redirect()

void mlib::http_connection::redirect	(	const char *	uri,
		unsigned int	code = `303`
	)

Generate a HTTP redirect response to a new uri.

Parameters

uri	redirected uri
code	redirect code

◆ respond()

void mlib::http_connection::respond	(	unsigned int	code,
		const char *	reason = `0`
	)

Send the beginning of HTTP response.

Parameters

code	HTTP response code
reason	reason-phrase. If NULL a standard reason-phrase is used.

First time the function sends the status line and headers of the HTTP response:

  HTTP/1.1 <code> <text>
  ...
  server headers
  ...
  connection headers

In subsequent calls it sends only connection headers (to support multi-part responses)

◆ respond_next()

void mlib::http_connection::respond_next ( bool last )

Send subsequent parts of a multi-part response.

Parameters

last	true if this is the last part of the mulit-part response

This function should be called only after a call to respond_part() function.

◆ respond_part()

void mlib::http_connection::respond_part	(	const char *	part_type,
		const char *	bound
	)

Send first part of a multi-part response.

Parameters

part_type	value of the 'Content-Type' header
bound	part boundary string

◆ run()

void mlib::http_connection::run ( )

overrideprotectedvirtual

Thread run loop.

The loop collects the client request, parses, validates and processes it.

Reimplemented from mlib::thread.

◆ serve_buffer() [1/2]

int mlib::http_connection::serve_buffer	(	const BYTE *	src_buff,
		size_t	sz
	)

Send the content of a buffer.

Parameters

src_buff	buffer to send
sz	buffer length

Returns: 0 if successful or one of the following codes:

Return values

HTTPD_ERR_WRITE - socket write failure

The buffer is preceded by "Content-Length" header.

◆ serve_buffer() [2/2]

int mlib::http_connection::serve_buffer ( const std::string & str )

Send the content of a string.

Parameters

str	string to send

Returns: 0 if successful or one of the following codes:

Return values

HTTPD_ERR_WRITE - socket write failure

The string is preceded by "Content-Length" header.

◆ serve_file()

int mlib::http_connection::serve_file ( const std::string & full_path )

Send the content of a file.

Parameters

full_path fully qualified path name (UTF8 encoded)

Returns: 0 if successful or one of the following codes:

Return values

HTTPD_ERR_WRITE	- socket write failure
HTTPD_ERR_FOPEN	- file open failure
HTTPD_ERR_FREAD	- file read failure

The file is preceded by "Content-Length" header.

◆ serve_shtml()

int mlib::http_connection::serve_shtml ( const std::string & full_path )

Send the content of a file, processing any SSI directives.

Parameters

full_path fully qualified file name (UTF8 encoded)

Returns: 0 if successful or one of the following values:

Return values

-1	socket write failure
-2	file open error

As we don't know the size of the response, the file is sent without a "Content-Length" header.

◆ term()

void mlib::http_connection::term ( )

overrideprotectedvirtual

Finalization function called after run.

Reimplemented from mlib::thread.

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

include/mlib/httpd.h
src/httpd.cpp

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ http_connection()

Member Function Documentation

◆ add_ohdr()

◆ get_ihdr()

◆ get_ohdr()

◆ get_qparam()

◆ redirect()

◆ respond()

◆ respond_next()

◆ respond_part()

◆ run()

◆ serve_buffer() [1/2]

◆ serve_buffer() [2/2]

◆ serve_file()

◆ serve_shtml()

◆ term()