drogon::HttpClient Class Reference

Asynchronous http client. More...

#include <drogon/HttpClient.h>

Inheritance diagram for drogon::HttpClient:

Collaboration diagram for drogon::HttpClient:

Public Member Functions
virtual void	sendRequest (const HttpRequestPtr &req, const HttpReqCallback &callback, double timeout=0)=0
	Send a request asynchronously to the server.
virtual void	sendRequest (const HttpRequestPtr &req, HttpReqCallback &&callback, double timeout=0)=0
	Send a request asynchronously to the server.
std::pair< ReqResult, HttpResponsePtr >	sendRequest (const HttpRequestPtr &req, double timeout=0)
	Send a request synchronously to the server and return the response.
virtual void	setSockOptCallback (std::function< void(int)> cb)=0
	Set socket options(before connecting).
virtual std::size_t	requestsBufferSize ()=0
	Return the number of unsent http requests in the current http client cache buffer.
virtual void	setPipeliningDepth (size_t depth)=0
virtual void	enableCookies (bool flag=true)=0
	Enable cookies for the client.
virtual void	addCookie (const std::string &key, const std::string &value)=0
	Add a cookie to the client.
virtual void	addCookie (const Cookie &cookie)=0
	Add a cookie to the client.
virtual void	setUserAgent (const std::string &userAgent)=0
	Set the user_agent header, the default value is 'DrogonClient' if this method is not used.
virtual trantor::EventLoop *	getLoop ()=0
	Get the event loop of the client;.
virtual size_t	bytesSent () const =0
	Get the number of bytes sent or received.
virtual size_t	bytesReceived () const =0
virtual std::string	host () const =0
std::string	getHost () const
virtual uint16_t	port () const =0
uint16_t	getPort () const
virtual bool	secure () const =0
bool	onDefaultPort () const
virtual void	setCertPath (const std::string &cert, const std::string &key)=0
	Set the client certificate used by the HTTP connection.
virtual void	addSSLConfigs (const std::vector< std::pair< std::string, std::string > > &sslConfCmds)=0
	Supplies command style options for SSL_CONF_cmd.

Static Public Member Functions
static HttpClientPtr	newHttpClient (const std::string &ip, uint16_t port, bool useSSL=false, trantor::EventLoop *loop=nullptr, bool useOldTLS=false, bool validateCert=true)
	Create a new HTTP client which use ip and port to connect to server.
static HttpClientPtr	newHttpClient (const std::string &hostString, trantor::EventLoop *loop=nullptr, bool useOldTLS=false, bool validateCert=true)
	Create a Http client using the hostString to connect to server.

Detailed Description

Asynchronous http client.

HttpClient implementation object uses the HttpAppFramework's event loop by default, so you should call app().run() to make the client work. Each HttpClient object establishes a persistent connection with the server. If the connection is broken, the client attempts to reconnect when calling the sendRequest method.

Using the static method newHttpClient(...) to get shared_ptr of the object implementing the class, the shared_ptr is retained in the framework until all response callbacks are invoked without fear of accidental deconstruction.

Member Function Documentation

addCookie() [1/2]

virtual void drogon::HttpClient::addCookie ( const Cookie & cookie )

pure virtual

Add a cookie to the client.

Note

These methods are independent of the enableCookies() method. Whether the enableCookies() is called with true or false, the cookies added by these methods will be sent to the server.

addCookie() [2/2]

virtual void drogon::HttpClient::addCookie ( const std::string & key, const std::string & value )

pure virtual

Add a cookie to the client.

Note

These methods are independent of the enableCookies() method. Whether the enableCookies() is called with true or false, the cookies added by these methods will be sent to the server.

addSSLConfigs()

virtual void drogon::HttpClient::addSSLConfigs ( const std::vector< std::pair< std::string, std::string > > & sslConfCmds )

pure virtual

Supplies command style options for SSL_CONF_cmd.

Parameters

sslConfCmds

options for SSL_CONF_cmd

Note

this method has no effect if the HTTP client is communicating via unencrypted HTTP

addSSLConfigs({{"-dhparam", "/path/to/dhparam"}, {"-strict", ""}});

enableCookies()

virtual void drogon::HttpClient::enableCookies ( bool flag = true )

pure virtual

Enable cookies for the client.

Parameters

flag	if the parameter is true, all requests sent by the client carry the cookies set by the server side. Cookies are disabled by default.

newHttpClient() [1/2]

HttpClientPtr drogon::HttpClient::newHttpClient ( const std::string & hostString, trantor::EventLoop * loop = nullptr, bool useOldTLS = false, bool validateCert = true )

static

Create a Http client using the hostString to connect to server.

Parameters

hostString

this parameter must be prefixed by 'http://' or 'https://'.

Examples for hostString:

https://www.baidu.com
http://www.baidu.com
https://127.0.0.1:8080/
http://127.0.0.1
http://[::1]:8080/   //IPv6 address must be enclosed in [], rfc2732

