curl::Easy_ref_t Class Reference

Collaboration diagram for curl::Easy_ref_t:

Classes
class	Exception
class	NotBuiltIn_error
class	ProtocolInternal_error

Public Types
enum	header_option { header_option::unspecified, header_option::unified, separate }
enum	code {   ok = 0, unsupported_protocol, url_malformat, cannot_resolve_proxy,   cannot_resolve_host, cannot_connect, remote_access_denied, writeback_error,   upload_failure, timedout, aborted_by_callback, too_many_redirects,   ssl_pinned_pubkey_mismatch }
enum	PauseOptions { PauseOptions::recv = 1 << 0, PauseOptions::send = 1 << 2, PauseOptions::all = recv | send, PauseOptions::cont = 0 }
using	writeback_t = std::size_t(*)(char *buffer, std::size_t _, std::size_t size, void *userp)
using	readback_t = std::size_t(*)(char *buffer, std::size_t size, std::size_t nitems, void *userp)
using	perform_ret_t = Ret_except< code, std::bad_alloc, std::invalid_argument, std::length_error, Exception, Recursive_api_call_Exception, NotBuiltIn_error, ProtocolInternal_error >

Public Member Functions
void	set_verbose (FILE *stderr_stream_arg) noexcept
void	set_error_buffer (char *error_buffer) noexcept
void	set_private (void *userp) noexcept
void *	get_private () const noexcept
void	set_writeback (writeback_t writeback, void *userp) noexcept
void	set_url (const Url_ref_t &url) noexcept
auto	set_url (const char *url) noexcept -> Ret_except< void, std::bad_alloc >
auto	pin_publickey (const char *pubkey) -> Ret_except< void, std::bad_alloc, curl::NotBuiltIn_error >
auto	set_cookie (const char *cookies) noexcept -> Ret_except< void, std::bad_alloc, curl::NotBuiltIn_error >
auto	set_cookiefile (const char *cookie_filename) noexcept -> Ret_except< void, curl::NotBuiltIn_error >
auto	set_cookiejar (const char *cookie_filename) noexcept -> Ret_except< void, std::bad_alloc, curl::NotBuiltIn_error >
auto	set_cookielist (const char *cookie) noexcept -> Ret_except< void, std::bad_alloc, curl::NotBuiltIn_error >
void	start_new_cookie_session () noexcept
auto	erase_all_cookies_in_mem () noexcept -> Ret_except< void, std::bad_alloc, curl::NotBuiltIn_error >
auto	erase_all_session_cookies_in_mem () noexcept -> Ret_except< void, std::bad_alloc, curl::NotBuiltIn_error >
auto	flush_cookies_to_jar () noexcept -> Ret_except< void, std::bad_alloc, curl::NotBuiltIn_error >
auto	reload_cookies_from_file () noexcept -> Ret_except< void, std::bad_alloc, curl::NotBuiltIn_error >
void	set_follow_location (long redir) noexcept
auto	set_useragent (const char *useragent) noexcept -> Ret_except< void, std::bad_alloc >
auto	set_encoding (const char *encoding) noexcept -> Ret_except< void, std::bad_alloc >
auto	set_interface (const char *value) noexcept -> Ret_except< void, std::bad_alloc >
auto	set_ip_addr_only (const char *ip_addr) noexcept -> Ret_except< void, std::bad_alloc >
void	set_timeout (unsigned long timeout) noexcept
void	set_http_header (const utils::slist &l, header_option option=header_option::unspecified) noexcept
void	set_nobody (bool enable) noexcept
void	request_get () noexcept
void	request_post (const void *data, std::size_t len) noexcept
void	request_post (readback_t readback, void *userp, std::size_t len=-1) noexcept
auto	perform () noexcept -> perform_ret_t
auto	set_pause (PauseOptions option) noexcept -> Ret_except< code, std::bad_alloc, Exception >
long	get_response_code () const noexcept
std::size_t	getinfo_sizeof_request () const noexcept
std::size_t	getinfo_sizeof_uploaded () const noexcept
std::size_t	getinfo_sizeof_response_header () const noexcept
std::size_t	getinfo_sizeof_response_body () const noexcept
std::size_t	getinfo_transfer_time () const noexcept
auto	getinfo_redirect_url () const noexcept -> const char *
auto	getinfo_effective_url () const noexcept -> const char *
auto	getinfo_cookie_list () const noexcept -> Ret_except< utils::slist, curl::NotBuiltIn_error >
auto	get_active_socket () const noexcept -> curl_socket_t
template<class String >
auto	set_readall_writeback (String &response) noexcept
template<class String , class size_type >
auto	set_read_writeback (std::pair< String, size_type > &arg) noexcept
void	setup_establish_connection_only () noexcept

Static Public Member Functions
static std::size_t	get_error_buffer_size () noexcept

Public Attributes
char *	curl_easy = nullptr
friend	Multi_t

Static Protected Member Functions
static auto	check_perform (long code, const char *fname) noexcept -> perform_ret_t

Detailed Description

Examples

