sss::WebClient Class Reference

Send web requests through libcurl. More...

#include <webclient.h>

Public Types
using	WriteFunction = size_t(*)(char *data, size_t size, size_t nmemb, void *writerData)
using	ReadFunction = size_t(*)(void *ptr, size_t size, size_t nmemb, void *readerData)

Public Member Functions
	WebClient (const WebClient &)=delete
	Disable copy constructor: only one libcurl handle per thread allwed.
	WebClient (WebClient &&other)
	Move constructor.
	WebClient ()
	Default constructor. First instance initializes libcurl.
	WebClient (const std::string &url)
	Constructor initializing only URL.
	WebClient (const std::string &endPoint, const std::string &path, const std::string &method="GET", const Map &params=Map(), const Map headers=Map())
	~WebClient ()
	Destructor. Last instance cleans up libcurl.
bool	Send ()
bool	SSLVerify (bool verifyPeer, bool verifyHost=true)
bool	SetUrl (const std::string &url)
void	SetEndpoint (const std::string &ep)
	Set endpoint: <proto>://<server>:<port>
void	SetPath (const std::string &path)
void	SetHeaders (const Map &headers)
void	SetReqParameters (const Map &params)
void	SetMethod (const std::string &method, size_t size=0)
void	SetUrlEncodedPostData (const Map &postData)
void	SetUrlEncodedPostData (const std::string &postData)
void	SetPostData (const std::string &data)
long	StatusCode () const
const std::string &	GetUrl () const
const std::vector< char > &	GetResponseBody () const
const std::vector< char > &	GetResponseHeader () const
std::string	GetContentText () const
	Get response body as text.
std::string	GetHeaderText () const
bool	SetWriteFunction (WriteFunction f, void *userData)
bool	SetReadFunction (ReadFunction f, void *userData)
bool	UploadFile (const std::string &fname, size_t fsize=0)
	Upload file.
bool	UploadFile (const std::string &fname, size_t offset, size_t size)
	Upload file starting from offset.
bool	UploadFileUnbuffered (const std::string &fname, size_t offset, size_t size)
	Upload file starting from offset using unbuffered I/O read.
bool	UploadFileMM (const std::string &fname, size_t offset, size_t size)
	Upload file starting from offset using unbuffered memory mapping of file.
bool	UploadDataFromBuffer (const char *data, size_t offset, size_t size)
	Upload data from memory buffer.
std::string	ErrorMsg () const
CURLcode	SetOpt (CURLoption option, va_list argp)
	Passthrough to curl_easy_setopt.
CURLcode	GetInfo (CURLINFO info, va_list argp)
	Passthrough method to curl_easy_getinfo.
void	SetVerbose (bool verbose)
	Send verbose output to stderr or the stream mapped to CURLOPT_STDERR.
bool	RedirectSTDErr (FILE *f)
	Redirect stderr to file. Returns false when it fails.
void	ClearBuffers ()
	Clear internal buffers.
void	ResetRWFunctions ()
	Reset read/write functions to default.

Detailed Description

Send web requests through libcurl.

Configure state then invoke WebClient::Send to send request.

Retrieve data through:

• GetResponseBody()
• GetResponseHeader()
• GetContentText()
• GetHeaderText()

Error handling is managed by having libcurl log errors into a char buffer. When a method fails returning false, you can extract the error message by invoking the WebClient::ErrorMsg() method.

Usage

WebClient req;
req.SSLVerify(verifyPeer, verifyHost);
req.SetEndpoint(args.endpoint);
req.SetPath(path);
req.SetMethod(args.method);
req.SetReqParameters(args.params);
req.SetHeaders(headers);
FILE *of = NULL;
if (!args.outfile.empty()) {
  of = fopen(args.outfile.c_str(), "wb");
  req.SetWriteFunction(NULL, of); // default is to write to file
}
if (!args.data.empty()) {
  if (!args.dataIsFileName) {
    if (ToLower(args.method) == "post") {
      req.SetUrlEncodedPostData(ParseParams(args.data.data()));
      req.SetMethod("POST");
      req.Send();
    } else { // "put"
      req.UploadDataFromBuffer(args.data.data(), 0, args.data.size());
    }
  } else {
    if (ToLower(args.method) == "put") {
      req.UploadFile(args.data.data());
    } else if (args.method == "post") {
      ifstream t(args.data.data());
      const string str((istreambuf_iterator<char>(t)),
                       istreambuf_iterator<char>());
      req.SetMethod("POST");
      req.SetPostData(str);
      req.Send();
    } else {
      throw domain_error("Wrong method " + args.method);
    }
  }
} else
  req.Send();
