KICAD_CURL_EASY Class Reference

KICAD_CURL_EASY wrapper interface around the curl_easy API. More...

#include <kicad_curl_easy.h>

Public Member Functions
	KICAD_CURL_EASY ()
	~KICAD_CURL_EASY ()
void	Perform ()
	Function perform equivalent to curl_easy_perform. More...
void	SetHeader (const std::string &aName, const std::string &aValue)
	Function SetHeader sets an arbitrary header for the HTTP(s) request. More...
bool	SetUserAgent (const std::string &aAgent)
	Function SetUserAgent sets the request user agent. More...
bool	SetURL (const std::string &aURL)
	Function SetURL sets the request URL. More...
bool	SetFollowRedirects (bool aFollow)
	Function SetFollowRedirects enables the following of HTTP(s) and other redirects, by default curl does not follow redirects. More...
const std::string	GetErrorText (int aCode)
	Function GetErrorText fetches CURL's "friendly" error string for a given error code. More...
const std::string &	GetBuffer ()
	Function GetBuffer returns a const reference to the recevied data buffer. More...
std::string	Escape (const std::string &aUrl)
	Escapes a string for use as a URL. More...

Private Member Functions
template<typename T >
int	setOption (int aOption, T aArg)
	Function setOption sets a curl option, only supports single parameter curl options. More...

Private Attributes
CURL *	m_CURL
curl_slist *	m_headers
std::string	m_buffer

Detailed Description

KICAD_CURL_EASY wrapper interface around the curl_easy API.

Handling of using the curl_easy API to make a request and save the response to a memory buffer

Here is a small example usage:

KICAD_CURL_EASY curl;

curl.SetURL( "http://github.com" );
curl.SetUserAgent( <http-client-identifier> );
curl.SetHeader( "Accept", "application/json" );
curl.Perform();

Definition at line 59 of file kicad_curl_easy.h.

Constructor & Destructor Documentation

KICAD_CURL_EASY()

KICAD_CURL_EASY::KICAD_CURL_EASY

(

)

Definition at line 47 of file kicad_curl_easy.cpp.

                                 :
    m_headers( NULL )
{
    // Call KICAD_CURL::Init() from in here everytime, but only the first time
    // will incur any overhead.  This strategy ensures that libcurl is never loaded
    // unless it is needed.

    KICAD_CURL::Init();

    m_CURL = curl_easy_init();

    if( !m_CURL )
    {
        THROW_IO_ERROR( "Unable to initialize CURL session" );
    }

    curl_easy_setopt( m_CURL, CURLOPT_WRITEFUNCTION, write_callback );
    curl_easy_setopt( m_CURL, CURLOPT_WRITEDATA, (void*) &m_buffer );
}

References KICAD_CURL::Init(), m_buffer, m_CURL, THROW_IO_ERROR, and write_callback().

~KICAD_CURL_EASY()

KICAD_CURL_EASY::~KICAD_CURL_EASY

(

)

Definition at line 68 of file kicad_curl_easy.cpp.

{
    if( m_headers )
        curl_slist_free_all( m_headers );

    curl_easy_cleanup( m_CURL );
}

References m_CURL, and m_headers.

Member Function Documentation

Escape()

std::string KICAD_CURL_EASY::Escape

(

const std::string &

aUrl

)

Escapes a string for use as a URL.

Definition at line 147 of file kicad_curl_easy.cpp.

{
    char* escaped = curl_easy_escape( m_CURL, aUrl.c_str(), aUrl.length() );

    std::string ret( escaped );
    curl_free( escaped );

    return ret;
}

References m_CURL.

Referenced by COMMON_CONTROL::ReportBug().

GetBuffer()

const std::string& KICAD_CURL_EASY::GetBuffer ( )

inline

Function GetBuffer returns a const reference to the recevied data buffer.

Definition at line 124 of file kicad_curl_easy.h.

    {
        return m_buffer;
    }

References m_buffer.

GetErrorText()

const std::string KICAD_CURL_EASY::GetErrorText

(

int

aCode

)

Function GetErrorText fetches CURL's "friendly" error string for a given error code.

Parameters

aCode

is CURL error code

Returns

const std::string - the corresponding error string for the given code

Definition at line 111 of file kicad_curl_easy.cpp.

{
    return curl_easy_strerror( (CURLcode)aCode );
}

