ulxr::HttpServer Class Reference
[HTTP and HTML handling]

A simple server for an http connection. More...

#include <ulxr_http_server.h>

Collaboration diagram for ulxr::HttpServer:


Public Member Functions
	HttpServer (HttpProtocol *prot, bool wbxml=false)
	Constructs a HttpServer in single threaded mode.
	HttpServer (HttpProtocol *prot, unsigned num, bool wbxml=false)
	Constructs a HttpServer in multithreaded mode.
virtual	~HttpServer ()
	Destroys the http server.
std::size_t	runPicoHttpd ()
	Runs a very simple http server.
void	setHttpRoot (const CppString &root)
	Sets the root of the pico http server.
virtual void	addRealm (const CppString &path, const CppString &realm)
	Adds another cross reference from a http resource to a realm.
virtual CppString	getRealm (const CppString &path) const
	Gets realm name of a resource.
void	addHttpHandler (const CppString &name, MethodHandler *handler)
	Sets a new handler for a http method.
void	addResource (CachedResource *cache)
	Adds a resource.
CachedResource *	getResource (const CppString &name)
	Gets a resource .
void	setRpcDispatcher (Dispatcher *disp)
	Sets a dispatcher for incoming RPC calls.
void	requestTermination ()
	Requests the server loop to terminate.
void	addAuthentication (const CppString &user, const CppString &pass, const CppString &realm)
	Adds another potential username, password and "range" for this connection (server mode).
unsigned	numThreads () const
	Gets the number of installed threads.
void	terminateAllThreads (unsigned time=0)
	Terminates all threads.
void	shutdownAllThreads (unsigned time=0)
	Signals termination and shuts down all ports.
void	waitAsync (bool term, bool stat=false)
	Waits for all threads to complete.
Protected Member Functions
void	printStatistics () const
	Prints some statistics about the running threads.
virtual void	forwardThreadedError (const Exception &ex) const
	Forwards error that happen within threads.
virtual void	executeHttpMethod (HttpProtocol *prot, Cpp8BitString &conn_pending_data, const CppString &name, const CppString &resource)
	Executes the appropriate method when the connection acts as http server.
virtual void	executeUnknownHttpMethod (HttpProtocol *prot, Cpp8BitString &conn_pending_data, const CppString &name, const CppString &resource)
	Executes a http method not known to ulxmlrpcpp.
virtual void	executeHttpGET (HttpProtocol *prot, const CppString &resource)
	Executes the GET method when the connection acts as http server.
virtual void	executeHttpPUT (HttpProtocol *prot, Cpp8BitString &conn_pending_data, const CppString &resource)
	Executes the PUT method when the connection acts as http server.
virtual void	executeHttpPOST (HttpProtocol *prot, Cpp8BitString &conn_pending_data, const CppString &resource)
	Executes the POST method when the connection acts as http server.
virtual void	executeHttpRPC (HttpProtocol *prot, Cpp8BitString &conn_pending_data)
	Executes the RPC server.
virtual void	executeHttpDELETE (HttpProtocol *prot, const CppString &resource)
	Executes the DELETE method when the connection acts as http server.
void	performHttpTransaction (HttpProtocol *prot)
	Performs a complete http transaction.
virtual void	interpreteHttpHeader (HttpProtocol *prot, CppString &head_resource, CppString &head_method, CppString &head_version)
	Processes all the http headers after the header has been completely read.
CppString	stripResource (const CppString &resource)
	Strips protocol and host name from the resource.
virtual void	checkValidPath (const CppString &resource)
	Checks if the resource contains a valid path.
CppString	createLocalName (const CppString &resource)
	creates the local filename from the httpd root and the resource name.
virtual CppString	guessMimeType (const CppString &name) const
	Tries to guess a mime type from the given file.
Private Member Functions
virtual void	beforeHttpTransaction ()
	Perform some user defined action before processing the next request.
virtual void	afterHttpTransaction ()
	Perform some user defined action after processing the request.
std::size_t	runPicoHttpd (HttpProtocol prot, ThreadData td=0)
	Runs a very simple http server.
void	releaseThreads ()
	Deletes all allocated thread objects.
unsigned	dispatchAsync ()
	Lauch the http server threads which waits for requests.
void	releaseHandlers (std::vector< MethodHandler * > &handlers)
	Deletes all registered http method handlers.
void	init ()
	Sets up internal variables.
	HttpServer (const HttpServer &)
