KiCad PCB EDA Suite
KICAD_CURL_EASY Class Reference

Class 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...
 

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

CURLm_CURL
 
curl_slist * m_headers
 
std::string m_buffer
 

Detailed Description

Class 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:

curl.SetURL( "http://github.com" );
curl.SetUserAgent( <http-client-indentifier> );
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 ( )

Definition at line 47 of file kicad_curl_easy.cpp.

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

47  :
48  m_headers( NULL )
49 {
50  // Call KICAD_CURL::Init() from in here everytime, but only the first time
51  // will incur any overhead. This strategy ensures that libcurl is never loaded
52  // unless it is needed.
53 
55 
56  m_CURL = curl_easy_init();
57 
58  if( !m_CURL )
59  {
60  THROW_IO_ERROR( "Unable to initialize CURL session" );
61  }
62 
63  curl_easy_setopt( m_CURL, CURLOPT_WRITEFUNCTION, write_callback );
64  curl_easy_setopt( m_CURL, CURLOPT_WRITEDATA, (void*) &m_buffer );
65 }
static size_t write_callback(void *contents, size_t size, size_t nmemb, void *userp)
static void Init()
Function Init calls curl_global_init for the application.
Definition: kicad_curl.cpp:128
curl_slist * m_headers
std::string m_buffer
#define THROW_IO_ERROR(msg)
Definition: ki_exception.h:38
KICAD_CURL_EASY::~KICAD_CURL_EASY ( )

Definition at line 68 of file kicad_curl_easy.cpp.

References m_CURL, and m_headers.

69 {
70  if( m_headers )
71  curl_slist_free_all( m_headers );
72 
73  curl_easy_cleanup( m_CURL );
74 }
curl_slist * m_headers

Member Function Documentation

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.

References m_buffer.

Referenced by GITHUB_GETLIBLIST::remoteGetJSON(), and GITHUB_PLUGIN::remoteGetZip().

125  {
126  return m_buffer;
127  }
std::string m_buffer
const std::string KICAD_CURL_EASY::GetErrorText ( int  aCode)

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

Parameters
aCodeis 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.

Referenced by Perform().

112 {
113  return curl_easy_strerror( (CURLcode)aCode );
114 }
void KICAD_CURL_EASY::Perform ( )

Function perform equivalent to curl_easy_perform.

Executes the request that was previously setup.

Exceptions
IO_ERROR,ifthere is a CURL request error

Definition at line 77 of file kicad_curl_easy.cpp.

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

Referenced by GITHUB_GETLIBLIST::remoteGetJSON(), and GITHUB_PLUGIN::remoteGetZip().

78 {
79  if( m_headers )
80  {
81  curl_easy_setopt( m_CURL, CURLOPT_HTTPHEADER, m_headers );
82  }
83 
84  // bonus: retain worst case memory allocation, should re-use occur
85  m_buffer.clear();
86 
87  CURLcode res = curl_easy_perform( m_CURL );
88 
89  if( res != CURLE_OK )
90  {
91  std::string msg = "curl_easy_perform()=";
92  msg += (int)res; msg += " "; msg += GetErrorText( res ).c_str();
93  THROW_IO_ERROR( msg );
94  }
95 }
curl_slist * m_headers
const std::string GetErrorText(int aCode)
Function GetErrorText fetches CURL's "friendly" error string for a given error code.
std::string m_buffer
#define THROW_IO_ERROR(msg)
Definition: ki_exception.h:38
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
aFollowis 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.

Referenced by GITHUB_GETLIBLIST::remoteGetJSON(), and GITHUB_PLUGIN::remoteGetZip().

138 {
139  if( setOption<long>( CURLOPT_FOLLOWLOCATION , (aFollow ? 1 : 0) ) == CURLE_OK )
140  {
141  return true;
142  }
143  return false;
144 }
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
aNameis the left hand side of the header, i.e. Accept without the colon
aValueis the right hand side of the header, i.e. application/json

Definition at line 98 of file kicad_curl_easy.cpp.

References m_headers.

Referenced by GITHUB_GETLIBLIST::remoteGetJSON(), and GITHUB_PLUGIN::remoteGetZip().

99 {
100  std::string header = aName + ':' + aValue;
101  m_headers = curl_slist_append( m_headers, header.c_str() );
102 }
curl_slist * m_headers
template<typename T >
int KICAD_CURL_EASY::setOption ( int  aOption,
aArg 
)
private

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

Parameters
aOptionis CURL option, see CURL manual for options
aArgis 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.

References m_CURL.

106 {
107  return curl_easy_setopt( m_CURL, (CURLoption)aOption, aArg );
108 }
bool KICAD_CURL_EASY::SetURL ( const std::string &  aURL)

Function SetURL sets the request URL.

Parameters
aURLis the URL
Returns
bool - True if successful, false if not

Definition at line 127 of file kicad_curl_easy.cpp.

Referenced by GITHUB_GETLIBLIST::remoteGetJSON(), and GITHUB_PLUGIN::remoteGetZip().

128 {
129  if( setOption<const char *>( CURLOPT_URL, aURL.c_str() ) == CURLE_OK )
130  {
131  return true;
132  }
133  return false;
134 }
bool KICAD_CURL_EASY::SetUserAgent ( const std::string &  aAgent)

Function SetUserAgent sets the request user agent.

Parameters
aAgentis 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.

Referenced by GITHUB_GETLIBLIST::remoteGetJSON(), and GITHUB_PLUGIN::remoteGetZip().

118 {
119  if( setOption<const char*>( CURLOPT_USERAGENT, aAgent.c_str() ) == CURLE_OK )
120  {
121  return true;
122  }
123  return false;
124 }

Member Data Documentation

std::string KICAD_CURL_EASY::m_buffer
private

Definition at line 143 of file kicad_curl_easy.h.

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

CURL* KICAD_CURL_EASY::m_CURL
private

Definition at line 141 of file kicad_curl_easy.h.

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

curl_slist* KICAD_CURL_EASY::m_headers
private

Definition at line 142 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: