kvikio::CurlHandle Class Reference

Representation of a curl easy handle pointer and its operations. More...

#include <libcurl.hpp>

Public Member Functions
	CurlHandle (LibCurl::UniqueHandlePtr handle, std::string source_file, std::string source_line)
	Construct a new curl handle. More...
	CurlHandle (CurlHandle const &)=delete
	CurlHandle support is not movable or copyable.
CurlHandle &	operator= (CurlHandle const &)=delete
	CurlHandle (CurlHandle &&o)=delete
CurlHandle &	operator= (CurlHandle &&o)=delete
CURL *	handle () noexcept
	Get the underlying curl easy handle pointer.
std::string	error_message () const
	Get the most recent error message libcurl recorded for this handle. More...
void	clear_error_message () noexcept
	Discard the recorded error message.
template<typename VAL >
void	setopt (CURLoption option, VAL value)
	Set option for the curl handle. More...
void	perform ()
	Perform a blocking network transfer using previously set options. More...
void	perform (std::function< void()> const &on_retry)
	Perform a blocking network transfer, and if the transfer fails, execute an on_retry callback to roll back to pre-transfer state. More...
template<typename OUTPUT >
void	getinfo (CURLINFO info, OUTPUT *output)
	Extract information from a curl handle. More...

Detailed Description

Representation of a curl easy handle pointer and its operations.

An instance is given a LibCurl::UniqueHandlePtr on creation, which is later retained on destruction.

Definition at line 80 of file libcurl.hpp.

Constructor & Destructor Documentation

CurlHandle()

kvikio::CurlHandle::CurlHandle	(	LibCurl::UniqueHandlePtr	handle,
		std::string	source_file,
		std::string	source_line
	)

Construct a new curl handle.

Typically, do not call this directly instead use the create_curl_handle() macro.

Parameters

handle	An unused curl easy handle pointer, which is retained on destruction.
source_file	Path of source file of the caller (for error messages).
source_line	Line of source file of the caller (for error messages).

Member Function Documentation

error_message()

std::string kvikio::CurlHandle::error_message

(

)

const

Get the most recent error message libcurl recorded for this handle.

The handle is created with CURLOPT_ERRORBUFFER, so after a failed transfer this holds a human-readable description that is usually more specific than curl_easy_strerror, for example "The requested URL returned error: 403". The buffer is empty when libcurl recorded no message.

Returns

The recorded error message, or an empty string if none was recorded.

getinfo()

template<typename OUTPUT >

void kvikio::CurlHandle::getinfo ( CURLINFO  info, OUTPUT *  output  )

inline

Extract information from a curl handle.

See https://curl.se/libcurl/c/curl_easy_getinfo.html for available options.

Template Parameters

OUTPUT

The type of the output.

Parameters

output

The output, which is used as-is: curl_easy_getinfo(..., output).

Definition at line 180 of file libcurl.hpp.

perform() [1/2]

void kvikio::CurlHandle::perform

(

)

Perform a blocking network transfer using previously set options.

Transient failures are retried with exponential backoff, as configured by defaults::http_max_attempts() and defaults::http_status_codes().

See https://curl.se/libcurl/c/curl_easy_perform.html.

Exceptions

std::runtime_error

if the transfer fails with a non-retryable error, or if it exhausts its attempt budget.

perform() [2/2]

void kvikio::CurlHandle::perform

(

std::function< void()> const &

on_retry

)

Perform a blocking network transfer, and if the transfer fails, execute an on_retry callback to roll back to pre-transfer state.

Parameters

on_retry

Invoked before each retried attempt, to roll back to the pre-transfer state.

Exceptions

std::runtime_error

if the transfer fails with a non-retryable error, or if it exhausts its attempt budget.

setopt()

template<typename VAL >

void kvikio::CurlHandle::setopt ( CURLoption  option, VAL  value  )

inline

Set option for the curl handle.

See https://curl.se/libcurl/c/curl_easy_setopt.html for available options.

Template Parameters

VAL	The type of the value.

Parameters

option

The curl option to set.

Definition at line 136 of file libcurl.hpp.

---

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

• libcurl.hpp