mastodonpp::CURLWrapper Class Reference

Handles the details of network connections. More...

#include <mastodonpp/curl_wrapper.hpp>

Inheritance diagram for mastodonpp::CURLWrapper:

Public Member Functions
	CURLWrapper ()
	Initializes curl and sets up connection. More...
	CURLWrapper (const CURLWrapper &other)=delete
	Copy constructor. More...
	CURLWrapper (CURLWrapper &&other) noexcept=delete
	Move constructor. More...
virtual	~CURLWrapper () noexcept
	Cleans up curl and connection. More...
CURLWrapper &	operator= (const CURLWrapper &other)=delete
	Copy assignment operator. More...
CURLWrapper &	operator= (CURLWrapper &&other) noexcept=delete
	Move assignment operator. More...
CURL *	get_curl_easy_handle ()
	Returns pointer to the CURL easy handle. More...
string	escape_url (const string_view url) const
	URL encodes the given string. More...
string	unescape_url (const string_view url) const
	URL decodes the given string . More...
void	setup_connection_properties (string_view proxy, string_view access_token, string_view cainfo, string_view useragent)
	Set some properties of the connection. More...

Protected Member Functions
answer_type	make_request (const http_method &method, string uri, const parametermap &parameters)
	Make a HTTP request. More...
string &	get_buffer ()
	Returns a reference to the buffer libcurl writes into. More...
void	cancel_stream ()
	Cancel the stream. More...
void	set_proxy (string_view proxy)
	Set the proxy to use. More...
void	set_access_token (string_view access_token)
	Set OAuth 2.0 Bearer Access Token. More...
void	set_cainfo (string_view path)
	Set path to Certificate Authority (CA) bundle. More...
void	set_useragent (string_view useragent)
	Sets the User-Agent. More...

Protected Attributes
mutex	buffer_mutex
	Mutex for get_buffer a.k.a. _curl_buffer_body. More...

Detailed Description

Handles the details of network connections.

You don't need to use this.

Since

0.1.0

Constructor & Destructor Documentation

CURLWrapper() [1/3]

mastodonpp::CURLWrapper::CURLWrapper

(

)

Initializes curl and sets up connection.

The first time an instance of CURLWrapper is created, it calls curl_global_init, which is not thread-safe. For more information consult curl_global_init(3).

Since

0.1.0

    : _curl_buffer_error{}
    , _stream_cancelled(false)
{
    if (curlwrapper_instances == 0)
    {
        curl_global_init(CURL_GLOBAL_ALL); // NOLINT(hicpp-signed-bitwise)
    }
    ++curlwrapper_instances;
    debuglog << "CURLWrapper instances: " << curlwrapper_instances << " (+1)\n";
 
    _connection = curl_easy_init();
    setup_curl();
}

CURLWrapper() [2/3]

mastodonpp::CURLWrapper::CURLWrapper ( const CURLWrapper &  other )

delete

Copy constructor.

CURLWrapper() [3/3]

mastodonpp::CURLWrapper::CURLWrapper ( CURLWrapper &&  other )

deletenoexcept

Move constructor.

~CURLWrapper()

mastodonpp::CURLWrapper::~CURLWrapper ( )

virtualnoexcept

Cleans up curl and connection.

Calls curl_global_cleanup, which is not thread-safe. For more information consult curl_global_cleanup(3).

Since

0.1.0

{
    curl_easy_cleanup(_connection);
 
    --curlwrapper_instances;
    debuglog << "CURLWrapper instances: " << curlwrapper_instances << " (-1)\n";
    if (curlwrapper_instances == 0)
    {
        curl_global_cleanup();
    }
}

Member Function Documentation

cancel_stream()

void mastodonpp::CURLWrapper::cancel_stream ( )

inlineprotected

Cancel the stream.

The stream will be cancelled, usually whithin a second. The curl_error_code of the answer will be set to 42 (CURLE_ABORTED_BY_CALLBACK).

Since

0.1.0

    {
        _stream_cancelled = true;
    }

escape_url()

string mastodonpp::CURLWrapper::escape_url ( const string_view  url ) const

inline

URL encodes the given string.

For more information consult curl_easy_escape(3).

Parameters

url	String to escape.

Returns

The escaped string or {} if it failed.

Since

0.3.0

    {
        char *cbuf{curl_easy_escape(_connection, url.data(),
                                    static_cast<int>(url.size()))};
        string sbuf{cbuf};
        curl_free(cbuf);
        return sbuf;
    }

