Synchronous HTTP client. More...

#include <kaycxx/http/client.hpp>

Public Member Functions
	client ()
	Creates an HTTP client.
	client (request_options default_options)
	Creates an HTTP client with default request options.
	~client ()
	Destroys the HTTP client.
	client (const client &)=delete
client &	operator= (const client &)=delete
	client (client &&other) noexcept
	Moves an HTTP client.
client &	operator= (client &&other) noexcept
	Move-assigns an HTTP client.
buffered_response	request (std::string_view method, std::string_view url, const request_options &options={})
	Sends an HTTP request and buffers the response body.
buffered_response	request (std::string_view method, std::string_view url, request_body body, const request_options &options={})
	Sends an HTTP request with a body and buffers the response body.
streamed_response	request (std::string_view method, std::string_view url, response_body output, const request_options &options={})
	Sends an HTTP request and streams the successful response body to an output stream.
streamed_response	request (std::string_view method, std::string_view url, request_body body, response_body output, const request_options &options={})
	Sends an HTTP request with a body and streams the successful response body to an output stream.
buffered_response	get (std::string_view url, const request_options &options={})
	Sends a GET request and buffers the response body.
buffered_response	get (std::string_view url, request_body body, const request_options &options={})
	Sends a GET request with a body and buffers the response body.
streamed_response	get (std::string_view url, response_body output, const request_options &options={})
	Sends a GET request and streams the successful response body to an output stream.
streamed_response	get (std::string_view url, request_body body, response_body output, const request_options &options={})
	Sends a GET request with a body and streams the successful response body to an output stream.
buffered_response	post (std::string_view url, const request_options &options={})
	Sends a POST request and buffers the response body.
buffered_response	post (std::string_view url, request_body body, const request_options &options={})
	Sends a POST request with a body and buffers the response body.
streamed_response	post (std::string_view url, response_body output, const request_options &options={})
	Sends a POST request and streams the successful response body to an output stream.
streamed_response	post (std::string_view url, request_body body, response_body output, const request_options &options={})
	Sends a POST request with a body and streams the successful response body to an output stream.
buffered_response	put (std::string_view url, const request_options &options={})
	Sends a PUT request and buffers the response body.
buffered_response	put (std::string_view url, request_body body, const request_options &options={})
	Sends a PUT request with a body and buffers the response body.
streamed_response	put (std::string_view url, response_body output, const request_options &options={})
	Sends a PUT request and streams the successful response body to an output stream.
streamed_response	put (std::string_view url, request_body body, response_body output, const request_options &options={})
	Sends a PUT request with a body and streams the successful response body to an output stream.
buffered_response	del (std::string_view url, const request_options &options={})
	Sends a DELETE request and buffers the response body.
buffered_response	del (std::string_view url, request_body body, const request_options &options={})
	Sends a DELETE request with a body and buffers the response body.
streamed_response	del (std::string_view url, response_body output, const request_options &options={})
	Sends a DELETE request and streams the successful response body to an output stream.
streamed_response	del (std::string_view url, request_body body, response_body output, const request_options &options={})
	Sends a DELETE request with a body and streams the successful response body to an output stream.

Detailed Description

Synchronous HTTP client.

A client retains its backend handle so sequential requests can reuse connections. A client instance must not be used concurrently from multiple threads. Starting another request reentrantly on the same instance throws error. A moved-from client can be destroyed or move-assigned; attempting to send a request with it throws error.

Constructor & Destructor Documentation

◆ client() [1/3]

kaycxx::http::client::client ( )

Creates an HTTP client.

Exceptions

error When libcurl cannot be initialized or its easy handle cannot be created.

◆ client() [2/3]

kaycxx::http::client::client ( request_options default_options )

explicit

Creates an HTTP client with default request options.

Request-specific options override these defaults. Headers are merged by ASCII case-insensitive name.

Parameters

default_options Default options for requests sent by this client.

Exceptions

error When libcurl cannot be initialized or its easy handle cannot be created.

◆ client() [3/3]

kaycxx::http::client::client ( client && other )

noexcept

Moves an HTTP client.

Parameters

other HTTP client to move from.

Member Function Documentation

◆ del() [1/4]

buffered_response kaycxx::http::client::del	(	std::string_view	url,
		const request_options &	options = {} )

nodiscard