HttpServer &	operator= (const HttpServer &)
Static Private Member Functions
static void *	startThread (ThreadData *td)
	Helper method to start a thread.
Private Attributes
CppString	rpc_resource_root
CppString	http_root_dir
bool	pico_shall_run
bool	wbxml_mode
Dispatcher *	rpc_dispatcher
HttpProtocol *	base_protocol
std::vector< ThreadData * >	threads
std::vector< MethodHandler * >	getHandlers
std::vector< MethodHandler * >	putHandlers
std::vector< MethodHandler * >	postHandlers
std::vector< MethodHandler * >	deleteHandlers
std::vector< CachedResource * >	resources
std::map< CppString, CppString >	realmXrefs
Classes
class	ThreadData

Detailed Description

A simple server for an http connection.

This implementation only honors the basic http methods PUT, GET, POST and DELETE. It is not intended as a replacement for a full featured web server.

Definition at line 56 of file ulxr_http_server.h.

Constructor & Destructor Documentation

ulxr::HttpServer::HttpServer	(	HttpProtocol *	prot,
		bool	wbxml = `false`
	)

Constructs a HttpServer in single threaded mode.

Parameters:

	prot	pointer to an existing http protocol
	wbxml	true: use binary xml for xml-rpc

Definition at line 151 of file ulxr_http_server.cpp.

References base_protocol, init(), ulxr::HttpProtocol::setChunkedTransfer(), and wbxml_mode.

ulxr::HttpServer::HttpServer	(	HttpProtocol *	prot,
		unsigned	num,
		bool	wbxml = `false`
	)

Constructs a HttpServer in multithreaded mode.

Parameters:

	prot	pointer to an existing http protocol
	num	number of parallel threads
	wbxml	true: use binary xml for xml-rpc

Definition at line 162 of file ulxr_http_server.cpp.

References base_protocol, ulxr::HttpProtocol::detach(), init(), ulxr::HttpProtocol::setChunkedTransfer(), threads, and wbxml_mode.

ulxr::HttpServer::~HttpServer ( ) [virtual]

Destroys the http server.

Definition at line 202 of file ulxr_http_server.cpp.

References deleteHandlers, getHandlers, postHandlers, putHandlers, releaseHandlers(), releaseThreads(), resources, and waitAsync().

ulxr::HttpServer::HttpServer ( const HttpServer & ) [private]

Member Function Documentation

std::size_t ulxr::HttpServer::runPicoHttpd ( )

Runs a very simple http server.

You should think of it as a file server that is capable of reading/writing/deleting/posting files, not much more. But it also includes the routing of RPC request! Derived classes might of course implement for example running scripts or do something else more advanced.

Returns:: in multithreaded mode: number of created threads. Otherwise after termination: 0.

Definition at line 759 of file ulxr_http_server.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

void ulxr::HttpServer::setHttpRoot ( const CppString & root )

Sets the root of the pico http server.

Parameters:

root

top level directory of the server

Definition at line 282 of file ulxr_http_server.cpp.

References ULXR_DIRSEP, ULXR_PCHAR, and ULXR_TRACE.

void ulxr::HttpServer::addRealm	(	const CppString &	path,
		const CppString &	realm
	)			`[virtual]`

Adds another cross reference from a http resource to a realm.

The default implementation assumes that all added resources are paths so the last character should be a slash. It then tries to find these paths at the beginning of paths in queries assuming that all files below the according path belong to the same realm.

Parameters:

	path	name of resource
	realm	name of realm

Definition at line 1095 of file ulxr_http_server.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

CppString ulxr::HttpServer::getRealm ( const CppString & path ) const [virtual]

Gets realm name of a resource.

The default implementation is very simple and only does a string compare with the given path and the realm-to-resource mapping. The longest match is taken.

Parameters:

path

name of resource which must match exactly.

Returns:: name of realm or "" if unavailable.

Definition at line 1045 of file ulxr_http_server.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

void ulxr::HttpServer::addHttpHandler	(	const CppString &	name,
		MethodHandler *	handler
	)

Sets a new handler for a http method.

The handler will be invoked after the header has been read completely. All information like http fields can be queried from the connection. If a handler was willing (not necessarily able) to perform the method it must return "true". Otherwise the next handler will be invoked.

Attention:: The handler must completely process the transaction: reading the rest of the message body and send the response.

