idfxx::http::request Class Reference

Non-owning view of an HTTP request. More...

Public Member Functions
	request (const request &)=delete
request &	operator= (const request &)=delete
	request (request &&)=delete
request &	operator= (request &&)=delete
enum method	method () const
	Returns the HTTP method of this request.
std::string_view	uri () const
	Returns the URI of this request.
size_t	content_length () const
	Returns the content length of the request body.
int	socket_fd () const
	Returns the socket file descriptor for this request's connection.
std::optional< std::string >	header (std::string_view field) const
	Retrieves a request header value by name.
std::optional< std::string >	query_string () const
	Returns the full query string from the request URI.
std::optional< std::string >	query_param (std::string_view key) const
	Retrieves a single query parameter value by key.
size_t	recv (std::span< uint8_t > buf)
	Receives raw request body data into a buffer.
size_t	recv (std::span< char > buf)
	Receives raw request body data into a character buffer.
std::string	recv_body ()
	Receives the entire request body as a string.
result< size_t >	try_recv (std::span< uint8_t > buf)
	Receives raw request body data into a buffer.
result< size_t >	try_recv (std::span< char > buf)
	Receives raw request body data into a character buffer.
result< std::string >	try_recv_body ()
	Receives the entire request body as a string.
void	set_status (std::string_view status)
	Sets the HTTP response status line.
void	set_status (int code)
	Sets the HTTP response status code.
void	set_content_type (std::string_view content_type)
	Sets the Content-Type response header.
void	set_header (std::string_view field, std::string_view value)
	Adds a response header.
void	send (std::string_view body)
	Sends a complete response with string body.
void	send (std::span< const uint8_t > body)
	Sends a complete response with binary body.
void	send_chunk (std::string_view chunk)
	Sends a chunk of a chunked response.
void	end_chunked ()
	Finalizes a chunked response.
void	send_error (int code, std::string_view message={})
	Sends an HTTP error response.
result< void >	try_send (std::string_view body)
	Sends a complete response with string body.
result< void >	try_send (std::span< const uint8_t > body)
	Sends a complete response with binary body.
result< void >	try_send_chunk (std::string_view chunk)
	Sends a chunk of a chunked response.
result< void >	try_end_chunked ()
	Finalizes a chunked response.
result< void >	try_send_error (int code, std::string_view message={})
	Sends an HTTP error response.
httpd_req_t *	idf_handle () const noexcept
	Returns the underlying ESP-IDF request handle.

Friends
class	server

Detailed Description

Non-owning view of an HTTP request.

Constructed on the stack within the C-to-C++ trampoline and passed by reference to handlers. Provides methods for reading request data (headers, query parameters, body) and sending responses.

This class must not outlive the handler invocation. It is non-copyable and non-movable to prevent accidental use-after-callback.

Definition at line 58 of file server.hpp.

Constructor & Destructor Documentation

request() [1/2]

idfxx::http::request::request ( const request &  )

delete

request() [2/2]

idfxx::http::request::request ( request &&  )

delete

Member Function Documentation

content_length()

size_t idfxx::http::request::content_length

(

)

const

Returns the content length of the request body.

Returns

The content length in bytes.

end_chunked()

void idfxx::http::request::end_chunked ( )

inline

Finalizes a chunked response.

Sends the terminal empty chunk, signalling end of response.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

Definition at line 280 of file server.hpp.

References try_end_chunked(), and idfxx::unwrap().

header()

std::optional< std::string > idfxx::http::request::header

(

std::string_view

field

)

const

Retrieves a request header value by name.

Parameters

field

Header name to look up.

Returns

The header value, or std::nullopt if the header is not present.

idf_handle()

httpd_req_t * idfxx::http::request::idf_handle ( ) const

inlinenoexcept

Returns the underlying ESP-IDF request handle.

Returns

The httpd_req_t pointer.

Definition at line 452 of file server.hpp.

method()

enum method idfxx::http::request::method

(

)

const

Returns the HTTP method of this request.

Returns

The request method.

operator=() [1/2]

request & idfxx::http::request::operator= ( const request &  )

delete

operator=() [2/2]

request & idfxx::http::request::operator= ( request &&  )

delete

query_param()

std::optional< std::string > idfxx::http::request::query_param

(

std::string_view

key

)

const

Retrieves a single query parameter value by key.

Parameters

key	The query parameter name.

Returns

The parameter value, or std::nullopt if the key is not present.

query_string()

std::optional< std::string > idfxx::http::request::query_string

(

)

const

Returns the full query string from the request URI.

Returns

The query string, or std::nullopt if no query string is present.

recv() [1/2]

size_t idfxx::http::request::recv ( std::span< char >  buf )

inline

Receives raw request body data into a character buffer.

Parameters

buf	Buffer to receive data into.

Returns

Number of bytes received.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

Definition at line 146 of file server.hpp.

References try_recv(), and idfxx::unwrap().

recv() [2/2]

size_t idfxx::http::request::recv ( std::span< uint8_t >  buf )

inline

Receives raw request body data into a buffer.

Parameters

buf	Buffer to receive data into.

Returns

Number of bytes received.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

Definition at line 136 of file server.hpp.

