HTTP client with blocking and streaming request support. More...

Classes
struct	config
	HTTP client configuration. More...

class	error_category
	Error category for HTTP client errors. More...

Public Types
enum class	errc : esp_err_t { max_redirect = 0x7001 , connect = 0x7002 , write_data = 0x7003 , fetch_header = 0x7004 , invalid_transport = 0x7005 , connecting = 0x7006 , eagain = 0x7007 , connection_closed = 0x7008 }
	Error codes for HTTP client operations. More...

enum class	state : int { uninit = 0 , init = 1 , connecting = 2 , connected = 3 , req_complete_header = 4 , req_complete_data = 5 , res_complete_header = 6 , res_on_data_start = 7 , res_complete_data = 8 , close = 9 }
	HTTP client lifecycle state. More...

Public Member Functions
	client (config cfg)
	Creates an HTTP client from configuration.

	~client ()
	Destroys the client and releases all resources.

	client (const client &)=delete

client &	operator= (const client &)=delete

	client (client &&) noexcept
	Move constructor.

client &	operator= (client &&) noexcept
	Move assignment.

void	set_url (std::string_view url)
	Sets the request URL.

result< void >	try_set_url (std::string_view url)
	Sets the request URL.

void	set_method (enum method m)
	Sets the HTTP method.

void	set_header (std::string_view key, std::string_view value)
	Sets a request header.

void	delete_header (std::string_view key)
	Deletes a request header.

void	set_post_field (std::string_view data)
	Sets the POST request body.

void	set_username (std::string_view username)
	Sets the username for authentication.

void	set_password (std::string_view password)
	Sets the password for authentication.

void	set_auth_type (enum auth_type type)
	Sets the authentication type.

template<typename Rep , typename Period >
void	set_timeout (const std::chrono::duration< Rep, Period > &timeout)
	Sets the request timeout.

void	perform ()
	Performs a blocking HTTP request.

result< void >	try_perform ()
	Performs a blocking HTTP request.

void	open (size_t write_len=0)
	Opens a connection for streaming.

void	open (int write_len)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

size_t	write (std::span< const uint8_t > data)
	Writes data to the open connection.

size_t	write (std::string_view data)
	Writes string data to the open connection.

int64_t	fetch_headers ()
	Reads and processes response headers.

size_t	read (std::span< uint8_t > buf)
	Reads response body data.

size_t	read (std::span< char > buf)
	Reads response body data into a character buffer.

void	flush_response ()
	Discards any remaining response data.

void	close ()
	Closes the connection.

result< void >	try_open (size_t write_len=0)
	Opens a connection for streaming.

result< void >	try_open (int write_len)
	This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

result< size_t >	try_write (std::span< const uint8_t > data)
	Writes data to the open connection.

result< size_t >	try_write (std::string_view data)
	Writes string data to the open connection.

result< int64_t >	try_fetch_headers ()
	Reads and processes response headers.

result< size_t >	try_read (std::span< uint8_t > buf)
	Reads response body data.

result< size_t >	try_read (std::span< char > buf)
	Reads response body data into a character buffer.

result< void >	try_flush_response ()
	Discards any remaining response data.

result< void >	try_close ()
	Closes the connection.

int	status_code () const
	Returns the HTTP response status code.

int64_t	content_length () const
	Returns the response content length.

int	chunk_length () const
	Returns the length of the current chunk in a chunked response.

result< int >	try_chunk_length () const
	Returns the length of the current chunk in a chunked response.

bool	is_chunked_response () const
	Checks whether the response uses chunked transfer encoding.

std::optional< std::string >	get_header (std::string_view key) const
	Retrieves a response header value.

std::string	get_url () const
	Retrieves the current effective URL.

void	set_redirection ()
	Applies the current redirect URL.

result< void >	try_set_redirection ()
	Applies the current redirect URL.

void	reset_redirect_counter ()
	Resets the redirect counter to zero.

void	cancel_request ()
	Cancels an ongoing HTTP request.

result< void >	try_cancel_request ()
	Cancels an ongoing HTTP request.

enum state	get_state () const
	Returns the current lifecycle state of the client.

esp_http_client_handle_t	idf_handle () const noexcept
	Returns the underlying ESP-IDF HTTP client handle.

Static Public Member Functions
static result< client >	make (config cfg)
	Creates an HTTP client from configuration.

Detailed Description

HTTP client with blocking and streaming request support.

Manages an HTTP session with support for TLS, authentication, custom headers, redirects, and event callbacks. Provides both a simple blocking perform() API and a streaming open()/write()/read()/close() API.

