class EE::Network::Http¶
Overview¶
A HTTP client. More…
#include <http.hpp> class Http: private EE::NonCopyable { public: // typedefs typedef std::function<void(const Http&, Http::Request&, Http::Response&)> AsyncResponseCallback; // classes class AsyncRequest; class HttpConnection; class MultipartEntitiesBuilder; class Pool; class Request; class Response; // construction Http(); Http(const std::string& host, unsigned short port = 0, bool useSSL = false, URI proxy = URI()); ~Http(); // methods void setHost(const std::string& host, unsigned short port = 0, bool useSSL = false, URI proxy = URI()); Response sendRequest(const Request& request, Time timeout = Time::Zero); Response downloadRequest(const Request& request, IOStream& writeTo, Time timeout = Time::Zero); Response downloadRequest(const Request& request, std::string writePath, Time timeout = Time::Zero); void sendAsyncRequest(const AsyncResponseCallback& cb, const Http::Request& request, Time timeout = Time::Zero); void downloadAsyncRequest(const AsyncResponseCallback& cb, const Http::Request& request, IOStream& writeTo, Time timeout = Time::Zero); void downloadAsyncRequest(const AsyncResponseCallback& cb, const Http::Request& request, std::string writePath, Time timeout = Time::Zero); const IpAddress& getHost() const; const std::string& getHostName() const; const unsigned short& getPort() const; const bool& isSSL() const; URI getURI() const; void setProxy(const URI& uri); const URI& getProxy() const; bool isProxied() const; static Response request( const URI& uri, Request::Method method = Request::Method::Get, const Time& timeout = Time::Zero, const Request::ProgressCallback& progressCallback = Request::ProgressCallback(), const Request::FieldTable& headers = Request::FieldTable(), const std::string& body = "", const bool& validateCertificate = true, const URI& proxy = URI() ); static Response get( const URI& uri, const Time& timeout = Time::Zero, const Request::ProgressCallback& progressCallback = Request::ProgressCallback(), const Request::FieldTable& headers = Request::FieldTable(), const std::string& body = "", const bool& validateCertificate = true, const URI& proxy = URI() ); static Response post( const URI& uri, const Time& timeout = Time::Zero, const Request::ProgressCallback& progressCallback = Request::ProgressCallback(), const Request::FieldTable& headers = Request::FieldTable(), const std::string& body = "", const bool& validateCertificate = true, const URI& proxy = URI() ); static void requestAsync( const Http::AsyncResponseCallback& cb, const URI& uri, const Time& timeout = Time::Zero, Request::Method method = Request::Method::Get, const Request::ProgressCallback& progressCallback = Request::ProgressCallback(), const Request::FieldTable& headers = Request::FieldTable(), const std::string& body = "", const bool& validateCertificate = true, const URI& proxy = URI() ); static void getAsync( const Http::AsyncResponseCallback& cb, const URI& uri, const Time& timeout = Time::Zero, const Request::ProgressCallback& progressCallback = Request::ProgressCallback(), const Request::FieldTable& headers = Request::FieldTable(), const std::string& body = "", const bool& validateCertificate = true, const URI& proxy = URI() ); static void postAsync( const Http::AsyncResponseCallback& cb, const URI& uri, const Time& timeout = Time::Zero, const Request::ProgressCallback& progressCallback = Request::ProgressCallback(), const Request::FieldTable& headers = Request::FieldTable(), const std::string& body = "", const bool& validateCertificate = true, const URI& proxy = URI() ); static URI getEnvProxyURI(); static void setThreadPool(std::shared_ptr<ThreadPool> pool); };
Detailed Documentation¶
A HTTP client.
Http is a very simple HTTP client that allows you to communicate with a web server. You can retrieve web pages, send data to an interactive resource, download a remote file, etc. The HTTP client is split into 3 classes:
EE::Network::Http EE::Network::Http::Request builds the request that will be sent to the server. A request is made of:
a method (what you want to do)
a target URI (usually the name of the web page or file)
one or more header fields (options that you can pass to the server)
an optional body (for POST requests) EE::Network::Http::Response parse the response from the web server and provides getters to read them. The response contains:
a status code
header fields (that may be answers to the ones that you requested)
a body, which contains the contents of the requested resource Http provides a simple function, sendRequest, to send a EE::Network::Http::Request and return the corresponding EE::Network::Http::Response from the server. Usage example:
// Create a new HTTP client Http http; // We'll work on http://www.google.com http.setHost( "http://www.google.com" ); // Prepare a request to get the 'features.php' page Http::Request request( "features.php" ); // Send the request Http::Response response = http.sendRequest(request); // Check the status code and display the result Http::Response::Status status = response.getStatus(); if ( status == Http::Response::Ok ) { std::cout << response.getBody() << std::endl; } else { std::cout << "Error " << status << std::endl; }
Shorthand methods are also provided:
Http::Response response = Http::get( "http://www.google.com" ); if ( response.getStatus() == Http::Response::Ok ) { std::cout << response.getBody() << std::endl; } else { std::cout << "Error " << response.getStatus() << std::endl; }
You can also use the shorthand async alternative method:
Http::getAsync( [=]( const Http&, Http::Request&, Http::Response& response ) { if ( response.getStatus() == Http::Response::Ok) { std::cout << response.getBody() << std::endl; } else { std::cout << "Error " << response.getStatus() << std::endl; } }, "http://www.google.com" );
Typedefs¶
typedef std::function<void(const Http&, Http::Request&, Http::Response&)> AsyncResponseCallback
Definition of the async callback response
Construction¶
Http()
Default constructor.
Http(const std::string& host, unsigned short port = 0, bool useSSL = false, URI proxy = URI())
Construct the HTTP client with the target host This is equivalent to calling setHost(host, port). The port has a default value of 0, which means that the HTTP client will use the right port according to the protocol used (80 for HTTP, 443 for HTTPS). You should leave it like this unless you really need a port other than the standard one, or use an unknown protocol.
Parameters:
host |
Web server to connect to |
port |
Port to use for connection |
useSSL |
force the SSL usage ( if compiled with the support of it ). If the host starts with https:// it will use it by default. |
proxy |
Set an http proxy for the host connection |
Methods¶
void setHost(const std::string& host, unsigned short port = 0, bool useSSL = false, URI proxy = URI())
Set the target host This function just stores the host address and port, it doesn’t actually connect to it until you send a request. The port has a default value of 0, which means that the HTTP client will use the right port according to the protocol used (80 for HTTP, 443 for HTTPS). You should leave it like this unless you really need a port other than the standard one, or use an unknown protocol.
Parameters:
host |
Web server to connect to |
port |
Port to use for connection |
useSSL |
force the SSL usage ( if compiled with the support of it ). If the host starts with https:// it will use it by default. * |
proxy |
Set an http proxy for the host connection |
Response sendRequest(const Request& request, Time timeout = Time::Zero)
Send a HTTP request and return the server’s response. You must have a valid host before sending a request (see setHost). Any missing mandatory header field in the request will be added with an appropriate value. Warning: this function waits for the server’s response and may not return instantly; use a thread if you don’t want to block your application, or use a timeout to limit the time to wait. A value of Time::Zero means that the client will use the system defaut timeout (which is usually pretty long).
Parameters:
request |
Request to send |
timeout |
Maximum time to wait |
Returns:
Server’s response
Response downloadRequest(const Request& request, IOStream& writeTo, Time timeout = Time::Zero)
Send a HTTP request and writes the server’s response to a IOStream file. You must have a valid host before sending a request (see setHost). Any missing mandatory header field in the request will be added with an appropriate value. Warning: this function waits for the server’s response and may not return instantly; use a thread if you don’t want to block your application, or use a timeout to limit the time to wait. A value of Time::Zero means that the client will use the system defaut timeout (which is usually pretty long).
Parameters:
request |
Request to send |
writeTo |
The IO stream to write the downloaded content |
timeout |
Maximum time to wait |
Returns:
Server’s response
Response downloadRequest(const Request& request, std::string writePath, Time timeout = Time::Zero)
Send a HTTP request and writes the server’s response to a file system path. You must have a valid host before sending a request (see setHost). Any missing mandatory header field in the request will be added with an appropriate value. Warning: this function waits for the server’s response and may not return instantly; use a thread if you don’t want to block your application, or use a timeout to limit the time to wait. A value of Time::Zero means that the client will use the system defaut timeout (which is usually pretty long).
Parameters:
request |
Request to send |
writePath |
The path of the file to write the downloaded content |
timeout |
Maximum time to wait |
Returns:
Server’s response
void sendAsyncRequest(const AsyncResponseCallback& cb, const Http::Request& request, Time timeout = Time::Zero)
Sends the request and creates a new thread, when got the response informs the result to the callback. * This function does not lock the caller thread.
See also:
void downloadAsyncRequest(const AsyncResponseCallback& cb, const Http::Request& request, IOStream& writeTo, Time timeout = Time::Zero)
Sends the request and creates a new thread, when got the response informs the result to the callback. * This function does not lock the caller thread.
See also:
void downloadAsyncRequest(const AsyncResponseCallback& cb, const Http::Request& request, std::string writePath, Time timeout = Time::Zero)
Sends the request and creates a new thread, when got the response informs the result to the callback. * This function does not lock the caller thread.
See also:
const IpAddress& getHost() const
Returns:
The host address
const std::string& getHostName() const
Returns:
The host name
const unsigned short& getPort() const
Returns:
The host port
const bool& isSSL() const
Returns:
If the HTTP client uses SSL/TLS
URI getURI() const
Returns:
The URI from the schema + hostname + port
void setProxy(const URI& uri)
Sets the request proxy
const URI& getProxy() const
Returns:
The request proxy
bool isProxied() const
Returns:
Is a proxy is need to be used
static Response request( const URI& uri, Request::Method method = Request::Method::Get, const Time& timeout = Time::Zero, const Request::ProgressCallback& progressCallback = Request::ProgressCallback(), const Request::FieldTable& headers = Request::FieldTable(), const std::string& body = "", const bool& validateCertificate = true, const URI& proxy = URI() )
Creates an HTTP Request using the global HTTP Client Pool
static Response get( const URI& uri, const Time& timeout = Time::Zero, const Request::ProgressCallback& progressCallback = Request::ProgressCallback(), const Request::FieldTable& headers = Request::FieldTable(), const std::string& body = "", const bool& validateCertificate = true, const URI& proxy = URI() )
Creates an HTTP GET Request using the global HTTP Client Pool
static Response post( const URI& uri, const Time& timeout = Time::Zero, const Request::ProgressCallback& progressCallback = Request::ProgressCallback(), const Request::FieldTable& headers = Request::FieldTable(), const std::string& body = "", const bool& validateCertificate = true, const URI& proxy = URI() )
Creates an HTTP POST Request using the global HTTP Client Pool
static void requestAsync( const Http::AsyncResponseCallback& cb, const URI& uri, const Time& timeout = Time::Zero, Request::Method method = Request::Method::Get, const Request::ProgressCallback& progressCallback = Request::ProgressCallback(), const Request::FieldTable& headers = Request::FieldTable(), const std::string& body = "", const bool& validateCertificate = true, const URI& proxy = URI() )
Creates an async HTTP Request using the global HTTP Client Pool
static void getAsync( const Http::AsyncResponseCallback& cb, const URI& uri, const Time& timeout = Time::Zero, const Request::ProgressCallback& progressCallback = Request::ProgressCallback(), const Request::FieldTable& headers = Request::FieldTable(), const std::string& body = "", const bool& validateCertificate = true, const URI& proxy = URI() )
Creates an async HTTP GET Request using the global HTTP Client Pool
static void postAsync( const Http::AsyncResponseCallback& cb, const URI& uri, const Time& timeout = Time::Zero, const Request::ProgressCallback& progressCallback = Request::ProgressCallback(), const Request::FieldTable& headers = Request::FieldTable(), const std::string& body = "", const bool& validateCertificate = true, const URI& proxy = URI() )
Creates an async HTTP POST Request using the global HTTP Client Pool
static URI getEnvProxyURI()
It will try to get the proxy from the environment variables.
static void setThreadPool(std::shared_ptr<ThreadPool> pool)
Set the thread pool to consume for async requests, otherwise it will use its own