get_buffer()

string& mastodonpp::CURLWrapper::get_buffer ( )

inlineprotected

Returns a reference to the buffer libcurl writes into.

Since

0.1.0

    {
        return _curl_buffer_body;
    }

get_curl_easy_handle()

CURL* mastodonpp::CURLWrapper::get_curl_easy_handle ( )

inline

Returns pointer to the CURL easy handle.

You can use this handle to set or modify curl options. For more information consult curl_easy_setopt(3).

Since

0.1.0

    {
        return _connection;
    }

make_request()

answer_type mastodonpp::CURLWrapper::make_request ( const http_method &  method, string  uri, const parametermap &  parameters  )

protected

Make a HTTP request.

Parameters

method	The HTTP method.
uri	The full URI.
parameters	A map of parameters.

Since

0.1.0

{
    _stream_cancelled = false;
    _curl_buffer_headers.clear();
    _curl_buffer_body.clear();
 
    CURLcode code;
    switch (method)
    {
    case http_method::GET:
    {
        add_parameters_to_uri(uri, parameters);
        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
        curl_easy_setopt(_connection, CURLOPT_HTTPGET, 1L);
 
        break;
    }
    case http_method::POST:
    {
        if (parameters.empty())
        {
            // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
            curl_easy_setopt(_connection, CURLOPT_POST, 1L);
        }
        else
        {
            curl_mime *mime{parameters_to_curl_mime(uri, parameters)};
            // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
            curl_easy_setopt(_connection, CURLOPT_MIMEPOST, mime);
        }
 
        break;
    }
    case http_method::PATCH:
    {
        if (!parameters.empty())
        {
            curl_mime *mime{parameters_to_curl_mime(uri, parameters)};
            // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
            curl_easy_setopt(_connection, CURLOPT_MIMEPOST, mime);
        }
 
        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
        code = curl_easy_setopt(_connection, CURLOPT_CUSTOMREQUEST, "PATCH");
        if (code != CURLE_OK)
        {
            throw CURLException{code, "Failed to set URI", _curl_buffer_error};
        }
 
        break;
    }
    case http_method::PUT:
    {
        if (!parameters.empty())
        {
            curl_mime *mime{parameters_to_curl_mime(uri, parameters)};
            // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
            curl_easy_setopt(_connection, CURLOPT_MIMEPOST, mime);
        }
 
        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
        code = curl_easy_setopt(_connection, CURLOPT_CUSTOMREQUEST, "PUT");
        if (code != CURLE_OK)
        {
            throw CURLException{code, "Failed to set URI", _curl_buffer_error};
        }
 
        break;
    }
    case http_method::DELETE:
    {
        if (!parameters.empty())
        {
            curl_mime *mime{parameters_to_curl_mime(uri, parameters)};
            // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
            curl_easy_setopt(_connection, CURLOPT_MIMEPOST, mime);
        }
 
        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
        code = curl_easy_setopt(_connection, CURLOPT_CUSTOMREQUEST, "DELETE");
        if (code != CURLE_OK)
        {
            throw CURLException{code, "Failed to set URI", _curl_buffer_error};
        }
 
        break;
    }
    }
    debuglog << "Making request to: " << uri << '\n';
 
    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
    code = curl_easy_setopt(_connection, CURLOPT_URL, uri.data());
    if (code != CURLE_OK)
    {
        throw CURLException{code, "Failed to set URI", _curl_buffer_error};
    }
 
    answer_type answer;
    code = curl_easy_perform(_connection);
    if (code == CURLE_OK
        || (code == CURLE_ABORTED_BY_CALLBACK && _stream_cancelled))
    {
        long http_status;       // NOLINT(google-runtime-int)
        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
        curl_easy_getinfo(_connection, CURLINFO_RESPONSE_CODE, &http_status);
        answer.http_status = static_cast<uint16_t>(http_status);
        debuglog << "HTTP status code: " << http_status << '\n';
 
        answer.headers = _curl_buffer_headers;
        answer.body = _curl_buffer_body;
    }
    else
    {
        answer.curl_error_code = static_cast<uint8_t>(code);
        answer.error_message = _curl_buffer_error;
        debuglog << "libcurl error: " << code << '\n';
        debuglog << _curl_buffer_error << '\n';
    }
 
    return answer;
}

operator=() [1/2]