Parameters:

	name	method name. Only GET, PUT, POST, DELETE are supported
	handler	pointer to handler object. Ownership is taken.

Definition at line 991 of file ulxr_http_server.cpp.

References ulxr::ApplicationError, ulxr::makeUpper(), ULXR_PCHAR, and ULXR_TRACE.

void ulxr::HttpServer::addResource ( CachedResource * cache )

Adds a resource.

Parameters:

cache

pointer to the resource

Definition at line 462 of file ulxr_http_server.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

CachedResource * ulxr::HttpServer::getResource ( const CppString & name )

Gets a resource .

Parameters:

name

name of the resource

Definition at line 470 of file ulxr_http_server.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

void ulxr::HttpServer::setRpcDispatcher ( Dispatcher * disp )

Sets a dispatcher for incoming RPC calls.

Parameters:

disp

pointer to RPC dispatcher

Definition at line 226 of file ulxr_http_server.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

void ulxr::HttpServer::requestTermination ( )

Requests the server loop to terminate.

Note: only a flag is set which is checked before waiting for the next call. For a remote shutdown implement a rpc method with calls this method or from outside call terminateAllThreads().

Definition at line 753 of file ulxr_http_server.cpp.

void ulxr::HttpServer::addAuthentication	(	const CppString &	user,
		const CppString &	pass,
		const CppString &	realm
	)

Adds another potential username, password and "range" for this connection (server mode).

Parameters:

	user	Username
	pass	Password
	realm	Synonym for area which shall be accessed

Definition at line 1103 of file ulxr_http_server.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

unsigned ulxr::HttpServer::numThreads ( ) const

Gets the number of installed threads.

Returns:: number of threads

Definition at line 1164 of file ulxr_http_server.cpp.

void ulxr::HttpServer::terminateAllThreads ( unsigned time = 0 )

Terminates all threads.

The threads only get a message and must terminate themselves.

Parameters:

time

planned: time in ms to wait before killing.

Definition at line 1170 of file ulxr_http_server.cpp.

References ULXR_MULTITHREADED, ULXR_PCHAR, and ULXR_TRACE.

void ulxr::HttpServer::shutdownAllThreads ( unsigned time = 0 )

Signals termination and shuts down all ports.

This is a rather rude way to terminate to stop the servers

Parameters:

time

planned: time in ms to wait before killing.

Definition at line 1183 of file ulxr_http_server.cpp.

References ULXR_MULTITHREADED, ULXR_PCHAR, and ULXR_TRACE.

void ulxr::HttpServer::waitAsync	(	bool	term,
		bool	stat = `false`
	)

Waits for all threads to complete.

Parameters:

	term	true: signal all threads to shut down as soon as possible.
	stat	true: print some statistical data to stdout.

Definition at line 1207 of file ulxr_http_server.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

Referenced by ~HttpServer().

void ulxr::HttpServer::printStatistics ( ) const [protected]

Prints some statistics about the running threads.

Definition at line 1255 of file ulxr_http_server.cpp.

References ULXR_COUT, and ULXR_PCHAR.

void ulxr::HttpServer::forwardThreadedError ( const Exception & ex ) const [protected, virtual]

Forwards error that happen within threads.

Parameters:

Exception that occured

Definition at line 901 of file ulxr_http_server.cpp.

References ULXR_CHAR, and ULXR_TRACE.

void ulxr::HttpServer::executeHttpMethod	(	HttpProtocol *	prot,
		Cpp8BitString &	conn_pending_data,
		const CppString &	name,
		const CppString &	resource
	)			`[protected, virtual]`

Executes the appropriate method when the connection acts as http server.

Parameters:

	prot	pointer to the connecthion object
	conn_pending_data	already received chunk from connection
	name	the method (GET, PUT ..)
	resource	name of the resource

Definition at line 332 of file ulxr_http_server.cpp.

References ULXR_PCHAR, and ULXR_TRACE.

void ulxr::HttpServer::executeUnknownHttpMethod	(	HttpProtocol *	prot,
		Cpp8BitString &	conn_pending_data,
		const CppString &	name,
		const CppString &	resource
	)			`[protected, virtual]`

Executes a http method not known to ulxmlrpcpp.

The default is to throw an according exception.

Parameters:

	prot	pointer to the connecthion object
	conn_pending_data	already received chunk from connection
	name	the method (GET, PUT ..)
	resource	name of the resource

Definition at line 387 of file ulxr_http_server.cpp.

