Basic helper for REST API servers. More...

#include <tsRestServer.h>

Public Member Functions
	RestServer (const RestArgs &args, Report &report)
	Constructor.

void	addResponseHeader (const UString &name, const UString &value)
	Add a header which will be sent with the response.

bool	getPostJSON (json::ValuePtr &value) const
	Get the POST data from the request in JSON format.

void	getPostText (UString &data) const
	Get the POST data from the request in text format.

bool	getRequest (TCPConnection &conn)
	Accept and decode one client request.

bool	hasParameter (const UString &name) const
	Check if the request's query parameters contains a parameter.

UString	header (const UString &name, const UString &def_value=UString()) const
	Get the first value of a given request header.

const UStringToUStringMultiMap &	headers () const
	Get a multimap of all request headers.

const UString &	method () const
	Return the request method of the previous getRequest().

UString	parameter (const UString &name, const UString &def_value=UString()) const
	Get the value of a given request's query parameter.

const UStringToUStringMultiMap &	parameters () const
	Get a multimap of all request's query parameters.

const UString &	path () const
	Get the path of the last received request.

const UString &	postContentType () const
	Get the MIME type of the POST data, if specified.

const ByteBlock &	postData () const
	Get the POST data from the request.

void	replaceResponseHeader (const UString &name, const UString &value)
	Replace a header which will be sent with the response.

void	reset ()
	Cleanup request data, restart from an empty state.

bool	sendResponse (TCPConnection &conn, int http_status, bool close)
	Send the response to the last client request.

void	setResponse (const ByteBlock &data, const UString &mime_type=u"application/octet-stream")
	Store the data to be sent with the response.

void	setResponse (const json::Value &value, const UString &mime_type=u"application/json")
	Store the data to be sent with the response.

void	setResponse (const UString &text, const UString &mime_type=u"text/plain; charset=utf-8")
	Store the data to be sent with the response.

const UString &	token () const
	Get the authentication token of the last received request, if any.

Detailed Description

Basic helper for REST API servers.

Constructor & Destructor Documentation

◆ RestServer()

ts::RestServer::RestServer	(	const RestArgs &	args,
		Report &	report
	)

Constructor.

Parameters

[in]	args	Initial REST operation arguments. This instance will keep a copy of it.
[in,out]	report	Where to report errors. This instance will keep a reference to it.

Member Function Documentation

◆ getRequest()

bool ts::RestServer::getRequest ( TCPConnection & conn )

Accept and decode one client request.

If the RestArgs contains a non-empty authentication token, this token is checked in the request headers. If there is no matching token in the request, the request is rejected and the connection is closed.

Parameters

[in,out] conn Client connection. This can be any TCPConnection but usually this is a TLSConnection.

Returns: True on success, false on error. In case of error, the connection is closed.

◆ method()

const UString & ts::RestServer::method ( ) const

inline

Return the request method of the previous getRequest().

Returns: A constant reference to the request method, typically "GET" or "POST".

◆ path()

const UString & ts::RestServer::path ( ) const

inline

Get the path of the last received request.

Returns: A constant reference to the path of the last received request.

◆ parameters()

const UStringToUStringMultiMap & ts::RestServer::parameters ( ) const

inline

Get a multimap of all request's query parameters.

Returns: A constant reference to the parameters. Valid until the next request.

◆ hasParameter()

bool ts::RestServer::hasParameter ( const UString & name ) const

Check if the request's query parameters contains a parameter.

Parameters

[in] name Name of the parameter to check.

Returns: True if the parameter name is present, false otherwise.

◆ parameter()

UString ts::RestServer::parameter	(	const UString &	name,
		const UString &	def_value = `UString()`
	)		const

Get the value of a given request's query parameter.

Parameters

[in]	name	Name of the parameter to fetch.
[in]	def_value	Value to return if the parameter name is not present.

Returns: The value of the parameter name, or the default value.

◆ headers()

const UStringToUStringMultiMap & ts::RestServer::headers ( ) const