Referenced by Perform().

Perform()

void KICAD_CURL_EASY::Perform

(

)

Function perform equivalent to curl_easy_perform.

Executes the request that was previously setup.

Exceptions

IO_ERROR,if

there is a CURL request error

Definition at line 77 of file kicad_curl_easy.cpp.

{
    if( m_headers )
    {
        curl_easy_setopt( m_CURL, CURLOPT_HTTPHEADER, m_headers );
    }

    // bonus: retain worst case memory allocation, should re-use occur
    m_buffer.clear();

    CURLcode res = curl_easy_perform( m_CURL );

    if( res != CURLE_OK )
    {
        std::string msg = "curl_easy_perform()=";
        msg += (int)res; msg += " "; msg += GetErrorText( res ).c_str();
        THROW_IO_ERROR( msg );
    }
}

References GetErrorText(), m_buffer, m_CURL, m_headers, and THROW_IO_ERROR.

SetFollowRedirects()

bool KICAD_CURL_EASY::SetFollowRedirects

(

bool

aFollow

)

Function SetFollowRedirects enables the following of HTTP(s) and other redirects, by default curl does not follow redirects.

Parameters

aFollow

is a boolean where true will enable following redirects

Returns

bool - True if successful, false if not

Definition at line 137 of file kicad_curl_easy.cpp.

{
    if( setOption<long>( CURLOPT_FOLLOWLOCATION , (aFollow ? 1 : 0) ) == CURLE_OK )
    {
        return true;
    }
    return false;
}

SetHeader()

void KICAD_CURL_EASY::SetHeader	(	const std::string &	aName,
		const std::string &	aValue
	)

Function SetHeader sets an arbitrary header for the HTTP(s) request.

Parameters

aName	is the left hand side of the header, i.e. Accept without the colon
aValue	is the right hand side of the header, i.e. application/json

Definition at line 98 of file kicad_curl_easy.cpp.

{
    std::string header = aName + ':' + aValue;
    m_headers = curl_slist_append( m_headers, header.c_str() );
}

References m_headers.

setOption()

template<typename T >

int KICAD_CURL_EASY::setOption ( int  aOption, T  aArg  )

private

Function setOption sets a curl option, only supports single parameter curl options.

Parameters

aOption	is CURL option, see CURL manual for options
aArg	is the argument being passed to CURL, ensure it is the right type per manual

Returns

int - a CURL error code, will return CURLE_OK unless a problem was encountered

Definition at line 105 of file kicad_curl_easy.cpp.

{
    return curl_easy_setopt( m_CURL, (CURLoption)aOption, aArg );
}

References m_CURL.

SetURL()

bool KICAD_CURL_EASY::SetURL

(

const std::string &

aURL

)

Function SetURL sets the request URL.

Parameters

aURL	is the URL

Returns

bool - True if successful, false if not

Definition at line 127 of file kicad_curl_easy.cpp.

{
    if( setOption<const char *>( CURLOPT_URL, aURL.c_str() ) == CURLE_OK )
    {
        return true;
    }
    return false;
}

SetUserAgent()

bool KICAD_CURL_EASY::SetUserAgent

(

const std::string &

aAgent

)

Function SetUserAgent sets the request user agent.

Parameters

aAgent

is the string to set for the user agent

Returns

bool - True if successful, false if not

Definition at line 117 of file kicad_curl_easy.cpp.

{
    if( setOption<const char*>( CURLOPT_USERAGENT, aAgent.c_str() ) == CURLE_OK )
    {
        return true;
    }
    return false;
}

Member Data Documentation

m_buffer

std::string KICAD_CURL_EASY::m_buffer

private

Definition at line 146 of file kicad_curl_easy.h.

Referenced by GetBuffer(), KICAD_CURL_EASY(), and Perform().

m_CURL

CURL* KICAD_CURL_EASY::m_CURL

private

Definition at line 144 of file kicad_curl_easy.h.

Referenced by Escape(), KICAD_CURL_EASY(), Perform(), setOption(), and ~KICAD_CURL_EASY().

m_headers

curl_slist* KICAD_CURL_EASY::m_headers

private

Definition at line 145 of file kicad_curl_easy.h.

Referenced by Perform(), SetHeader(), and ~KICAD_CURL_EASY().

---

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

• kicad_curl_easy.h
• kicad_curl_easy.cpp