Sends a DELETE request and buffers the response body.

Parameters

url	Request URL.
options	Request options.

Returns: Successful HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.

◆ del() [2/4]

buffered_response kaycxx::http::client::del	(	std::string_view	url,
		request_body	body,
		const request_options &	options = {} )

nodiscard

Sends a DELETE request with a body and buffers the response body.

Parameters

url	Request URL.
body	Request body.
options	Request options.

Returns: Successful HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.
nlohmann::json::type_error	When a JSON body cannot be serialized.

◆ del() [3/4]

streamed_response kaycxx::http::client::del	(	std::string_view	url,
		request_body	body,
		response_body	output,
		const request_options &	options = {} )

nodiscard

Sends a DELETE request with a body and streams the successful response body to an output stream.

Parameters

url	Request URL.
body	Request body.
output	Output stream receiving the successful response body.
options	Request options.

Returns: Successful streamed HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.
nlohmann::json::type_error	When a JSON body cannot be serialized.

◆ del() [4/4]

streamed_response kaycxx::http::client::del	(	std::string_view	url,
		response_body	output,
		const request_options &	options = {} )

nodiscard

Sends a DELETE request and streams the successful response body to an output stream.

Parameters

url	Request URL.
output	Output stream receiving the successful response body.
options	Request options.

Returns: Successful streamed HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.

◆ get() [1/4]

buffered_response kaycxx::http::client::get	(	std::string_view	url,
		const request_options &	options = {} )

nodiscard

Sends a GET request and buffers the response body.

Parameters

url	Request URL.
options	Request options.

Returns: Successful HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.

◆ get() [2/4]

buffered_response kaycxx::http::client::get	(	std::string_view	url,
		request_body	body,
		const request_options &	options = {} )

nodiscard

Sends a GET request with a body and buffers the response body.

Parameters

url	Request URL.
body	Request body.
options	Request options.

Returns: Successful HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.
nlohmann::json::type_error	When a JSON body cannot be serialized.

◆ get() [3/4]

streamed_response kaycxx::http::client::get	(	std::string_view	url,
		request_body	body,
		response_body	output,
		const request_options &	options = {} )

nodiscard

Sends a GET request with a body and streams the successful response body to an output stream.

Parameters

url	Request URL.
body	Request body.
output	Output stream receiving the successful response body.
options	Request options.

Returns: Successful streamed HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.
nlohmann::json::type_error	When a JSON body cannot be serialized.

◆ get() [4/4]

streamed_response kaycxx::http::client::get	(	std::string_view	url,
		response_body	output,
		const request_options &	options = {} )

nodiscard

Sends a GET request and streams the successful response body to an output stream.

Parameters

url	Request URL.
output	Output stream receiving the successful response body.
options	Request options.

Returns: Successful streamed HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.

◆ operator=()

client & kaycxx::http::client::operator= ( client && other )

noexcept

Move-assigns an HTTP client.

Parameters

other HTTP client to move from.

Returns: Reference to this HTTP client.

◆ post() [1/4]

buffered_response kaycxx::http::client::post	(	std::string_view	url,
		const request_options &	options = {} )

nodiscard

Sends a POST request and buffers the response body.

Parameters

url	Request URL.
options	Request options.

Returns: Successful HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.

◆ post() [2/4]

buffered_response kaycxx::http::client::post	(	std::string_view	url,
		request_body	body,
		const request_options &	options = {} )

nodiscard

Sends a POST request with a body and buffers the response body.

Parameters

url	Request URL.
body	Request body.
options	Request options.

Returns: Successful HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.
nlohmann::json::type_error	When a JSON body cannot be serialized.

◆ post() [3/4]

streamed_response kaycxx::http::client::post	(	std::string_view	url,
		request_body	body,
		response_body	output,
		const request_options &	options = {} )

nodiscard

Sends a POST request with a body and streams the successful response body to an output stream.

Parameters

url	Request URL.
body	Request body.
output	Output stream receiving the successful response body.
options	Request options.

Returns: Successful streamed HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.
nlohmann::json::type_error	When a JSON body cannot be serialized.

◆ post() [4/4]

streamed_response kaycxx::http::client::post	(	std::string_view	url,
		response_body	output,
		const request_options &	options = {} )

nodiscard

Sends a POST request and streams the successful response body to an output stream.

Parameters