Not thread-safe — callers must manage their own synchronization.

Definition at line 87 of file client.hpp.

Member Enumeration Documentation

◆ errc

enum class idfxx::http::client::errc : esp_err_t

strong

Error codes for HTTP client operations.

Enumerator
max_redirect	Maximum number of redirects exceeded.
connect	Connection to server failed.
write_data	Error writing request data.
fetch_header	Error reading response headers.
invalid_transport	Invalid transport type specified.
connecting	Connection in progress (async mode)
eagain	Resource temporarily unavailable, try again.
connection_closed	Connection closed by remote.

Definition at line 92 of file client.hpp.

◆ state

enum class idfxx::http::client::state : int

strong

HTTP client lifecycle state.

Covers the full lifecycle: initialization, connection establishment, request transmission, and response reception.

Enumerator
uninit	Client not yet initialized.
init	Client initialized.
connecting	Connecting to server.
connected	Connected to server.
req_complete_header	Request headers sent.
req_complete_data	Request data sent.
res_complete_header	Response headers received.
res_on_data_start	Response data started.
res_complete_data	Response data completed.
close	Connection closed.

Definition at line 642 of file client.hpp.

Constructor & Destructor Documentation

◆ client() [1/3]

idfxx::http::client::client ( config cfg )

explicit

Creates an HTTP client from configuration.

Parameters

cfg	Client configuration.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

◆ ~client()

idfxx::http::client::~client ( )

Destroys the client and releases all resources.

◆ client() [2/3]

idfxx::http::client::client ( const client & )

delete

◆ client() [3/3]

idfxx::http::client::client ( client && )

noexcept

Move constructor.

Transfers handle ownership.

Member Function Documentation

◆ cancel_request()

void idfxx::http::client::cancel_request ( )

inline

Cancels an ongoing HTTP request.

Closes the current connection and opens a new socket. Useful for aborting long-running or streaming requests.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 621 of file client.hpp.

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

◆ chunk_length()

int idfxx::http::client::chunk_length ( ) const

inline

Returns the length of the current chunk in a chunked response.

Only valid when the response uses chunked transfer encoding.

Returns: The chunk length in bytes.

Exceptions

std::system_error if the response is not chunked or the client is not initialized.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled.

if (client.is_chunked_response()) {
    int len = client.chunk_length();
}

Definition at line 534 of file client.hpp.

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

◆ close()

void idfxx::http::client::close ( )

inline

Closes the connection.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 425 of file client.hpp.

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

◆ content_length()

int64_t idfxx::http::client::content_length ( ) const

Returns the response content length.

Returns: Content length in bytes, or -1 if unknown/chunked.

◆ delete_header()

void idfxx::http::client::delete_header ( std::string_view key )

Deletes a request header.

Parameters

key	Header name to remove.

◆ fetch_headers()

int64_t idfxx::http::client::fetch_headers ( )

inline

Reads and processes response headers.

Must be called after open() (and any write() calls) before reading response body data.

Returns: The content length, or -1 if chunked/unknown.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 389 of file client.hpp.

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

◆ flush_response()

void idfxx::http::client::flush_response ( )

inline

Discards any remaining response data.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 417 of file client.hpp.

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

◆ get_header()

std::optional< std::string > idfxx::http::client::get_header ( std::string_view key ) const

Retrieves a response header value.

Parameters

key	Header name to look up.

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

◆ get_state()

enum state idfxx::http::client::get_state ( ) const

Returns the current lifecycle state of the client.

Reports where the client is in the connect/request/response lifecycle.

Returns: The client state.

◆ get_url()

std::string idfxx::http::client::get_url ( ) const

Retrieves the current effective URL.

May differ from the originally configured URL after redirects.

Returns: The current URL.

◆ idf_handle()

esp_http_client_handle_t idfxx::http::client::idf_handle ( ) const

inlinenoexcept

Returns the underlying ESP-IDF HTTP client handle.

Returns: The esp_http_client handle.

Definition at line 671 of file client.hpp.

◆ is_chunked_response()

bool idfxx::http::client::is_chunked_response ( ) const

Checks whether the response uses chunked transfer encoding.

Returns: true if the response is chunked.

◆ make()

static result< client > idfxx::http::client::make ( config cfg )

static

Creates an HTTP client from configuration.

Parameters

cfg	Client configuration.

Returns: The new client, or an error.

◆ open() [1/2]

void idfxx::http::client::open ( int write_len )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 357 of file client.hpp.

References open().

Referenced by open().

◆ open() [2/2]

void idfxx::http::client::open ( size_t write_len = 0 )

inline