curl_easy_get.cc, curl_multi_poll.cc, curl_multi_poll2.cc, curl_multi_socket_action_epoll.cc, curl_multi_socket_action_event.cc, curl_multi_socket_action_uv.cc, and curl_share.cc.

Definition at line 53 of file curl_easy.hpp.

Member Typedef Documentation

writeback_t

using curl::Easy_ref_t::writeback_t = std::size_t (*)(char *buffer, std::size_t _, std::size_t size, void *userp)

Parameters

buffer	not null-terminated
size	at most CURL_MAX_WRITE_SIZE

@ return if less than size, then it will singal an err cond to libcurl.
This will cause the transfer to get aborted and the libcurl function used will return code::writeback_error.
If curl_t::has_pause_support() == true, and CURL_WRITEFUNC_PAUSE is returned, it will cause transfer to be paused. See curl_easy_pause for more details.

It would be undefined behavior to call any easy member function in writeback.

Definition at line 145 of file curl_easy.hpp.

readback_t

using curl::Easy_ref_t::readback_t = std::size_t (*)(char *buffer, std::size_t size, std::size_t nitems, void *userp)

The length of buffer is size * nitems.

Returns

bytes writen to the buffer.
0 to signal end-of-file to the library and cause it to stop the current transfer.
CURL_READFUNC_ABORT (requires curl_t::has_readfunc_abort_support()) to stop immediately, result code::aborted_by_callback.
If curl_t::has_pause_support() == true, and CURL_READFUNC_PAUSE is returned, it would cause reading from this connection to pause. See curl_easy_pause for further details.
Bugs: when doing TFTP uploads, you must return the exact amount of data that the callback wants, or it will be considered the final packet by the server end and the transfer will end there.