url	Request URL.
output	Output stream receiving the successful response body.
options	Request options.

Returns: Successful streamed HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.

◆ put() [1/4]

buffered_response kaycxx::http::client::put	(	std::string_view	url,
		const request_options &	options = {} )

nodiscard

Sends a PUT request and buffers the response body.

Parameters

url	Request URL.
options	Request options.

Returns: Successful HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.

◆ put() [2/4]

buffered_response kaycxx::http::client::put	(	std::string_view	url,
		request_body	body,
		const request_options &	options = {} )

nodiscard

Sends a PUT request with a body and buffers the response body.

Parameters

url	Request URL.
body	Request body.
options	Request options.

Returns: Successful HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.
nlohmann::json::type_error	When a JSON body cannot be serialized.

◆ put() [3/4]

streamed_response kaycxx::http::client::put	(	std::string_view	url,
		request_body	body,
		response_body	output,
		const request_options &	options = {} )

nodiscard

Sends a PUT request with a body and streams the successful response body to an output stream.

Parameters

url	Request URL.
body	Request body.
output	Output stream receiving the successful response body.
options	Request options.

Returns: Successful streamed HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.
nlohmann::json::type_error	When a JSON body cannot be serialized.

◆ put() [4/4]

streamed_response kaycxx::http::client::put	(	std::string_view	url,
		response_body	output,
		const request_options &	options = {} )

nodiscard

Sends a PUT request and streams the successful response body to an output stream.

Parameters

url	Request URL.
output	Output stream receiving the successful response body.
options	Request options.

Returns: Successful streamed HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.

◆ request() [1/4]

buffered_response kaycxx::http::client::request	(	std::string_view	method,
		std::string_view	url,
		const request_options &	options = {} )

nodiscard

Sends an HTTP request and buffers the response body.

Parameters

method	HTTP request method.
url	Request URL.
options	Request options.

Returns: Successful HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.

◆ request() [2/4]

buffered_response kaycxx::http::client::request	(	std::string_view	method,
		std::string_view	url,
		request_body	body,
		const request_options &	options = {} )

nodiscard

Sends an HTTP request with a body and buffers the response body.

Parameters

method	HTTP request method.
url	Request URL.
body	Request body.
options	Request options.

Returns: Successful HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.
nlohmann::json::type_error	When a JSON body cannot be serialized.

◆ request() [3/4]

streamed_response kaycxx::http::client::request	(	std::string_view	method,
		std::string_view	url,
		request_body	body,
		response_body	output,
		const request_options &	options = {} )

nodiscard

Sends an HTTP request with a body and streams the successful response body to an output stream.

Error response bodies are retained by the thrown response error and are not written to the output stream. A transport or output error can leave a partial successful response in the output stream.

Parameters

method	HTTP request method.
url	Request URL.
body	Request body.
output	Output stream receiving the successful response body.
options	Request options.

Returns: Successful streamed HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.
nlohmann::json::type_error	When a JSON body cannot be serialized.

◆ request() [4/4]

streamed_response kaycxx::http::client::request	(	std::string_view	method,
		std::string_view	url,
		response_body	output,
		const request_options &	options = {} )

nodiscard

Sends an HTTP request and streams the successful response body to an output stream.

Error response bodies are retained by the thrown response error and are not written to the output stream. A transport or output error can leave a partial successful response in the output stream.

Parameters

method	HTTP request method.
url	Request URL.
output	Output stream receiving the successful response body.
options	Request options.

Returns: Successful streamed HTTP response.

Exceptions

response_error	When the server returns a status code outside the range 200 to 299.
error	When the request cannot be configured or performed.

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

kaycxx/http/client.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ client() [1/3]

◆ client() [2/3]

◆ client() [3/3]

Member Function Documentation

◆ del() [1/4]

◆ del() [2/4]

◆ del() [3/4]

◆ del() [4/4]

◆ get() [1/4]

◆ get() [2/4]

◆ get() [3/4]

◆ get() [4/4]

◆ operator=()

◆ post() [1/4]

◆ post() [2/4]

◆ post() [3/4]

◆ post() [4/4]

◆ put() [1/4]

◆ put() [2/4]

◆ put() [3/4]

◆ put() [4/4]

◆ request() [1/4]

◆ request() [2/4]

◆ request() [3/4]

◆ request() [4/4]