Opens a connection for streaming.

Opens the HTTP connection and sends request headers. If write_len is greater than zero, the connection is opened for writing that many bytes before reading the response.

Parameters

write_len Number of bytes to write (0 for read-only requests).

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error if write_len exceeds INT_MAX or the connection fails.

Definition at line 354 of file client.hpp.

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

◆ operator=() [1/2]

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

noexcept

Move assignment.

Transfers handle ownership.

◆ operator=() [2/2]

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

delete

◆ perform()

void idfxx::http::client::perform ( )

inline

Performs a blocking HTTP request.

Sends the request and reads the complete response. Use event callbacks or the streaming API to process response data.

idfxx::http::client c({.url = "https://example.com"});
c.perform();
auto status = c.status_code();

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 325 of file client.hpp.

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

◆ read() [1/2]

size_t idfxx::http::client::read ( std::span< char > buf )

inline

Reads response body data into a character buffer.

Parameters

buf	Buffer to read into.

Returns: Number of bytes read, or 0 at end of response.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 409 of file client.hpp.

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

◆ read() [2/2]

size_t idfxx::http::client::read ( std::span< uint8_t > buf )

inline

Reads response body data.

Parameters

buf	Buffer to read into.

Returns: Number of bytes read, or 0 at end of response.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 399 of file client.hpp.

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

◆ reset_redirect_counter()

void idfxx::http::client::reset_redirect_counter ( )

Resets the redirect counter to zero.

Allows additional redirects up to max_redirection_count.

◆ set_auth_type()

void idfxx::http::client::set_auth_type ( enum auth_type type )

Sets the authentication type.

Parameters

type	The authentication type.

◆ set_header()

void idfxx::http::client::set_header	(	std::string_view	key,
		std::string_view	value
	)

Sets a request header.

Throws std::bad_alloc (or aborts) on allocation failure.

Parameters

key	Header name.
value	Header value.

◆ set_method()

void idfxx::http::client::set_method ( enum method m )

Sets the HTTP method.

Parameters

m	The HTTP method.

◆ set_password()

void idfxx::http::client::set_password ( std::string_view password )

Sets the password for authentication.

Parameters

password The password.

◆ set_post_field()

void idfxx::http::client::set_post_field ( std::string_view data )

Sets the POST request body.

The client takes ownership of a copy of the data, keeping it alive for the duration of the request. Throws std::bad_alloc (or aborts) on allocation failure.

Parameters

data	POST body content.

◆ set_redirection()

void idfxx::http::client::set_redirection ( )

inline

Applies the current redirect URL.

Sets the client URL to the redirect target from the Location header. Typically called from a redirect event callback when automatic redirect is disabled.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 586 of file client.hpp.

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

◆ set_timeout()

template<typename Rep , typename Period >

void idfxx::http::client::set_timeout ( const std::chrono::duration< Rep, Period > & timeout )

inline

Sets the request timeout.

Template Parameters

Rep	Duration representation type.
Period	Duration period type.

Parameters

timeout The timeout duration.

Definition at line 301 of file client.hpp.

References idfxx::timeout.

◆ set_url()

void idfxx::http::client::set_url ( std::string_view url )

inline

Sets the request URL.

Parameters

url	The URL string.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 225 of file client.hpp.

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

◆ set_username()

void idfxx::http::client::set_username ( std::string_view username )

Sets the username for authentication.

Parameters

username The username.

◆ status_code()

int idfxx::http::client::status_code ( ) const

Returns the HTTP response status code.

Returns: The status code (e.g. 200, 404).

◆ try_cancel_request()

result< void > idfxx::http::client::try_cancel_request ( )

Cancels an ongoing HTTP request.

Closes the current connection and opens a new socket. Useful for aborting long-running or streaming requests.

Returns: Success, or an error.

Referenced by cancel_request().

◆ try_chunk_length()

result< int > idfxx::http::client::try_chunk_length ( ) const

Returns the length of the current chunk in a chunked response.

Only valid when the response uses chunked transfer encoding.

Returns: The chunk length in bytes.

Return values

errc::invalid_state	if the client is not initialized.
errc::not_supported	if the response is not chunked.

Referenced by chunk_length().

◆ try_close()

result< void > idfxx::http::client::try_close ( )

Closes the connection.

Returns: Success, or an error.

Referenced by close().

◆ try_fetch_headers()

result< int64_t > idfxx::http::client::try_fetch_headers ( )

Reads and processes response headers.

Must be called after open() (and any write() calls) before reading response body data.

Returns: The content length (-1 if chunked/unknown), or an error.

Referenced by fetch_headers().

