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 (CURLcode aCode)
 Function GetErrorText fetches CURL's "friendly" error string for a given error code. More...
 
template<typename T >
CURLcode SetOption (CURLoption aOption, T aArg)
 Function SetOption sets a curl option, only supports single parameter curl options. More...
 
const std::string & GetBuffer ()
 Function GetBuffer returns a const reference to the recevied data buffer. More...
 

Private Attributes

CURL * m_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 67 of file kicad_curl_easy.h.

Constructor & Destructor Documentation

KICAD_CURL_EASY::KICAD_CURL_EASY ( )

Definition at line 46 of file kicad_curl_easy.cpp.

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

46  :
47  m_headers( NULL )
48 {
49  // Call KICAD_CURL::Init() from in here everytime, but only the first time
50  // will incur any overhead. This strategy ensures that libcurl is never loaded
51  // unless it is needed.
52 
54 
55  m_CURL = curl_easy_init();
56 
57  if( !m_CURL )
58  {
59  THROW_IO_ERROR( "Unable to initialize CURL session" );
60  }
61 
62  curl_easy_setopt( m_CURL, CURLOPT_WRITEFUNCTION, write_callback );
63  curl_easy_setopt( m_CURL, CURLOPT_WRITEDATA, (void*) &m_buffer );
64 }
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:135
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 67 of file kicad_curl_easy.cpp.

References m_CURL, and m_headers.

68 {
69  if( m_headers )
70  curl_slist_free_all( m_headers );
71 
72  curl_easy_cleanup( m_CURL );
73 }
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 173 of file kicad_curl_easy.h.

References m_buffer.

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

174  {
175  return m_buffer;
176  }
std::string m_buffer
const std::string KICAD_CURL_EASY::GetErrorText ( CURLcode  aCode)
inline

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 151 of file kicad_curl_easy.h.

Referenced by Perform().

152  {
153  return curl_easy_strerror( aCode );
154  }
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 76 of file kicad_curl_easy.cpp.

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

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

77 {
78  if( m_headers )
79  {
80  curl_easy_setopt( m_CURL, CURLOPT_HTTPHEADER, m_headers );
81  }
82 
83  // bonus: retain worst case memory allocation, should re-use occur
84  m_buffer.clear();
85 
86  CURLcode res = curl_easy_perform( m_CURL );
87 
88  if( res != CURLE_OK )
89  {
90  std::string msg = StrPrintf( "curl_easy_perform()=%d: %s",
91  res, GetErrorText( res ).c_str() );
92  THROW_IO_ERROR( msg );
93  }
94 }
int StrPrintf(std::string *result, const char *format,...)
Function StrPrintf is like sprintf() but the output is appended to a std::string instead of to a char...
Definition: richio.cpp:75
curl_slist * m_headers
std::string m_buffer
const std::string GetErrorText(CURLcode aCode)
Function GetErrorText fetches CURL's "friendly" error string for a given error code.
#define THROW_IO_ERROR(msg)
Definition: ki_exception.h:38
bool KICAD_CURL_EASY::SetFollowRedirects ( bool  aFollow)
inline

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 135 of file kicad_curl_easy.h.

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

136  {
137  if( SetOption<long>( CURLOPT_FOLLOWLOCATION , (aFollow ? 1 : 0) ) == CURLE_OK )
138  {
139  return true;
140  }
141  return false;
142  }
void KICAD_CURL_EASY::SetHeader ( const std::string &  aName,
const std::string &  aValue 
)
inline

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 89 of file kicad_curl_easy.h.

References m_headers.

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

90  {
91  std::string header = aName + ':' + aValue;
92  m_headers = curl_slist_append( m_headers, header.c_str() );
93  }
curl_slist * m_headers
template<typename T >
CURLcode KICAD_CURL_EASY::SetOption ( CURLoption  aOption,
aArg 
)
inline

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
CURLcode - CURL error code, will return CURLE_OK unless a problem was encountered

Definition at line 164 of file kicad_curl_easy.h.

References m_CURL.

165  {
166  return curl_easy_setopt( m_CURL, aOption, aArg );
167  }
bool KICAD_CURL_EASY::SetURL ( const std::string &  aURL)
inline

Function SetURL sets the request URL.

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

Definition at line 118 of file kicad_curl_easy.h.

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

119  {
120  if( SetOption<const char *>( CURLOPT_URL, aURL.c_str() ) == CURLE_OK )
121  {
122  return true;
123  }
124  return false;
125  }
bool KICAD_CURL_EASY::SetUserAgent ( const std::string &  aAgent)
inline

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 102 of file kicad_curl_easy.h.

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

103  {
104  if( SetOption<const char*>( CURLOPT_USERAGENT, aAgent.c_str() ) == CURLE_OK )
105  {
106  return true;
107  }
108  return false;
109  }

Member Data Documentation

std::string KICAD_CURL_EASY::m_buffer
private

Definition at line 181 of file kicad_curl_easy.h.

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

CURL* KICAD_CURL_EASY::m_CURL
private

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