Parameters

loop	If the loop parameter is set to nullptr, the client uses the HttpAppFramework's event loop, otherwise it runs in the loop identified by the parameter.
useOldTLS	If the parameter is set to true, the TLS1.0/1.1 are enabled for HTTPS.

Note

Parameters

validateCert

If the parameter is set to true, the client validates the server certificate when SSL handshaking.

Note

Don't add path and parameters in hostString, the request path and parameters should be set in HttpRequestPtr when calling the sendRequest() method.

newHttpClient() [2/2]

HttpClientPtr drogon::HttpClient::newHttpClient ( const std::string & ip, uint16_t port, bool useSSL = false, trantor::EventLoop * loop = nullptr, bool useOldTLS = false, bool validateCert = true )

static

Create a new HTTP client which use ip and port to connect to server.

Parameters

ip	The ip address of the HTTP server
port	The port of the HTTP server
useSSL	if the parameter is set to true, the client connects to the server using HTTPS.
loop	If the loop parameter is set to nullptr, the client uses the HttpAppFramework's event loop, otherwise it runs in the loop identified by the parameter.
useOldTLS	If the parameter is set to true, the TLS1.0/1.1 are enabled for HTTPS.
validateCert	If the parameter is set to true, the client validates the server certificate when SSL handshaking.

Returns

HttpClientPtr The smart pointer to the new client object.

Note

: The ip parameter support for both ipv4 and ipv6 address

sendRequest() [1/3]

virtual void drogon::HttpClient::sendRequest ( const HttpRequestPtr & req, const HttpReqCallback & callback, double timeout = 0 )

pure virtual

Send a request asynchronously to the server.

Parameters

req	The request sent to the server.
callback	The callback is called when the response is received from the server.
timeout	In seconds. If the response is not received within the timeout, the callback is called with ReqResult::Timeout and an empty response. The zero value by default disables the timeout.

Note

The request object is altered(some headers are added to it) before it is sent, so calling this method with a same request object in different thread is dangerous. Please be careful when using timeout on an non-idempotent request.

sendRequest() [2/3]

std::pair< ReqResult, HttpResponsePtr > drogon::HttpClient::sendRequest ( const HttpRequestPtr & req, double timeout = 0 )

inline

Send a request synchronously to the server and return the response.

Parameters

req
timeout	In seconds. If the response is not received within the timeout, the ReqResult::Timeout and an empty response is returned. The zero value by default disables the timeout.

Returns

std::pair<ReqResult, HttpResponsePtr>

Note

Never call this function in the event loop thread of the client (partially in the callback function of the asynchronous sendRequest method), otherwise the thread will be blocked forever. Please be careful when using timeout on an non-idempotent request.

sendRequest() [3/3]

virtual void drogon::HttpClient::sendRequest ( const HttpRequestPtr & req, HttpReqCallback && callback, double timeout = 0 )

pure virtual

Send a request asynchronously to the server.

Parameters

req	The request sent to the server.
callback	The callback is called when the response is received from the server.
timeout	In seconds. If the response is not received within the timeout, the callback is called with ReqResult::Timeout and an empty response. The zero value by default disables the timeout.

Note

The request object is altered(some headers are added to it) before it is sent, so calling this method with a same request object in different thread is dangerous. Please be careful when using timeout on an non-idempotent request.

setCertPath()

virtual void drogon::HttpClient::setCertPath ( const std::string & cert, const std::string & key )

pure virtual

Set the client certificate used by the HTTP connection.

Parameters

cert	Path to the certificate
key	Path to the certificate's private key

Note

this method has no effect if the HTTP client is communicating via unencrypted HTTP

setPipeliningDepth()

virtual void drogon::HttpClient::setPipeliningDepth ( size_t depth )

pure virtual

Set the pipelining depth, which is the number of requests that are not responding. If this method is not called, the default depth value is 0 which means the pipelining is disabled. For details about pipelining, see rfc2616-8.1.2.2

setSockOptCallback()

virtual void drogon::HttpClient::setSockOptCallback ( std::function< void(int)> cb )

pure virtual

Set socket options(before connecting).

Set the callback which is called before connecting to the server. The callback is used to set socket options on the socket fd.

auto client = HttpClient::newHttpClient("http://www.baidu.com");
client->setSockOptCallback([](int fd) {});
auto req = HttpRequest::newHttpRequest();
client->sendRequest(req, [](ReqResult result, const HttpResponsePtr&
response) {});

setUserAgent()

virtual void drogon::HttpClient::setUserAgent ( const std::string & userAgent )

pure virtual

Set the user_agent header, the default value is 'DrogonClient' if this method is not used.

Parameters

userAgent

The user_agent value, if it is empty, the user_agent header is not sent to the server.

---

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

• lib/inc/drogon/HttpClient.h