CURLWrapper& mastodonpp::CURLWrapper::operator= ( const CURLWrapper &  other )

delete

Copy assignment operator.

operator=() [2/2]

CURLWrapper& mastodonpp::CURLWrapper::operator= ( CURLWrapper &&  other )

deletenoexcept

Move assignment operator.

set_access_token()

void mastodonpp::CURLWrapper::set_access_token ( string_view  access_token )

protected

Set OAuth 2.0 Bearer Access Token.

Since

0.1.0

{
    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg, hicpp-signed-bitwise)
    CURLcode code{curl_easy_setopt(_connection, CURLOPT_XOAUTH2_BEARER,
                                   access_token.data())};
    if (code != CURLE_OK)
    {
        throw CURLException{code, "Could not set authorization token.",
                _curl_buffer_error};
    }
 
#if (LIBCURL_VERSION_NUM < 0x073d00) // libcurl < 7.61.0.
#define CURLAUTH_BEARER CURLAUTH_ANY
#endif
 
    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg, hicpp-signed-bitwise)
    code = curl_easy_setopt(_connection, CURLOPT_HTTPAUTH, CURLAUTH_BEARER);
    if (code != CURLE_OK)
    {
        throw CURLException{code, "Could not set authorization token.",
                _curl_buffer_error};
    }
 
    debuglog << "Set authorization token.\n";
}

set_cainfo()

void mastodonpp::CURLWrapper::set_cainfo ( string_view  path )

protected

Set path to Certificate Authority (CA) bundle.

Since

0.3.0

{
    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
    CURLcode code{curl_easy_setopt(_connection, CURLOPT_CAINFO, path.data())};
    if (code != CURLE_OK)
    {
        throw CURLException{code, "Could not set CA info.", _curl_buffer_error};
    }
}

set_proxy()

void mastodonpp::CURLWrapper::set_proxy ( string_view  proxy )

protected

Set the proxy to use.

See CURLOPT_PROXY(3).

Parameters

proxy

Examples: "socks4a://127.0.0.1:9050", "http://[::1]:3128".

Since

0.1.0

{
    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
    CURLcode code{curl_easy_setopt(_connection, CURLOPT_PROXY, proxy.data())};
    if (code != CURLE_OK)
    {
        throw CURLException{code, "Failed to set proxy", _curl_buffer_error};
    }
    debuglog << "Set proxy to: " << proxy << '\n';
}

set_useragent()

void mastodonpp::CURLWrapper::set_useragent ( string_view  useragent )

protected

Sets the User-Agent.

Since

0.3.0

{
    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
    CURLcode code{curl_easy_setopt(_connection, CURLOPT_USERAGENT,
                                   useragent.data())};
    if (code != CURLE_OK)
    {
        throw CURLException{code, "Failed to set User-Agent",
                _curl_buffer_error};
    }
    debuglog << "Set User-Agent to: " << useragent << '\n';
}

setup_connection_properties()

void mastodonpp::CURLWrapper::setup_connection_properties	(	string_view	proxy,
		string_view	access_token,
		string_view	cainfo,
		string_view	useragent
	)

Set some properties of the connection.

Meant for internal use. See Instance::copy_connection_properties().

Since

0.3.0

{
    if (!proxy.empty())
    {
        set_proxy(proxy);
    }
 
    if (!access_token.empty())
    {
        set_access_token(access_token);
    }
 
    if (!cainfo.empty())
    {
        set_cainfo(cainfo);
    }
 
    if (!useragent.empty())
    {
        set_useragent(useragent);
    }
}

unescape_url()

string mastodonpp::CURLWrapper::unescape_url ( const string_view  url ) const

inline

URL decodes the given string .

For more information consult curl_easy_unescape(3).

Parameters

url	String to unescape.

Returns

The unescaped string or {} if it failed.

Since

0.3.0

    {
        char *cbuf{curl_easy_unescape(_connection, url.data(),
                                      static_cast<int>(url.size()), nullptr)};
        string sbuf{cbuf};
        curl_free(cbuf);
        return sbuf;
    }

Member Data Documentation

buffer_mutex

mutex mastodonpp::CURLWrapper::buffer_mutex

protected

Mutex for get_buffer a.k.a. _curl_buffer_body.

This mutex is locked before anything is read or written from/to _curl_buffer_body.

Since

0.1.0

---

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

• include/curl_wrapper.hpp
• src/curl_wrapper.cpp