if (of)
  fclose(of);
return req;

Member Typedef Documentation

ReadFunction

using sss::WebClient::ReadFunction = size_t (*)(void *ptr, size_t size, size_t nmemb, void *readerData)

Function type invoked by libcurl to read data to send

Parameters

[in]	nmemb	number of blocks of size size
[in]	readerData	user data passed to reade function

WriteFunction

using sss::WebClient::WriteFunction = size_t (*)(char *data, size_t size, size_t nmemb, void *writerData)

Function type invoked by libcurl to write received data

Parameters

[in]	nmemb	number of blocks of size size
[in]	writerData	user data passed to write function

Constructor & Destructor Documentation

WebClient()

sss::WebClient::WebClient ( const std::string &  endPoint, const std::string &  path, const std::string &  method = "GET", const Map &  params = Map(), const Map  headers = Map()  )

inline

Constructor

Parameters

[in]	endPoint	endpoint in the format <proto>://<server>:port
[in]	path	path to be added to endPoint to compete URL: /.../...
[in]	method	HTTP method
[in]	params	key,value map of parameters k1=value1&k2=value2&...

~WebClient()

sss::WebClient::~WebClient

(

)

Destructor. Last instance cleans up libcurl.

Cleanup and invoke cleanup on libcurl in case of last instance.

Member Function Documentation

ErrorMsg()

std::string sss::WebClient::ErrorMsg

(

)

const

Return curl error.

Returns

libcurl error as returned by curl_easy_strerror or curl_multi_strerror.

Here is the caller graph for this function:

GetHeaderText()

std::string sss::WebClient::GetHeaderText

(

)

const

Get headers as text.

Returns

response headers as a single string.

References sss::begin(), sss::end(), and GetResponseHeader().

Here is the call graph for this function:

Here is the caller graph for this function:

GetInfo()

CURLcode sss::WebClient::GetInfo	(	CURLINFO	info,
		va_list	argp
	)

Passthrough method to curl_easy_getinfo.

https://curl.se/libcurl/c/curl_easy_getinfo.html

GetResponseBody()

const std::vector< char > & sss::WebClient::GetResponseBody

(

)

const

Get response content.

Returns