If you stop the current transfer by returning 0 "pre-maturely" (i.e before the server expected it, like when you've said you will upload N bytes and you upload less than N bytes), you may experience that the server "hangs" waiting for the rest of the data that won't come.

Definition at line 539 of file curl_easy.hpp.

Member Enumeration Documentation

header_option

enum curl::Easy_ref_t::header_option

strong

Enumerator
unspecified	If unspecified is passed to set_http_header, then the previous header_option (or default) will be used. If curl_t::has_header_option_support() == false, then it is default to unified. Before 7.42.1, default is unified. After 7.42.1, default is separate.
unified	The following options only take effect when curl_t::has_header_option_support() == true.

Definition at line 447 of file curl_easy.hpp.

                             {
        unspecified,
        unified, // header specified with set_http_header will also be used for proxy
        separate, // reverse of unified
    };

code

enum curl::Easy_ref_t::code

strong

Precondition

curl_t::has_protocol(protocol you use in url)

Exceptions

NotSupported_error,std::bad_alloc

or any exception defined in this class

Definition at line 551 of file curl_easy.hpp.

                    {
        ok = 0,
        unsupported_protocol,
        url_malformat,
        cannot_resolve_proxy,
        cannot_resolve_host,
        cannot_connect, // Cannot connect to host or proxy
        remote_access_denied,
        writeback_error,
        upload_failure, // Failed starting the upload
        timedout,
        aborted_by_callback, // If readback return CURL_READFUNC_ABORT.
        too_many_redirects, 
        ssl_pinned_pubkey_mismatch,
    };

PauseOptions

enum curl::Easy_ref_t::PauseOptions

strong

Enumerator
recv	Pause receiving data. There will be no data received on this connection until this function is called again without this bit set. Thus, the writeback won't be called.
send	Pause sending data. There will be no data sent on this connection until this function is called again without this bit set. Thus, the readback won't be called/the data registered with request_post won't be copied.
all	Convenience define that pauses both directions.
cont	Convenience define that unpauses both directions.

Definition at line 572 of file curl_easy.hpp.

                            {
        recv = 1 << 0,
        send = 1 << 2, // Make value of pause_send the same as stock libcurl
        all = recv | send, 
        cont = 0,
    };

Member Function Documentation

set_verbose()

void curl::Easy_ref_t::set_verbose ( FILE *  stderr_stream_arg )

noexcept

Parameters

stderr_stream_arg

if not null, enable verbose mode and print them onto stderr_stream_arg.

Definition at line 64 of file curl_easy.cc.

{
    if (stderr_stream_arg) {
        curl_easy_setopt(curl_easy, CURLOPT_STDERR, stderr_stream_arg);
        curl_easy_setopt(curl_easy, CURLOPT_VERBOSE, 1L);
    }
}

get_error_buffer_size()

std::size_t curl::Easy_ref_t::get_error_buffer_size ( )

staticnoexcept

Minimum length for error buffer.

Definition at line 71 of file curl_easy.cc.

{
    return CURL_ERROR_SIZE;
}

set_error_buffer()

void curl::Easy_ref_t::set_error_buffer ( char *  error_buffer )

noexcept

Parameters

buffer

either nullptr to disable error buffer, or at least get_error_buffer_size() big.

The error buffer must be kept around until call set_error_buffer again or curl::Easy_t is destroyed.

The error buffer is only set if ProtocolInternal_error is thrown.

Definition at line 75 of file curl_easy.cc.

{
    curl_easy_setopt(curl_easy, CURLOPT_ERRORBUFFER, error_buffer);
}

set_private()

void curl::Easy_ref_t::set_private ( void *  userp )

noexcept

Precondition

curl_t::has_private_ptr_support()

Parameters

userp

any user-defined pointer. Default to nullptr.

Definition at line 80 of file curl_easy.cc.

{
    curl_easy_setopt(curl_easy, CURLOPT_PRIVATE, userp);
}

get_private()

void * curl::Easy_ref_t::get_private ( ) const

noexcept

Precondition

curl_t::has_private_ptr_support()

Returns

pointer set via set_private or nullptr if not set at all.

Definition at line 84 of file curl_easy.cc.

{
    char *userp;
    curl_easy_getinfo(curl_easy, CURLINFO_PRIVATE, &userp);
    return userp;
}

set_writeback()

void curl::Easy_ref_t::set_writeback ( writeback_t  writeback, void *  userp  )

noexcept

By default, writeback == std::fwrite, userp == stdout

Definition at line 91 of file curl_easy.cc.

{
    curl_easy_setopt(curl_easy, CURLOPT_WRITEFUNCTION, writeback);
    curl_easy_setopt(curl_easy, CURLOPT_WRITEDATA, userp);
}

Here is the caller graph for this function:

set_url() [1/2]

void curl::Easy_ref_t::set_url ( const Url_ref_t &  url )

noexcept

Precondition

curl_t::has_CURLU()

Parameters

url	content of it must not be changed during call to perform(), but can be changed once it is finished.

Examples

curl_easy_get.cc.

Definition at line 97 of file curl_easy.cc.

{
    curl_easy_setopt(curl_easy, CURLOPT_CURLU, url.url);
}

set_url() [2/2]

auto curl::Easy_ref_t::set_url ( const char *  url ) -> Ret_except<void, std::bad_alloc>

noexcept

Parameters

url	would be dupped, thus it can be freed up after this function call.

Definition at line 101 of file curl_easy.cc.

{
    CHECK_OOM(curl_easy_setopt(curl_easy, CURLOPT_URL, url));
    return {};
}

pin_publickey()

auto curl::Easy_ref_t::pin_publickey

(

const char *

pubkey

)

-> Ret_except<void, std::bad_alloc, curl::NotBuiltIn_error>

Precondition

url set to use TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc && curl_t::has_protocol(protolcol)

Parameters

pubkey

null-terminated string. The string can be the file name of your pinned public key. The file format expected is "PEM" or "DER". The string can also be any number of base64 encoded sha256 hashes preceded by "sha256//" and separated by ";". The application does not have to keep the string around after setting this option.

Returns

note that whether this is supported depend on:

• ssl lib
• libcurl version
• whether pubkey is a path to file or sha256.

When negotiating a TLS or SSL connection, the server sends a certificate indicating its identity. A public key is extracted from this certificate and if it does not exactly match the public key provided to this option, curl will abort the connection before sending or receiving any data.

On mismatch, code::ssl_pinned_pubkey_mismatch is returned.

Definition at line 107 of file curl_easy.cc.

{
    auto result = curl_easy_setopt(curl_easy, CURLOPT_PINNEDPUBLICKEY, pubkey);
    if (result == CURLE_OUT_OF_MEMORY)
        return {std::bad_alloc{}};
    else if (result == CURLE_UNKNOWN_OPTION)
        return {curl::NotBuiltIn_error{"pining public key is not supported by this version of libcurl "
                                       "on this specific ssl version"}};
    else
        return {};
}

set_cookie()

auto curl::Easy_ref_t::set_cookie ( const char *  cookies ) -> Ret_except<void, std::bad_alloc, curl::NotBuiltIn_error>

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http")

Parameters

cookies

null-terminated string, in format "name1=content1; name2=content2;" This string will be strdup-ed and override previous call. This is defaulted to nullptr.

Returns

note that libcurl can be built with cookies disabled, thus this library can return exception curl::NotBuiltIn_error.

This option sets the cookie header explicitly in the outgoing request(s).
If multiple requests are done due to authentication, followed redirections or similar, they will all get this cookie passed on.

The cookies set by this option are separate from the internal cookie storage held by the cookie engine and will not be modified by it.

If you enable the cookie engine and either you've imported a cookie of the same name (e.g. 'foo') or the server has set one, it will have no effect on the cookies you set here.

A request to the server will send both the 'foo' held by the cookie engine and the 'foo' held by this option.
To set a cookie that is instead held by the cookie engine and can be modified by the server use set_cookielist.

This option will not enable the cookie engine. Use set_cookiefile or set_cookiejar to enable parsing and sending cookies automatically.

Definition at line 120 of file curl_easy.cc.

{
    auto code = curl_easy_setopt(curl_easy, CURLOPT_COOKIE, cookies);
    if (code == CURLE_UNKNOWN_OPTION)
        return curl::NotBuiltIn_error{"cookies not supported"};
    else if (code == CURLE_OUT_OF_MEMORY)
        return {std::bad_alloc{}};
 
    return {};
}

set_cookiefile()

auto curl::Easy_ref_t::set_cookiefile ( const char *  cookie_filename ) -> Ret_except<void, curl::NotBuiltIn_error>

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http")

Parameters

cookie_filename

null-terminte string for the filename of the cookie file; "" to enable cookie engine without any initial cookies; "-" to read the cookie from stdin; Does not have to keep around after this call. This is default to nullptr.

Returns

note that libcurl can be built with cookies disabled, thus this library can return exception curl::NotBuiltIn_error.

The cookie data can be in either the old Netscape / Mozilla cookie data format or just regular HTTP headers (Set-Cookie style) dumped to a file.

It enables the cookie engine, making libcurl parse response and send cookies on subsequent requests with this handle.

This function can be used with set_cookielist.

It only reads cookies right before a transfer is started.
To make libcurl write cookies to file, see set_cookiejar.

Exercise caution if you are using this option and multiple transfers may occur due to redirect:

If you use the Set-Cookie format: "name1=content1; name2=content2;" and don't specify a domain then the cookie is sent for any domain (even after redirects are followed) and cannot be modified by a server-set cookie.

If a server sets a cookie of the same name then both will be sent on a future transfer to that server, likely not what you intended. To address these issues set a domain in Set-Cookie HTTP header (doing that will include sub-domains) or use the Netscape format:

char *my_cookie =
  "example.com"    // Hostname
  "\t" "FALSE"     // Include subdomains
  "\t" "/"         // Path
  "\t" "FALSE"     // Secure
  "\t" "0"         // Expiry in epoch time format. 0 == Session
  "\t" "foo"       // Name
  "\t" "bar";      // Value

If you call this function multiple times, you just add more files to read. Subsequent files will add more cookies.

Definition at line 131 of file curl_easy.cc.

{
    if (curl_easy_setopt(curl_easy, CURLOPT_COOKIEFILE, cookie_filename) == CURLE_UNKNOWN_OPTION)
        return {curl::NotBuiltIn_error{"cookies not supported"}};
    return {};
}

set_cookiejar()

auto curl::Easy_ref_t::set_cookiejar ( const char *  cookie_filename ) -> Ret_except<void, std::bad_alloc, curl::NotBuiltIn_error>

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http")

Parameters

cookie_filename

null-terminated string; "-" write cookies to stdout; Does not have to keep around after this call. This is default to nullptr.

Returns

note that libcurl can be built with cookies disabled, thus this library can return exception curl::NotBuiltIn_error.

This will make libcurl write all internally known cookies to the specified file when curl::Easy_t is destroyed.

If no cookies, then no file will be created.

Using this option also enables cookies for this session, so if you for example follow a location it will make matching cookies get sent accordingly.

Note that libcurl doesn't read any cookies from the cookie jar.
If you want to read cookies from a file, use set_cookiefile.

If the cookie jar file can't be created or written to, libcurl will not and cannot report an error for this.
Using set_verbose, set curl::stderr_stream to non-null before creating curl::Easy_t or CURLOPT_DEBUGFUNCTION will get a warning to display, but that is the only visible feedback you get about this possibly lethal situation.

Since 7.43.0 cookies that were imported in the Set-Cookie format without a domain name are not exported by this function.

Definition at line 138 of file curl_easy.cc.

{
    auto code = curl_easy_setopt(curl_easy, CURLOPT_COOKIEJAR, cookie_filename);
    if (code == CURLE_UNKNOWN_OPTION)
        return {curl::NotBuiltIn_error{"cookies not supported"}};
    else if (code == CURLE_OUT_OF_MEMORY)
        return {std::bad_alloc{}};
 
    return {};
}

set_cookielist()

auto curl::Easy_ref_t::set_cookielist ( const char *  cookie ) -> Ret_except<void, std::bad_alloc, curl::NotBuiltIn_error>

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http")

Parameters

cookie_filename

null-terminte string for the filename of the cookie file; Does not have to keep around after this call. This is default to nullptr.

Returns

note that libcurl can be built with cookies disabled, thus this library can return exception curl::NotBuiltIn_error.

The cookie will be immediately loaded, and this function can be mixed with set_cookiefile.

Such a cookie can be either a single line in Netscape / Mozilla format or just regular HTTP-style header (Set-Cookie: ...) format.

This will also enable the cookie engine and adds that single cookie to the internal cookie store.

Exercise caution if you are using this option and multiple transfers may occur due to redirect:

If you use the Set-Cookie format: "name1=content1; name2=content2;" and don't specify a domain then the cookie is sent for any domain (even after redirects are followed) and cannot be modified by a server-set cookie.

If a server sets a cookie of the same name then both will be sent on a future transfer to that server, likely not what you intended. To address these issues set a domain in Set-Cookie HTTP header (doing that will include sub-domains) or use the Netscape format:

char *my_cookie =
  "example.com"    // Hostname
  "\t" "FALSE"     // Include subdomains
  "\t" "/"         // Path
  "\t" "FALSE"     // Secure
  "\t" "0"         // Expiry in epoch time format. 0 == Session
  "\t" "foo"       // Name
  "\t" "bar";      // Value

Definition at line 149 of file curl_easy.cc.

{
    auto code = curl_easy_setopt(curl_easy, CURLOPT_COOKIELIST, cookie);
    if (code == CURLE_UNKNOWN_OPTION)
        return {curl::NotBuiltIn_error{"cookies not supported"}};
    else if (code == CURLE_OUT_OF_MEMORY)
        return {std::bad_alloc{}};
 
    return {};
}

Here is the caller graph for this function:

start_new_cookie_session()

void curl::Easy_ref_t::start_new_cookie_session ( )

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http")

It will force libcurl to ignore all cookies it is about to load that are "session cookies" from the previous session.

Session cookies are cookies without expiry date and they are meant to be alive and existing for this "session" only.

A "session" is usually defined in browser land for as long as you have your browser up, more or less.

By default, libcurl always stores and loads all cookies, independent if they are session cookies or not.

NOTE that cookie support can be removed in compile time of libcurl, there is no guarantee this would work.

Definition at line 160 of file curl_easy.cc.

{
    curl_easy_setopt(curl_easy, CURLOPT_COOKIESESSION, 1L);
}

erase_all_cookies_in_mem()

auto curl::Easy_ref_t::erase_all_cookies_in_mem ( ) -> Ret_except<void, std::bad_alloc, curl::NotBuiltIn_error>

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http") && curl_t::has_erase_all_cookies_in_mem_support().

Returns

note that libcurl can be built with cookies disabled, thus this library can return exception curl::NotBuiltIn_error.

Definition at line 164 of file curl_easy.cc.

{
    return set_cookielist("ALL");
}

Here is the call graph for this function:

erase_all_session_cookies_in_mem()

auto curl::Easy_ref_t::erase_all_session_cookies_in_mem ( ) -> Ret_except<void, std::bad_alloc, curl::NotBuiltIn_error>

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http") && curl_t::has_erase_all_session_cookies_in_mem_support()

Returns

note that libcurl can be built with cookies disabled, thus this library can return exception curl::NotBuiltIn_error.

Session cookies are cookies without expiry date and they are meant to be alive and existing for this "session" only.

A "session" is usually defined in browser land for as long as you have your browser up, more or less.

Definition at line 169 of file curl_easy.cc.

{
    return set_cookielist("SESS");
}

Here is the call graph for this function:

flush_cookies_to_jar()

auto curl::Easy_ref_t::flush_cookies_to_jar ( ) -> Ret_except<void, std::bad_alloc, curl::NotBuiltIn_error>

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http") && curl_t::has_flush_cookies_to_jar()

Returns

note that libcurl can be built with cookies disabled, thus this library can return exception curl::NotBuiltIn_error.

writes all known cookies to the file specified by set_cookiejar.

Definition at line 174 of file curl_easy.cc.

{
    return set_cookielist("FLUSH");
}

Here is the call graph for this function:

reload_cookies_from_file()

auto curl::Easy_ref_t::reload_cookies_from_file ( ) -> Ret_except<void, std::bad_alloc, curl::NotBuiltIn_error>

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http") && curl_t::has_reload_cookies_from_file()

Returns

note that libcurl can be built with cookies disabled, thus this library can return exception curl::NotBuiltIn_error.

loads all cookies from the files specified by set_cookiefile.

Definition at line 179 of file curl_easy.cc.

{
    return set_cookielist("RELOAD");
}

Here is the call graph for this function:

set_follow_location()

void curl::Easy_ref_t::set_follow_location ( long  redir )

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http")

Parameters

redir

set to 0 to disable redirection. set to -1 to allow infinite number of redirections. Other number enables redir number of redirections.

Definition at line 185 of file curl_easy.cc.

{
    if (redir != 0) {
        curl_easy_setopt(curl_easy, CURLOPT_FOLLOWLOCATION, 1L);
        curl_easy_setopt(curl_easy, CURLOPT_MAXREDIRS, redir);
    } else
        curl_easy_setopt(curl_easy, CURLOPT_FOLLOWLOCATION, 0L);
}

set_useragent()

auto curl::Easy_ref_t::set_useragent ( const char *  useragent ) -> Ret_except<void, std::bad_alloc>

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http")

Parameters

useragent

pass nullptr for no useragent (default)

Definition at line 194 of file curl_easy.cc.

{
    CHECK_OOM(curl_easy_setopt(curl_easy, CURLOPT_USERAGENT, useragent));
    return {};
}

set_encoding()

auto curl::Easy_ref_t::set_encoding ( const char *  encoding ) -> Ret_except<void, std::bad_alloc>

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http")

Parameters

encoding

"" for enable all (default); nullptr for disable all (including auto decompression).

Definition at line 199 of file curl_easy.cc.

{
    CHECK_OOM(curl_easy_setopt(curl_easy, CURLOPT_ACCEPT_ENCODING, encoding));
    return {};
}

set_interface()

auto curl::Easy_ref_t::set_interface ( const char *  value ) -> Ret_except<void, std::bad_alloc>

noexcept

Parameters

value

can be ipv4 or ipv6 address/hostname/interface. If it is nullptr, then set to whatever TCP stack find available (default).

Definition at line 205 of file curl_easy.cc.

{
    CHECK_OOM(curl_easy_setopt(curl_easy, CURLOPT_INTERFACE, value));
    return {};
}

Here is the caller graph for this function:

set_ip_addr_only()

auto curl::Easy_ref_t::set_ip_addr_only ( const char *  ip_addr ) -> Ret_except<void, std::bad_alloc>

noexcept

Precondition

curl_t::has_set_ip_addr_only_support()

Parameters

ip_addr

ipv4/ipv6 address If it is nullptr, then set to whatever TCP stack find available (default).

46 is the maximum length for ipv6 address represented in string.

Information retrieved from here.

Definition at line 210 of file curl_easy.cc.

{
    constexpr const auto buffer_size = 5 + 46;
    char buffer[buffer_size];
    std::snprintf(buffer, buffer_size, "host!%s", ip_addr);
 
    return set_interface(buffer);
}

Here is the call graph for this function:

set_timeout()

void curl::Easy_ref_t::set_timeout ( unsigned long  timeout )

noexcept

Parameters

timeout

in milliseconds. Set to 0 to disable (default); should be less than std::numeric_limits<long>::max().

Definition at line 226 of file curl_easy.cc.

{
    curl_easy_setopt(curl_easy, CURLOPT_TIMEOUT_MS, timeout);
}

set_http_header()

void curl::Easy_ref_t::set_http_header ( const utils::slist &  l, header_option  option = header_option::unspecified  )

noexcept

Precondition

url is set to use http(s)

Parameters

l	will not be copied, thus it is required to be kept around until another set_http_header is issued or this Easy_t is destroyed.

Must not be CRLF-terminated.

Parameters

option

control whether header set here will also sent to proxy

Example:

• Replace hedaer 'Accept:'

  utils::slist l; l.push_back("Accept: deflate"); easy.set_http_header(l);

• Remove header 'Accept:'

  easy.set_http_header(utils::slist{});

Starting in 7.58.0, libcurl will specifically prevent "Authorization:" headers from being sent to hosts other than the first used one, unless specifically permitted with the CURLOPT_UNRESTRICTED_AUTH option.

Starting in 7.64.0, libcurl will specifically prevent "Cookie:" headers from being sent to hosts other than the first used one, unless specifically permitted with the CURLOPT_UNRESTRICTED_AUTH option.

Definition at line 231 of file curl_easy.cc.

{
    curl_easy_setopt(curl_easy, CURLOPT_HTTPHEADER, static_cast<struct curl_slist*>(l.get_underlying_ptr()));
    if (option != header_option::unspecified) {
        long value;
        if (option == header_option::separate)
            value = CURLHEADER_SEPARATE;
        else
            value = CURLHEADER_UNIFIED;
 
        curl_easy_setopt(curl_easy, CURLOPT_HEADEROPT, value);
    }
}

Here is the call graph for this function:

set_nobody()

void curl::Easy_ref_t::set_nobody ( bool  enable )

noexcept

Parameters

enable

if true, then it would not request body data to be transfered; if false, then a normal request (default).

Definition at line 245 of file curl_easy.cc.

{
    curl_easy_setopt(curl_easy, CURLOPT_NOBODY, enable);
}

request_get()

void curl::Easy_ref_t::request_get ( )

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http")

This is the default for http, and would also set_nobody(false).

Definition at line 250 of file curl_easy.cc.

{
    curl_easy_setopt(curl_easy, CURLOPT_HTTPGET, 1L);
}

Here is the caller graph for this function:

request_post() [1/2]

void curl::Easy_ref_t::request_post ( const void *  data, std::size_t  len  )

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http")

Parameters

len	if set to -1, then libcurl would strlen(data) to determine its length.

The data pointed to is NOT copied by the library: as a consequence, it must be preserved by the calling application until the associated transfer finishes.

Definition at line 254 of file curl_easy.cc.

{
    curl_easy_setopt(curl_easy, CURLOPT_POSTFIELDSIZE_LARGE, len);
    curl_easy_setopt(curl_easy, CURLOPT_POSTFIELDS, data);
}

Here is the caller graph for this function:

request_post() [2/2]

void curl::Easy_ref_t::request_post ( readback_t  readback, void *  userp, std::size_t  len = -1  )

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http")

Parameters

len	optional. Set to -1 means length of data is not known ahead of time.

Definition at line 259 of file curl_easy.cc.

{
    request_post(nullptr, len);
 
    curl_easy_setopt(curl_easy, CURLOPT_READFUNCTION, readback);
    curl_easy_setopt(curl_easy, CURLOPT_READDATA, userp);
}

Here is the call graph for this function:

set_pause()

auto curl::Easy_ref_t::set_pause ( PauseOptions  option ) -> Ret_except<code, std::bad_alloc, Exception>

noexcept

Precondition

curl_t::has_pause_support() and there's an ongoing transfer

Returns

If no exception is thrown, then it is either code::ok or code::writeback_error.

The pausing of transfers does not work with protocols that work without network connectivity, like FILE://. Trying to pause such a transfer, in any direction, will cause problems in the worst case or an error in the best case.

Use of set_pause with multi_socket_action interface

Before libcurl 7.32.0, when a specific handle was unpaused with this function, there was no particular forced rechecking or similar of the socket's state, which made the continuation of the transfer get delayed until next multi-socket call invoke or even longer.
Alternatively, the user could forcibly call for example curl_multi_socket_all - with a rather hefty performance penalty.

Starting in libcurl 7.32.0, unpausing a transfer will schedule a timeout trigger for that handle 1 millisecond into the future, so that a curl_multi_socket_action( ... CURL_SOCKET_TIMEOUT) can be used immediately afterwards to get the transfer going again as desired.

If you use multi interface, you can use multi_socket_action to have a more in-detail control of pausing the easy.

MEMORY USE

When pausing a read by returning the magic return code from a write callback, the read data is already in libcurl's internal buffers so it'll have to keep it in an allocated buffer until the reading is again unpaused using this function.

If the downloaded data is compressed and is asked to get uncompressed automatically on download, libcurl will continue to uncompress the entire downloaded chunk and it will cache the data uncompressed. This has the side-effect that if you download something that is compressed a lot, it can result in a very large amount of data required to be allocated to be kept around during the pause.

This said, you should probably consider not using paused reading if you allow libcurl to uncompress data automatically.

Definition at line 278 of file curl_easy.cc.

{
    int bitmask = 0;
    if (option & PauseOptions::recv)
        bitmask |= CURLPAUSE_RECV;
    if (option & PauseOptions::send)
        bitmask |= CURLPAUSE_SEND;
 
    auto result = curl_easy_pause(curl_easy, bitmask);
    if (result == CURLE_WRITE_ERROR)
        return {code::writeback_error};
    else if (result == CURLE_OUT_OF_MEMORY)
        return {std::bad_alloc{}};
    else if (result != CURLE_OK)
        return {Exception{result}};
    else
        return {code::ok};
}

getinfo_sizeof_request()

std::size_t curl::Easy_ref_t::getinfo_sizeof_request ( ) const

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http")

Returns

size of issued request headers in bytes, including headers sent in redirection.

Definition at line 304 of file curl_easy.cc.

{
    long size;
    curl_easy_getinfo(curl_easy, CURLINFO_REQUEST_SIZE, &size);
    return size;
}

getinfo_sizeof_uploaded()

std::size_t curl::Easy_ref_t::getinfo_sizeof_uploaded ( ) const

noexcept

Returns

in bytes

Definition at line 310 of file curl_easy.cc.

{
    curl_off_t ul;
    if (curl_easy_getinfo(curl_easy, CURLINFO_SIZE_UPLOAD_T, &ul)) {
        double bytes;
        curl_easy_getinfo(curl_easy, CURLINFO_SIZE_UPLOAD, &bytes);
        return static_cast<std::size_t>(bytes);
    }
    return ul;
}

getinfo_sizeof_response_header()

std::size_t curl::Easy_ref_t::getinfo_sizeof_response_header ( ) const

noexcept

Returns

in bytes

Definition at line 320 of file curl_easy.cc.

{
    long size;
    curl_easy_getinfo(curl_easy, CURLINFO_HEADER_SIZE, &size);
    return size;
}

getinfo_sizeof_response_body()

std::size_t curl::Easy_ref_t::getinfo_sizeof_response_body ( ) const

noexcept

Returns

in bytes, does not include response from redirection

Definition at line 326 of file curl_easy.cc.

{
    curl_off_t dl;
    if (curl_easy_getinfo(curl_easy, CURLINFO_SIZE_DOWNLOAD_T, &dl) == CURLE_UNKNOWN_OPTION) {
        double bytes;
        curl_easy_getinfo(curl_easy, CURLINFO_SIZE_DOWNLOAD, &bytes);
        return static_cast<std::size_t>(bytes);
    }
    return dl;
}

getinfo_transfer_time()

std::size_t curl::Easy_ref_t::getinfo_transfer_time ( ) const

noexcept

Returns

transfer time in ms

What transfer time really measures:

|
|--NAMELOOKUP
|--|--CONNECT
|--|--|--APPCONNECT
|--|--|--|--PRETRANSFER
|--|--|--|--|--STARTTRANSFER
|--|--|--|--|--|--transfer time
|--|--|--|--|--|--REDIRECT

Definition at line 336 of file curl_easy.cc.

{
    curl_off_t total;
    if (curl_easy_getinfo(curl_easy, CURLINFO_TOTAL_TIME_T, &total) == CURLE_UNKNOWN_OPTION) {
        double seconds;
        curl_easy_getinfo(curl_easy, CURLINFO_TOTAL_TIME, &seconds);
        return static_cast<std::size_t>(seconds * 1000);
    }
    return total;
}

getinfo_redirect_url()

auto curl::Easy_ref_t::getinfo_redirect_url ( ) const -> const char*

noexcept

Precondition

curl_t::has_redirect_url_support() && url is set to use http(s) && curl_t::has_protocol("http")

Returns

null-terminated string, freeing not required.
Would be freed up when corresponding curl::Easy_t is destroyed.
If not supported, would return nullptr.

If you disable redirection or CURLOPT_MAXREDIRS limit prevented a redirect to happen (since 7.54.1), a would-be redirect-to url is returned.

This function is only meaningful for http(s) protocol.

Definition at line 347 of file curl_easy.cc.

{
    char *url = nullptr;
    curl_easy_getinfo(curl_easy, CURLINFO_REDIRECT_URL, &url);
    return url;
}

getinfo_effective_url()

auto curl::Easy_ref_t::getinfo_effective_url ( ) const -> const char*

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http")

Returns

null-terminated string, freeing not required.
Would be freed up when corresponding curl::Easy_t is destroyed.
If not supported, would return nullptr.

It might be the url you set or the redirected actual url.

Definition at line 353 of file curl_easy.cc.

{
    char *url = nullptr;
    curl_easy_getinfo(curl_easy, CURLINFO_EFFECTIVE_URL, &url);
    return url;
}

getinfo_cookie_list()

auto curl::Easy_ref_t::getinfo_cookie_list ( ) const -> Ret_except<utils::slist, curl::NotBuiltIn_error>

noexcept

Precondition

url is set to use http(s) && curl_t::has_protocol("http") && curl_t::has_getinfo_cookie_list_support()

Returns

note that libcurl can be built with cookies disabled, thus this library can return exception curl::NotBuiltIn_error. If utils::slist is empty, it might be due to std::bad_alloc, or no cookie is present(cookie engine not enabled or no cookie has received).

Since 7.43.0 cookies that were imported in the Set-Cookie format without a domain name are not exported by this option.

Definition at line 360 of file curl_easy.cc.

{
    curl_slist *cookies = nullptr;
    if (curl_easy_getinfo(curl_easy, CURLINFO_COOKIELIST, &cookies) == CURLE_UNKNOWN_OPTION)
        return {curl::NotBuiltIn_error{"cookies not supported"}};
 
    return {utils::slist{cookies}};
}

get_active_socket()

auto curl::Easy_ref_t::get_active_socket ( ) const -> curl_socket_t

noexcept

Precondition

curl_t::has_get_active_socket_support()

Returns

CURL_SOCKET_BAD if no valid socket or not supported

The return value can be used in Multi_t::multi_assign()

Definition at line 370 of file curl_easy.cc.

{
    curl_socket_t socketfd = CURL_SOCKET_BAD;
    curl_easy_getinfo(curl_easy, CURLINFO_ACTIVESOCKET, &socketfd);
    return socketfd;
}

set_readall_writeback()

template<class String >

auto curl::Easy_ref_t::set_readall_writeback ( String &  response )

inlinenoexcept

set_readall_callback() can be used for get or post.

Definition at line 729 of file curl_easy.hpp.

    {
        set_writeback([](char *buffer, std::size_t _, std::size_t size, void *ptr) {
            auto &response = *static_cast<String*>(ptr);
            response.append(buffer, buffer + size);
            return size;
        }, &response);
    }

Here is the call graph for this function:

set_read_writeback()

template<class String , class size_type >

auto curl::Easy_ref_t::set_read_writeback ( std::pair< String, size_type > &  arg )

inlinenoexcept

set_read_callback() can be used for get or post.

This function will set writeback to only write arg.second bytes into arg.first.

Definition at line 745 of file curl_easy.hpp.

    {
        set_writeback([](char *buffer, std::size_t _, std::size_t size, void *ptr) {
            auto &args = *static_cast<std::pair<String, size_type>*>(ptr);
            auto &response = args.first;
            auto &requested_len = args.second;
 
            auto str_size = response.size();
            if (str_size < requested_len)
                response.append(buffer, buffer + std::min(size, requested_len - str_size));
 
            return size;
        }, &arg);
    }

Here is the call graph for this function:

setup_establish_connection_only()

void curl::Easy_ref_t::setup_establish_connection_only ( )

noexcept

After this call, Easy_ref_t::perform/Multi_t::perform or multi_socket_action must be called to establish the connection.

To use the established connection, call set_nobody(false) or request_*() to disable nobody.

Example usage:

int main(int argc, char* argv[]) {
    curl::curl_t curl{nullptr};

    auto easy = curl.create_easy();
    assert(easy.p1 && easy.p2);

    auto easy_ref = curl::Easy_ref_t{easy};
    easy_ref.set_url("https://www.google.com");

    setup_establish_connection_only();
    easy_ref.perform(); // Establish the connection

    request_get();
    easy_ref.perform(); // Now result is writen to stdout.
}

Definition at line 377 of file curl_easy.cc.

{
    request_get();
    curl_easy_setopt(curl_easy, CURLOPT_NOBODY, 1);
}

Here is the call graph for this function:

---

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

• curl_easy.hpp
• curl_easy.cc
• curl_err_handling.cc