◆ try_flush_response()

result< void > idfxx::http::client::try_flush_response ( )

Discards any remaining response data.

Returns: Success, or an error.

Referenced by flush_response().

◆ try_open() [1/2]

result< void > idfxx::http::client::try_open ( int write_len )

inline

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Definition at line 442 of file client.hpp.

References try_open().

Referenced by try_open().

◆ try_open() [2/2]

result< void > idfxx::http::client::try_open ( size_t write_len = 0 )

Opens a connection for streaming.

Opens the HTTP connection and sends request headers. If write_len is greater than zero, the connection is opened for writing that many bytes before reading the response.

Parameters

write_len Number of bytes to write (0 for read-only requests).

Returns: Success, or an error.

Return values

idfxx::errc::invalid_arg if write_len exceeds INT_MAX.

Referenced by open().

◆ try_perform()

result< void > idfxx::http::client::try_perform ( )

Performs a blocking HTTP request.

Sends the request and reads the complete response. Use event callbacks or the streaming API to process response data.

Returns: Success, or an error.

Referenced by perform().

◆ try_read() [1/2]

result< size_t > idfxx::http::client::try_read ( std::span< char > buf )

Reads response body data into a character buffer.

Parameters

buf	Buffer to read into.

Returns: Number of bytes read (0 at end of response), or an error.

◆ try_read() [2/2]

result< size_t > idfxx::http::client::try_read ( std::span< uint8_t > buf )

Reads response body data.

Parameters

buf	Buffer to read into.

Returns: Number of bytes read (0 at end of response), or an error.

Referenced by read(), and read().

◆ try_set_redirection()

result< void > idfxx::http::client::try_set_redirection ( )

Applies the current redirect URL.

Sets the client URL to the redirect target from the Location header. Typically called from a redirect event callback when automatic redirect is disabled.

Returns: Success, or an error.

Referenced by set_redirection().

◆ try_set_url()

result< void > idfxx::http::client::try_set_url ( std::string_view url )

Sets the request URL.

Parameters

url	The URL string.

Returns: Success, or an error.

Referenced by set_url().

◆ try_write() [1/2]

result< size_t > idfxx::http::client::try_write ( std::span< const uint8_t > data )

Writes data to the open connection.

Parameters

data	Binary data to write.

Returns: Number of bytes written, or an error.

Referenced by write(), and write().

◆ try_write() [2/2]

result< size_t > idfxx::http::client::try_write ( std::string_view data )

Writes string data to the open connection.

Parameters

data	String data to write.

Returns: Number of bytes written, or an error.

◆ write() [1/2]

size_t idfxx::http::client::write ( std::span< const uint8_t > data )

inline

Writes data to the open connection.

Parameters

data	Binary data to write.

Returns: Number of bytes written.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 367 of file client.hpp.

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

◆ write() [2/2]

size_t idfxx::http::client::write ( std::string_view data )

inline

Writes string data to the open connection.

Parameters

data	String data to write.

Returns: Number of bytes written.

Note: Only available when CONFIG_COMPILER_CXX_EXCEPTIONS is enabled in menuconfig.

Exceptions

std::system_error on failure.

Definition at line 377 of file client.hpp.

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

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

idfxx_http_client/include/idfxx/http/client.hpp

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

◆ errc

◆ state

Constructor & Destructor Documentation

◆ client() [1/3]

◆ ~client()

◆ client() [2/3]

◆ client() [3/3]

Member Function Documentation

◆ cancel_request()

◆ chunk_length()

◆ close()

◆ content_length()

◆ delete_header()

◆ fetch_headers()

◆ flush_response()

◆ get_header()

◆ get_state()

◆ get_url()

◆ idf_handle()

◆ is_chunked_response()

◆ make()

◆ open() [1/2]

◆ open() [2/2]

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ perform()

◆ read() [1/2]

◆ read() [2/2]

◆ reset_redirect_counter()

◆ set_auth_type()

◆ set_header()

◆ set_method()

◆ set_password()

◆ set_post_field()

◆ set_redirection()

◆ set_timeout()

◆ set_url()

◆ set_username()

◆ status_code()

◆ try_cancel_request()

◆ try_chunk_length()

◆ try_close()

◆ try_fetch_headers()

◆ try_flush_response()

◆ try_open() [1/2]

◆ try_open() [2/2]

◆ try_perform()

◆ try_read() [1/2]

◆ try_read() [2/2]

◆ try_set_redirection()

◆ try_set_url()

◆ try_write() [1/2]

◆ try_write() [2/2]

◆ write() [1/2]

◆ write() [2/2]