inline

Get a multimap of all request headers.

Returns: A constant reference to the headers. Valid until the next request.

◆ header()

UString ts::RestServer::header	(	const UString &	name,
		const UString &	def_value = `UString()`
	)		const

Get the first value of a given request header.

Parameters

[in]	name	Name of the header to fetch.
[in]	def_value	Value to return if the header name is not present.

Returns: The value of the header name, or the default value.

◆ token()

const UString & ts::RestServer::token ( ) const

inline

Get the authentication token of the last received request, if any.

Note that if the RestArgs contains a non-empty authentication token, this token was already checked by getRequest() and the request was rejected it the token didn't match.

Returns: A constant reference to the authentication token of the last received request.

◆ postContentType()

const UString & ts::RestServer::postContentType ( ) const

inline

Get the MIME type of the POST data, if specified.

Returns: A constant reference to the MIME type of the POST data or the empty string if unspecified.

◆ postData()

const ByteBlock & ts::RestServer::postData ( ) const

inline

Get the POST data from the request.

Returns: A constant reference to the POST data. Valid until the next request.

◆ getPostText()

void ts::RestServer::getPostText ( UString & data ) const

Get the POST data from the request in text format.

Parameters

[out] data The POST data.

◆ getPostJSON()

bool ts::RestServer::getPostJSON ( json::ValuePtr & value ) const

Get the POST data from the request in JSON format.

Parameters

[out] value The POST data.

Returns: True on success, false on error (typically invalid JSON data).

◆ addResponseHeader()

void ts::RestServer::addResponseHeader	(	const UString &	name,
		const UString &	value
	)

Add a header which will be sent with the response.

If the same header already exists with another value, a new header is added.

Parameters

[in]	name	The header name.
[in]	value	The header value.

◆ replaceResponseHeader()

void ts::RestServer::replaceResponseHeader	(	const UString &	name,
		const UString &	value
	)

Replace a header which will be sent with the response.

If the same header already exists with another value, it is replaced.

Parameters

[in]	name	The header name.
[in]	value	The header value.

◆ setResponse() [1/3]

void ts::RestServer::setResponse	(	const ByteBlock &	data,
		const UString &	mime_type = `u"application/octet-stream"`
	)

Store the data to be sent with the response.

Parameters

[in]	data	Returned data in binary form.
[in]	mime_type	Optional MIME type for these data.

◆ setResponse() [2/3]

void ts::RestServer::setResponse	(	const UString &	text,
		const UString &	mime_type = `u"text/plain; charset=utf-8"`
	)

Store the data to be sent with the response.

Parameters

[in]	text	Returned data in text format.
[in]	mime_type	Optional MIME type for these data.

◆ setResponse() [3/3]

void ts::RestServer::setResponse	(	const json::Value &	value,
		const UString &	mime_type = `u"application/json"`
	)

Store the data to be sent with the response.

Parameters

[in]	value	Returned data in JSON format.
[in]	mime_type	Optional MIME type for these data.

◆ sendResponse()

bool ts::RestServer::sendResponse	(	TCPConnection &	conn,
		int	http_status,
		bool	close
	)

Send the response to the last client request.

Parameters

[in,out]	conn	Client connection from which the request was received.
[in]	http_status	HTTP status code (200, 404, etc.)
[in]	close	If true, the connection is closed after sending the response.

Returns: True on success, false on error. In case of error, the connection is closed.

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

tsRestServer.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ RestServer()

Member Function Documentation

◆ getRequest()

◆ method()

◆ path()

◆ parameters()

◆ hasParameter()

◆ parameter()

◆ headers()

◆ header()

◆ token()

◆ postContentType()

◆ postData()

◆ getPostText()

◆ getPostJSON()

◆ addResponseHeader()

◆ replaceResponseHeader()

◆ setResponse() [1/3]

◆ setResponse() [2/3]

◆ setResponse() [3/3]

◆ sendResponse()