response bytes (char used because it's the type used within libcurl)

Here is the caller graph for this function:

GetResponseHeader()

const std::vector< char > & sss::WebClient::GetResponseHeader

(

)

const

Get reponse header.

Returns

raw response headers as a single byte array.

Here is the caller graph for this function:

GetUrl()

const std::string & sss::WebClient::GetUrl

(

)

const

Return full URL.

Returns

endpoint + url parameters

Send()

bool sss::WebClient::Send

(

)

Send request.

Returns

false if error, retrieve error message through WebClient::ErroMsg

Here is the caller graph for this function:

SetHeaders()

void sss::WebClient::SetHeaders

(

const Map &

headers

)

Store headers into internal buffer.

Parameters

[in]

headers

HTTP headers

Here is the caller graph for this function:

SetMethod()

void sss::WebClient::SetMethod	(	const std::string &	method,
		size_t	size = 0
	)

Set HTTP method.

Parameters

[in]

method

"GET", "POST", "PUT", "DELETE", "HEAD"

References sss::ToUpper().

Here is the call graph for this function:

Here is the caller graph for this function:

SetOpt()

CURLcode sss::WebClient::SetOpt	(	CURLoption	option,
		va_list	argp
	)

Passthrough to curl_easy_setopt.

https://curl.se/libcurl/c/curl_easy_setopt.html

SetPath()

void sss::WebClient::SetPath

(

const std::string &

path

)

Set URL path.

Parameters

[in]

path

URL with endpoint part removed.

Here is the caller graph for this function:

SetPostData()

void sss::WebClient::SetPostData

(

const std::string &

data

)

Store data to be posted.

Parameters

[in]

data

text to be posted.

Here is the caller graph for this function:

SetReadFunction()

bool sss::WebClient::SetReadFunction	(	ReadFunction	f,
		void *	userData
	)

Set function libcurl uses to read data to send.

Parameters

[in]	f	pointer to function called by libcurl to read data to send; set to NULL to read from file.
[in]	userData	pointer to user data.

Here is the caller graph for this function:

SetReqParameters()

void sss::WebClient::SetReqParameters

(

const Map &

params

)

Store request parameters into internal buffer.

Parameters

[in]

params

URL parameters: key=value&...

Here is the caller graph for this function:

SetUrl()

bool sss::WebClient::SetUrl

(

const std::string &

url

)

Set full URL

Parameters

[in]

url

endpoint + paramters URL

SetUrlEncodedPostData() [1/2]

void sss::WebClient::SetUrlEncodedPostData

(

const Map &

postData

)

Url-encode and store data to be posted from {key,value} map.

Parameters

[in]

postData

{key, value} map of URL paramters.

References sss::UrlEncode().

Here is the call graph for this function:

Here is the caller graph for this function:

SetUrlEncodedPostData() [2/2]

void sss::WebClient::SetUrlEncodedPostData

(

const std::string &

postData

)

Url-encode and store data to be posted from string in the standard key=value&key2=value2... format.

Parameters

[in]

postData

"key1=value1&key2=value2..."

References sss::UrlEncode().

Here is the call graph for this function:

SetWriteFunction()

bool sss::WebClient::SetWriteFunction	(	WriteFunction	f,
		void *	userData
	)

Set function libcurl uses to store response data.

Parameters

[in]	f	pointer to function called by libcurl to consume returned data.
[in]	userData	pointer to user data.

Here is the caller graph for this function:

SSLVerify()

bool sss::WebClient::SSLVerify	(	bool	verifyPeer,
		bool	verifyHost = true
	)

Set SSL verification options: peer and/or host Verification should be disabled when sending https requests through SSH tunnels.

Parameters

[in]	verifyPeer	verify the authenticity of the peer's certificate
[in]	verifyHost	verify the identity of the server

Here is the caller graph for this function:

StatusCode()

long sss::WebClient::StatusCode

(

)

const

Return status code from last executed request.

Returns

HTTP status (20*, 30*, 40*, 50*).

UploadDataFromBuffer()

bool sss::WebClient::UploadDataFromBuffer	(	const char *	data,
		size_t	offset,
		size_t	size
	)

Upload data from memory buffer.

Parameters

[in]	data	pointer to data
[in]	offset	offset
[in]	size	data size

Returns

true if successful, false otherwise

References Send(), and SetMethod().

Here is the call graph for this function:

Here is the caller graph for this function:

UploadFile() [1/2]

bool sss::WebClient::UploadFile	(	const std::string &	fname,
		size_t	fsize = 0
	)

Upload file.

Parameters

[in]	fname	file name
[in]	fsize	file size, if zero file size will be computed

Returns

true if successful, false otherwise

References ErrorMsg(), sss::FileSize(), Send(), SetMethod(), and SetReadFunction().

Here is the call graph for this function:

Here is the caller graph for this function:

UploadFile() [2/2]

bool sss::WebClient::UploadFile	(	const std::string &	fname,
		size_t	offset,
		size_t	size
	)

Upload file starting from offset.

Parameters

[in]	fname	file name
[in]	offset	offset
[in]	size	file size, if zero size is computed from file.

Returns

true if successful, false otherwise

References ErrorMsg(), sss::FileSize(), sss::ReadFile(), Send(), SetMethod(), and SetReadFunction().

Here is the call graph for this function:

UploadFileMM()

bool sss::WebClient::UploadFileMM	(	const std::string &	fname,
		size_t	offset,
		size_t	size
	)

Upload file starting from offset using unbuffered memory mapping of file.

Parameters

[in]	fname	file name
[in]	offset	offset
[in]	size	file size, if zero it will compute file size on its ow

Returns

true if successful, false otherwise

References UploadDataFromBuffer().

Here is the call graph for this function:

UploadFileUnbuffered()

bool sss::WebClient::UploadFileUnbuffered	(	const std::string &	fname,
		size_t	offset,
		size_t	size
	)

Upload file starting from offset using unbuffered I/O read.

Parameters

[in]	fname	file name
[in]	offset	offset
[in]	size	file size, if zero size will be computer as (file size) - offset.

Returns

true if successful, false otherwise

References ErrorMsg(), Send(), SetMethod(), and SetReadFunction().

Here is the call graph for this function:

---

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

• /Users/ugo/projects/s3client/repo/lib/include/webclient.h
• /Users/ugo/projects/s3client/repo/lib/src/webclient.cpp