References ulxr::NotConformingError, ulxr_i18n, and ULXR_PCHAR.

void ulxr::HttpServer::executeHttpGET	(	HttpProtocol *	prot,
		const CppString &	resource
	)			`[protected, virtual]`

Executes the GET method when the connection acts as http server.

Parameters:

	prot	pointer to the connecthion object
	resource	name of the resource

Definition at line 485 of file ulxr_http_server.cpp.

References ulxr::CachedResource::data(), ulxr::CachedResource::good(), ulxr::CachedResource::open(), ulxr::CachedResource::reset(), ulxr::SystemError, ULXR_DIRSEP, ulxr_i18n, ULXR_PCHAR, and ULXR_TRACE.

void ulxr::HttpServer::executeHttpPUT	(	HttpProtocol *	prot,
		Cpp8BitString &	conn_pending_data,
		const CppString &	resource
	)			`[protected, virtual]`

Executes the PUT method when the connection acts as http server.

Parameters:

	prot	pointer to the connecthion object
	conn_pending_data	already received chunk from connection
	resource	name of the resource

TODO:

Todo:: readBody

Definition at line 633 of file ulxr_http_server.cpp.

References ulxr::CachedResource::clear(), ulxr::CachedResource::good(), ulxr::SystemError, ULXR_DIRSEP, ulxr_i18n, ULXR_PCHAR, ULXR_RECV_BUFFER_SIZE, ULXR_TRACE, and ulxr::CachedResource::write().

void ulxr::HttpServer::executeHttpPOST	(	HttpProtocol *	prot,
		Cpp8BitString &	conn_pending_data,
		const CppString &	resource
	)			`[protected, virtual]`

Executes the POST method when the connection acts as http server.

If the request resource is the same as "rpc_resource_root" and a dispatcher is available then executeHttpRPC is invoked.

Parameters:

	prot	pointer to the connecthion object
	conn_pending_data	already received chunk from connection
	resource	name of the resource

Definition at line 610 of file ulxr_http_server.cpp.

References ulxr::ApplicationError, ulxr_i18n, ULXR_PCHAR, and ULXR_TRACE.

void ulxr::HttpServer::executeHttpRPC	(	HttpProtocol *	prot,
		Cpp8BitString &	conn_pending_data
	)			`[protected, virtual]`

Executes the RPC server.

Parameters:

	prot	pointer to the connecthion object
	conn_pending_data	already received chunk from connection

TODO:

Todo:: readBody

Definition at line 521 of file ulxr_http_server.cpp.

References ulxr::MethodCallParserBase::getMethodCall(), ulxr::NotConformingError, ULXR_DOUT_READ, ULXR_DOUT_XML, ULXR_GET_STRING, ulxr_i18n, ULXR_PCHAR, ULXR_RECV_BUFFER_SIZE, and ULXR_TRACE.

void ulxr::HttpServer::executeHttpDELETE	(	HttpProtocol *	prot,
		const CppString &	resource
	)			`[protected, virtual]`

Executes the DELETE method when the connection acts as http server.

Parameters:

	prot	pointer to the connection object
	resource	name of the resource

Definition at line 693 of file ulxr_http_server.cpp.

References ulxr::CachedResource::clear(), ulxr::CachedResource::good(), ulxr::SystemError, ULXR_DIRSEP, ulxr_i18n, ULXR_PCHAR, and ULXR_TRACE.

void ulxr::HttpServer::performHttpTransaction ( HttpProtocol * prot ) [protected]

Performs a complete http transaction.

A request is read from the connection, processes and the result sent back to the client.

Parameters:

prot

pointer to the connecthion object

Definition at line 908 of file ulxr_http_server.cpp.

References ulxr::Protocol::ConnBody, ulxr::Protocol::ConnError, ulxr::Protocol::ConnSwitchToBody, ulxr::TransportError, ulxr_i18n, ULXR_PCHAR, ULXR_RECV_BUFFER_SIZE, ULXR_TRACE, and ulxr::Exception::why().

void ulxr::HttpServer::interpreteHttpHeader	(	HttpProtocol *	prot,
		CppString &	head_resource,
		CppString &	head_method,
		CppString &	head_version
	)			`[protected, virtual]`

Processes all the http headers after the header has been completely read.

Parameters:

	prot	pointer to the connecthion object
	head_resource	resource in http header
	head_method	method name name in http header
	head_version	version in http header