References try_recv(), and idfxx::unwrap().

recv_body()

std::string idfxx::http::request::recv_body ( )

inline

Receives the entire request body as a string.

Reads all remaining body data up to content_length() bytes.

Returns

The request body string.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

Definition at line 157 of file server.hpp.

References try_recv_body(), and idfxx::unwrap().

send() [1/2]

void idfxx::http::request::send ( std::span< const uint8_t >  body )

inline

Sends a complete response with binary body.

Parameters

body	The response body data.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

Definition at line 258 of file server.hpp.

References try_send(), and idfxx::unwrap().

send() [2/2]

void idfxx::http::request::send ( std::string_view  body )

inline

Sends a complete response with string body.

server.on_get("/hello", [](idfxx::http::request& req) -> idfxx::result<void> {
    req.set_content_type("text/plain");
    req.send("Hello, World!");
    return {};
});

Parameters

body	The response body string.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

Definition at line 249 of file server.hpp.

References try_send(), and idfxx::unwrap().

send_chunk()

void idfxx::http::request::send_chunk ( std::string_view  chunk )

inline

Sends a chunk of a chunked response.

Call repeatedly to stream data to the client. Call end_chunked() to finalize the chunked response.

Parameters

chunk

The chunk data to send.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

Definition at line 270 of file server.hpp.

References try_send_chunk(), and idfxx::unwrap().

send_error()

void idfxx::http::request::send_error ( int  code, std::string_view  message = {}  )

inline

Sends an HTTP error response.

Parameters

code	The HTTP error status code (e.g. 404, 500).
message	Optional error message body.

Note

Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error

on failure.

Definition at line 290 of file server.hpp.

set_content_type()

void idfxx::http::request::set_content_type

(

std::string_view

content_type

)

Sets the Content-Type response header.

The string is copied internally and kept alive until the response is sent.

Parameters

content_type

The MIME type string (e.g. "application/json").

set_header()

void idfxx::http::request::set_header	(	std::string_view	field,
		std::string_view	value
	)

Adds a response header.

Both field and value are copied internally and kept alive until the response is sent.

Parameters

field	Header name.
value	Header value.

set_status() [1/2]

void idfxx::http::request::set_status

(

int

code

)

Sets the HTTP response status code.

Maps common status codes to their standard reason phrases. Falls back to just the numeric code for unrecognized values.

Parameters

code	The HTTP status code (e.g. 200, 404).

set_status() [2/2]

void idfxx::http::request::set_status

(

std::string_view

status

)

Sets the HTTP response status line.

The string must remain in the format "NNN Reason Phrase" (e.g. "200 OK"). The string is copied internally and kept alive until the response is sent.

Parameters

status

The status string (e.g. "200 OK").

socket_fd()

int idfxx::http::request::socket_fd

(

)

const

Returns the socket file descriptor for this request's connection.

Returns

The socket file descriptor.

try_end_chunked()

result< void > idfxx::http::request::try_end_chunked

(

)

Finalizes a chunked response.

Sends the terminal empty chunk, signalling end of response.

Returns

Success, or an error.

Referenced by end_chunked().

try_recv() [1/2]

result< size_t > idfxx::http::request::try_recv

(

std::span< char >

buf

)

Receives raw request body data into a character buffer.

Parameters

buf	Buffer to receive data into.

Returns

Number of bytes received, or an error.

try_recv() [2/2]

result< size_t > idfxx::http::request::try_recv

(

std::span< uint8_t >

buf

)

Receives raw request body data into a buffer.

Parameters

buf	Buffer to receive data into.

Returns

Number of bytes received, or an error.

Referenced by recv(), and recv().

try_recv_body()

result< std::string > idfxx::http::request::try_recv_body

(

)

Receives the entire request body as a string.

Reads all remaining body data up to content_length() bytes.

Returns

The request body string, or an error.

Referenced by recv_body().

try_send() [1/2]

result< void > idfxx::http::request::try_send

(

std::span< const uint8_t >

body

)

Sends a complete response with binary body.

Parameters

body	The response body data.

Returns

Success, or an error.

try_send() [2/2]

result< void > idfxx::http::request::try_send

(

std::string_view

body

)

Sends a complete response with string body.

Parameters

body	The response body string.

Returns

Success, or an error.

Referenced by send(), and send().

try_send_chunk()

result< void > idfxx::http::request::try_send_chunk

(

std::string_view

chunk

)

Sends a chunk of a chunked response.

Call repeatedly to stream data to the client. Call try_end_chunked() to finalize the chunked response.

Parameters

chunk

The chunk data to send.

Returns

Success, or an error.

Referenced by send_chunk().

try_send_error()

result< void > idfxx::http::request::try_send_error	(	int	code,
		std::string_view	message = {}
	)

Sends an HTTP error response.

Parameters

code	The HTTP error status code (e.g. 404, 500).
message	Optional error message body.

Returns

Success, or an error.

uri()

std::string_view idfxx::http::request::uri

(

)

const

Returns the URI of this request.

Returns

The request URI string.

Friends And Related Symbol Documentation

server

friend class server

friend

Definition at line 455 of file server.hpp.

---

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

• idfxx_http_server/include/idfxx/http/server.hpp