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

#include <httpd.h>

Inheritance diagram for mlib::http::connection:

Public Member Functions
const std::string &	get_path () const
	Return request target of this connection.

const std::string &	get_method () const
	Return HTTP method (GET, POST, etc.) of the request.

const std::string &	get_query () const
	Return request query string (everything after '?' and before '#')

const std::string &	get_body () const
	Return request body.

void	add_ohdr (const std::string &hdr, const std::string &value)
	Add or modify a response header.

bool	has_ihdr (const std::string &hdr) const
	Check if request has a header.

const std::string &	get_ihdr (const std::string &hdr) const
	Return the value of a request header.

const str_pairs &	get_request_headers () const
	Return all request headers.

bool	has_ohdr (const std::string &hdr) const
	Check if response has a header.

const std::string &	get_ohdr (const std::string &hdr) const
	Return the value of a response header.

bool	has_qparam (const std::string &key)
	Check if query has a parameter.

const std::string &	get_qparam (const std::string &key)
	Return the value of a query parameter.

bool	has_bparam (const std::string &key)
	Return true if request contains the given parameter in the request body.

const std::string &	get_bparam (const std::string &key)
	Return the value of a body parameter.

int	get_content_length () const
	Return size of request body.

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

void	respond (unsigned int code, const std::string &reason=std::string())
	Send the beginning of HTTP response.

void	redirect (const std::string &uri, unsigned int code=303)
	Generate a HTTP redirect response to a new resource.

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

int	serve_file (const std::filesystem::path &file)
	Send the content of a file.

int	serve_shtml (const std::filesystem::path &file)
	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.

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.

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
	connection (sock &socket, server &server)
	Protected constructor used by mlib::http::server class to create a new connection thread.

void	run () override
	The 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
server &	parent

sockstream	ws

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

Friends
class	server

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 mlib::http::server object in response to a new connection request.

The thread is started automatically by the server. It listens on the connection socket and process HTTP requests. When the HTTP client closes the connection the thread stops and the object is destructed by the server.

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

For details of request processing, see the run() function.

Most of the public functions are designed for the benefit of user handler functions. The handler function, if one has been registered, is called before sending any reply to the HTTP client.

Constructor & Destructor Documentation

◆ connection()

mlib::http::connection::connection	(	sock &	socket,
		server &	server )

protected

Protected constructor used by mlib::http::server 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 std::string &	hdr,
		const std::string &	value )

inline

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 respond() (or serve_...) function as all headers are sent at that time.

◆ get_body()

const std::string & mlib::http::connection::get_body ( ) const

inline

Return request body.

Returns: request body or empty string if request doesn't have a body

◆ get_bparam()

const std::string & mlib::http::connection::get_bparam ( const std::string & key )

inline

Return the value of a body parameter.

Only requests with content in URL-encoded format can be parsed.

Parameters

key	form parameter

Returns: parameter value

Throws an exception of type std::out_of_range if the form doesn't have the parameter.

◆ get_content_length()

int mlib::http::connection::get_content_length ( ) const

inline

Return size of request body.

If the request is a POST or PUT request without a "Content-Length" header, the request is rejected with a response code 400.

◆ get_ihdr()

const std::string & mlib::http::connection::get_ihdr ( const std::string & hdr ) const

inline

Return the value of a request header.

Parameters

hdr	header name

Returns: header value

Throws an exception of type std::out_of_range if request doesn't have the header

◆ get_method()

const std::string & mlib::http::connection::get_method ( ) const

inline

Return HTTP method (GET, POST, etc.) of the request.

Returns the <method> component of the request line.

The general structure of a HTTP request line is:

<target> := <target path>['?' <query> ['#' <fragment>]]

◆ get_ohdr()

const std::string & mlib::http::connection::get_ohdr ( const std::string & hdr ) const

inline

Return the value of a response header.

The header can belong either to server or to connection.

Parameters

hdr	header name

Returns: header field value

Throws an exception of type std::out_of_range if the response doesn't have that header.

◆ get_path()

const std::string & mlib::http::connection::get_path ( ) const

inline

Return request target of this connection.

Returns the <target path> component of the request line.

The general structure of a HTTP request line is:

<target> := <target path>['?' <query> ['#' <fragment>]]

Only origin-form (see RFC9112) is accepted.

◆ get_qparam()

const std::string & mlib::http::connection::get_qparam ( const std::string & key )

inline

Return the value of a query parameter.

Parameters

key	query parameter

Returns: parameter value

Throws an exception of type std::out_of_range if the query doesn't have the parameter.

Query parameters and their values are URL-decoded before being processed.

◆ get_query()

const std::string & mlib::http::connection::get_query ( ) const

inline

Return request query string (everything after '?' and before '#')

Returns the query component from the request line.

The general structure of a HTTP request line is:

<target> := <target path>['?' <query> ['#' <fragment>]]

Note: The returned string is not decoded.

Returns: query component of the request line or empty string if request line doesn't include a query.

◆ has_bparam()

bool mlib::http::connection::has_bparam ( const std::string & key )

inline

Return true if request contains the given parameter in the request body.

Return true if request body contains the parameter.

Request body is URL-decoded before being processed.

◆ has_ihdr()

bool mlib::http::connection::has_ihdr ( const std::string & hdr ) const

inline

Check if request has a header.

Return true if request has the header.

◆ has_ohdr()

bool mlib::http::connection::has_ohdr ( const std::string & hdr ) const

inline

Check if response has a header.

Return ‘true’ if either the server or the connection has added the header to the request response.

◆ has_qparam()

bool mlib::http::connection::has_qparam ( const std::string & key )

inline

Check if query has a parameter.

Return true if the query contains the given parameter.

Query parameters and their values are URL-decoded before being processed.

◆ redirect()

void mlib::http::connection::redirect	(	const std::string &	uri,
		unsigned int	code = 303 )

Generate a HTTP redirect response to a new resource.

Parameters

uri	path for new resource
code	redirect code

◆ respond()

void mlib::http::connection::respond	(	unsigned int	code,
		const std::string &	reason = std::string() )

Send the beginning of HTTP response.

Parameters

code	HTTP response code
reason	reason-phrase. If empty 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)

◆ run()

void mlib::http::connection::run ( )

overrideprotectedvirtual

The thread run loop.

The loop has the following steps:

Wait for a client request line and validate it.
Get request headers; validate and parse them.
For POST and PUT requests, get the request body.
Invoke the handler function if one has been defined.
Otherwise, see if it is a request for an existing file and return 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

HTTP_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

HTTP_ERR_WRITE - socket write failure

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

◆ serve_file()

int mlib::http::connection::serve_file ( const std::filesystem::path & file )

Send the content of a file.

Parameters

file file name

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

Return values

HTTP_ERR_WRITE	- socket write failure
HTTP_ERR_FOPEN	- file open failure
HTTP_ERR_FREAD	- file read failure

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

◆ serve_shtml()

int mlib::http::connection::serve_shtml ( const std::filesystem::path & file )

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

Parameters

file file name

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

◆ connection()

Member Function Documentation

◆ add_ohdr()

◆ get_body()

◆ get_bparam()

◆ get_content_length()

◆ get_ihdr()

◆ get_method()

◆ get_ohdr()

◆ get_path()

◆ get_qparam()

◆ get_query()

◆ has_bparam()

◆ has_ihdr()

◆ has_ohdr()

◆ has_qparam()

◆ redirect()

◆ respond()

◆ run()

◆ serve_buffer() [1/2]

◆ serve_buffer() [2/2]

◆ serve_file()

◆ serve_shtml()

◆ term()