.. index:: pair: class; EE::Network::Http .. _doxid-class_e_e_1_1_network_1_1_http: class EE::Network::Http ======================= .. toctree:: :hidden: class_EE_Network_Http_AsyncRequest.rst class_EE_Network_Http_HttpConnection.rst class_EE_Network_Http_MultipartEntitiesBuilder.rst class_EE_Network_Http_Pool.rst class_EE_Network_Http_Request.rst class_EE_Network_Http_Response.rst Overview ~~~~~~~~ A HTTP client. :ref:`More...` .. ref-code-block:: cpp :class: doxyrest-overview-code-block #include class Http: private :ref:`EE::NonCopyable` { public: // typedefs typedef std::function`&, :ref:`Http::Response`&)> :ref:`AsyncResponseCallback`; // classes class :ref:`AsyncRequest`; class :ref:`HttpConnection`; class :ref:`MultipartEntitiesBuilder`; class :ref:`Pool`; class :ref:`Request`; class :ref:`Response`; // construction :ref:`Http`(); :ref:`Http`(const std::string& host, unsigned short port = 0, bool useSSL = false, :ref:`URI` proxy = :ref:`URI`()); :target:`~Http`(); // methods void :ref:`setHost`(const std::string& host, unsigned short port = 0, bool useSSL = false, :ref:`URI` proxy = :ref:`URI`()); :ref:`Response` :ref:`sendRequest`(const :ref:`Request`& request, :ref:`Time` timeout = Time::Zero); :ref:`Response` :ref:`downloadRequest`(const :ref:`Request`& request, :ref:`IOStream`& writeTo, :ref:`Time` timeout = Time::Zero); :ref:`Response` :ref:`downloadRequest`(const :ref:`Request`& request, std::string writePath, :ref:`Time` timeout = Time::Zero); void :ref:`sendAsyncRequest`(const :ref:`AsyncResponseCallback`& cb, const :ref:`Http::Request`& request, :ref:`Time` timeout = Time::Zero); void :ref:`downloadAsyncRequest`(const :ref:`AsyncResponseCallback`& cb, const :ref:`Http::Request`& request, :ref:`IOStream`& writeTo, :ref:`Time` timeout = Time::Zero); void :ref:`downloadAsyncRequest`(const :ref:`AsyncResponseCallback`& cb, const :ref:`Http::Request`& request, std::string writePath, :ref:`Time` timeout = Time::Zero); const :ref:`IpAddress`& :ref:`getHost`() const; const std::string& :ref:`getHostName`() const; const unsigned short& :ref:`getPort`() const; const bool& :ref:`isSSL`() const; :ref:`URI` :ref:`getURI`() const; void :ref:`setProxy`(const :ref:`URI`& uri); const :ref:`URI`& :ref:`getProxy`() const; bool :ref:`isProxied`() const; static :ref:`Response` :ref:`request`( const :ref:`URI`& uri, :ref:`Request::Method` method = Request::Method::Get, const :ref:`Time`& timeout = Time::Zero, const :ref:`Request::ProgressCallback`& progressCallback = :ref:`Request::ProgressCallback`(), const :ref:`Request::FieldTable`& headers = :ref:`Request::FieldTable`(), const std::string& body = "", const bool& validateCertificate = true, const :ref:`URI`& proxy = :ref:`URI`() ); static :ref:`Response` :ref:`get`( const :ref:`URI`& uri, const :ref:`Time`& timeout = Time::Zero, const :ref:`Request::ProgressCallback`& progressCallback = :ref:`Request::ProgressCallback`(), const :ref:`Request::FieldTable`& headers = :ref:`Request::FieldTable`(), const std::string& body = "", const bool& validateCertificate = true, const :ref:`URI`& proxy = :ref:`URI`() ); static :ref:`Response` :ref:`post`( const :ref:`URI`& uri, const :ref:`Time`& timeout = Time::Zero, const :ref:`Request::ProgressCallback`& progressCallback = :ref:`Request::ProgressCallback`(), const :ref:`Request::FieldTable`& headers = :ref:`Request::FieldTable`(), const std::string& body = "", const bool& validateCertificate = true, const :ref:`URI`& proxy = :ref:`URI`() ); static void :ref:`requestAsync`( const :ref:`Http::AsyncResponseCallback`& cb, const :ref:`URI`& uri, const :ref:`Time`& timeout = Time::Zero, :ref:`Request::Method` method = Request::Method::Get, const :ref:`Request::ProgressCallback`& progressCallback = :ref:`Request::ProgressCallback`(), const :ref:`Request::FieldTable`& headers = :ref:`Request::FieldTable`(), const std::string& body = "", const bool& validateCertificate = true, const :ref:`URI`& proxy = :ref:`URI`() ); static void :ref:`getAsync`( const :ref:`Http::AsyncResponseCallback`& cb, const :ref:`URI`& uri, const :ref:`Time`& timeout = Time::Zero, const :ref:`Request::ProgressCallback`& progressCallback = :ref:`Request::ProgressCallback`(), const :ref:`Request::FieldTable`& headers = :ref:`Request::FieldTable`(), const std::string& body = "", const bool& validateCertificate = true, const :ref:`URI`& proxy = :ref:`URI`() ); static void :ref:`postAsync`( const :ref:`Http::AsyncResponseCallback`& cb, const :ref:`URI`& uri, const :ref:`Time`& timeout = Time::Zero, const :ref:`Request::ProgressCallback`& progressCallback = :ref:`Request::ProgressCallback`(), const :ref:`Request::FieldTable`& headers = :ref:`Request::FieldTable`(), const std::string& body = "", const bool& validateCertificate = true, const :ref:`URI`& proxy = :ref:`URI`() ); static :ref:`URI` :ref:`getEnvProxyURI`(); static void :ref:`setThreadPool`(std::shared_ptr<:ref:`ThreadPool`> pool); }; .. _details-class_e_e_1_1_network_1_1_http: Detailed Documentation ~~~~~~~~~~~~~~~~~~~~~~ A HTTP client. :ref:`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: * :ref:`EE::Network::Http::Request ` * :ref:`EE::Network::Http::Response ` * :ref:`EE::Network::Http ` :ref:`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 :ref:`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) :ref:`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 :ref:`Http ` provides a simple function, sendRequest, to send a :ref:`EE::Network::Http::Request ` and return the corresponding :ref:`EE::Network::Http::Response ` from the server. Usage example: .. ref-code-block:: cpp // 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: .. ref-code-block:: cpp 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: .. ref-code-block:: cpp 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 -------- .. index:: pair: typedef; AsyncResponseCallback .. _doxid-class_e_e_1_1_network_1_1_http_1adeb2e1857ef87bea198564e4d47c56ba: .. ref-code-block:: cpp :class: doxyrest-title-code-block typedef std::function`&, :ref:`Http::Response`&)> AsyncResponseCallback Definition of the async callback response Construction ------------ .. index:: pair: function; Http .. _doxid-class_e_e_1_1_network_1_1_http_1a1c886357579ed76daa4da38eb8d4458e: .. ref-code-block:: cpp :class: doxyrest-title-code-block Http() Default constructor. .. index:: pair: function; Http .. _doxid-class_e_e_1_1_network_1_1_http_1a447a9ab7dd27986b8444f625b6e32b22: .. ref-code-block:: cpp :class: doxyrest-title-code-block Http(const std::string& host, unsigned short port = 0, bool useSSL = false, :ref:`URI` proxy = :ref:`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. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - host - Web server to connect to * - port - Port to use for connection * - useSSL - force the :ref:`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 ------- .. index:: pair: function; setHost .. _doxid-class_e_e_1_1_network_1_1_http_1a372c35f1e8355c07e85d483c2c46e157: .. ref-code-block:: cpp :class: doxyrest-title-code-block void setHost(const std::string& host, unsigned short port = 0, bool useSSL = false, :ref:`URI` proxy = :ref:`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. .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - host - Web server to connect to * - port - Port to use for connection * - useSSL - force the :ref:`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 .. index:: pair: function; sendRequest .. _doxid-class_e_e_1_1_network_1_1_http_1a3e6e28487b022ddaa837babbcbbbfa31: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`Response` sendRequest(const :ref:`Request`& request, :ref:`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). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - request - :ref:`Request ` to send * - timeout - Maximum time to wait .. rubric:: Returns: Server's response .. index:: pair: function; downloadRequest .. _doxid-class_e_e_1_1_network_1_1_http_1a0b362079a25e4b2ffb2ca4f7627995f0: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`Response` downloadRequest(const :ref:`Request`& request, :ref:`IOStream`& writeTo, :ref:`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). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - request - :ref:`Request ` to send * - writeTo - The IO stream to write the downloaded content * - timeout - Maximum time to wait .. rubric:: Returns: Server's response .. index:: pair: function; downloadRequest .. _doxid-class_e_e_1_1_network_1_1_http_1a65f70a11da301436c0f18b74e73e4f84: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`Response` downloadRequest(const :ref:`Request`& request, std::string writePath, :ref:`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). .. rubric:: Parameters: .. list-table:: :widths: 20 80 * - request - :ref:`Request ` to send * - writePath - The path of the file to write the downloaded content * - timeout - Maximum time to wait .. rubric:: Returns: Server's response .. index:: pair: function; sendAsyncRequest .. _doxid-class_e_e_1_1_network_1_1_http_1afbd46187947b65663878772755dc21a1: .. ref-code-block:: cpp :class: doxyrest-title-code-block void sendAsyncRequest(const :ref:`AsyncResponseCallback`& cb, const :ref:`Http::Request`& request, :ref:`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. .. rubric:: See also: :ref:`sendRequest ` .. index:: pair: function; downloadAsyncRequest .. _doxid-class_e_e_1_1_network_1_1_http_1ac1303e9d8c0cd3f93410e3e2d81b2df2: .. ref-code-block:: cpp :class: doxyrest-title-code-block void downloadAsyncRequest(const :ref:`AsyncResponseCallback`& cb, const :ref:`Http::Request`& request, :ref:`IOStream`& writeTo, :ref:`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. .. rubric:: See also: :ref:`downloadRequest ` .. index:: pair: function; downloadAsyncRequest .. _doxid-class_e_e_1_1_network_1_1_http_1a2dc8e402bbade61f702c2e7d011ba639: .. ref-code-block:: cpp :class: doxyrest-title-code-block void downloadAsyncRequest(const :ref:`AsyncResponseCallback`& cb, const :ref:`Http::Request`& request, std::string writePath, :ref:`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. .. rubric:: See also: :ref:`downloadRequest ` .. index:: pair: function; getHost .. _doxid-class_e_e_1_1_network_1_1_http_1affb922af2ff6f69a72ad5eaff23b6647: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`IpAddress`& getHost() const .. rubric:: Returns: The host address .. index:: pair: function; getHostName .. _doxid-class_e_e_1_1_network_1_1_http_1a7c0e2884e81b932d2e9914734f26ef48: .. ref-code-block:: cpp :class: doxyrest-title-code-block const std::string& getHostName() const .. rubric:: Returns: The host name .. index:: pair: function; getPort .. _doxid-class_e_e_1_1_network_1_1_http_1afae0aabe402df258a8137def39d0f4b6: .. ref-code-block:: cpp :class: doxyrest-title-code-block const unsigned short& getPort() const .. rubric:: Returns: The host port .. index:: pair: function; isSSL .. _doxid-class_e_e_1_1_network_1_1_http_1acd01b37c1ef923349f8eff58209ea0a4: .. ref-code-block:: cpp :class: doxyrest-title-code-block const bool& isSSL() const .. rubric:: Returns: If the HTTP client uses SSL/TLS .. index:: pair: function; getURI .. _doxid-class_e_e_1_1_network_1_1_http_1af6a6891bbbf83e231294e2ae78ad9f34: .. ref-code-block:: cpp :class: doxyrest-title-code-block :ref:`URI` getURI() const .. rubric:: Returns: The :ref:`URI ` from the schema + hostname + port .. index:: pair: function; setProxy .. _doxid-class_e_e_1_1_network_1_1_http_1aa7b537a6b327f2b490b7304a6c445237: .. ref-code-block:: cpp :class: doxyrest-title-code-block void setProxy(const :ref:`URI`& uri) Sets the request proxy .. index:: pair: function; getProxy .. _doxid-class_e_e_1_1_network_1_1_http_1ac80f6887f871354e9f06564f37ce4fcf: .. ref-code-block:: cpp :class: doxyrest-title-code-block const :ref:`URI`& getProxy() const .. rubric:: Returns: The request proxy .. index:: pair: function; isProxied .. _doxid-class_e_e_1_1_network_1_1_http_1a64887ec03c6996e34c56b0d4ed9ddbab: .. ref-code-block:: cpp :class: doxyrest-title-code-block bool isProxied() const .. rubric:: Returns: Is a proxy is need to be used .. index:: pair: function; request .. _doxid-class_e_e_1_1_network_1_1_http_1a0badd44b1f410b7053d7db5413e876c6: .. ref-code-block:: cpp :class: doxyrest-title-code-block static :ref:`Response` request( const :ref:`URI`& uri, :ref:`Request::Method` method = Request::Method::Get, const :ref:`Time`& timeout = Time::Zero, const :ref:`Request::ProgressCallback`& progressCallback = :ref:`Request::ProgressCallback`(), const :ref:`Request::FieldTable`& headers = :ref:`Request::FieldTable`(), const std::string& body = "", const bool& validateCertificate = true, const :ref:`URI`& proxy = :ref:`URI`() ) Creates an HTTP :ref:`Request ` using the global HTTP Client :ref:`Pool ` .. index:: pair: function; get .. _doxid-class_e_e_1_1_network_1_1_http_1a01f9cbc91957ad3706b1de12c698ef52: .. ref-code-block:: cpp :class: doxyrest-title-code-block static :ref:`Response` get( const :ref:`URI`& uri, const :ref:`Time`& timeout = Time::Zero, const :ref:`Request::ProgressCallback`& progressCallback = :ref:`Request::ProgressCallback`(), const :ref:`Request::FieldTable`& headers = :ref:`Request::FieldTable`(), const std::string& body = "", const bool& validateCertificate = true, const :ref:`URI`& proxy = :ref:`URI`() ) Creates an HTTP GET :ref:`Request ` using the global HTTP Client :ref:`Pool ` .. index:: pair: function; post .. _doxid-class_e_e_1_1_network_1_1_http_1aa2854f0f0a999da19fd16c1acef15de7: .. ref-code-block:: cpp :class: doxyrest-title-code-block static :ref:`Response` post( const :ref:`URI`& uri, const :ref:`Time`& timeout = Time::Zero, const :ref:`Request::ProgressCallback`& progressCallback = :ref:`Request::ProgressCallback`(), const :ref:`Request::FieldTable`& headers = :ref:`Request::FieldTable`(), const std::string& body = "", const bool& validateCertificate = true, const :ref:`URI`& proxy = :ref:`URI`() ) Creates an HTTP POST :ref:`Request ` using the global HTTP Client :ref:`Pool ` .. index:: pair: function; requestAsync .. _doxid-class_e_e_1_1_network_1_1_http_1a304a791f878781e27eaf36295daac5a9: .. ref-code-block:: cpp :class: doxyrest-title-code-block static void requestAsync( const :ref:`Http::AsyncResponseCallback`& cb, const :ref:`URI`& uri, const :ref:`Time`& timeout = Time::Zero, :ref:`Request::Method` method = Request::Method::Get, const :ref:`Request::ProgressCallback`& progressCallback = :ref:`Request::ProgressCallback`(), const :ref:`Request::FieldTable`& headers = :ref:`Request::FieldTable`(), const std::string& body = "", const bool& validateCertificate = true, const :ref:`URI`& proxy = :ref:`URI`() ) Creates an async HTTP :ref:`Request ` using the global HTTP Client :ref:`Pool ` .. index:: pair: function; getAsync .. _doxid-class_e_e_1_1_network_1_1_http_1a7b11f078f954c2f4bb5a381cf6452cda: .. ref-code-block:: cpp :class: doxyrest-title-code-block static void getAsync( const :ref:`Http::AsyncResponseCallback`& cb, const :ref:`URI`& uri, const :ref:`Time`& timeout = Time::Zero, const :ref:`Request::ProgressCallback`& progressCallback = :ref:`Request::ProgressCallback`(), const :ref:`Request::FieldTable`& headers = :ref:`Request::FieldTable`(), const std::string& body = "", const bool& validateCertificate = true, const :ref:`URI`& proxy = :ref:`URI`() ) Creates an async HTTP GET :ref:`Request ` using the global HTTP Client :ref:`Pool ` .. index:: pair: function; postAsync .. _doxid-class_e_e_1_1_network_1_1_http_1a9bcabb0dd8df86fefbb16865e0f5e318: .. ref-code-block:: cpp :class: doxyrest-title-code-block static void postAsync( const :ref:`Http::AsyncResponseCallback`& cb, const :ref:`URI`& uri, const :ref:`Time`& timeout = Time::Zero, const :ref:`Request::ProgressCallback`& progressCallback = :ref:`Request::ProgressCallback`(), const :ref:`Request::FieldTable`& headers = :ref:`Request::FieldTable`(), const std::string& body = "", const bool& validateCertificate = true, const :ref:`URI`& proxy = :ref:`URI`() ) Creates an async HTTP POST :ref:`Request ` using the global HTTP Client :ref:`Pool ` .. index:: pair: function; getEnvProxyURI .. _doxid-class_e_e_1_1_network_1_1_http_1a337b5075afe4c829892e613efbf44fc9: .. ref-code-block:: cpp :class: doxyrest-title-code-block static :ref:`URI` getEnvProxyURI() It will try to get the proxy from the environment variables. .. index:: pair: function; setThreadPool .. _doxid-class_e_e_1_1_network_1_1_http_1af2c9d1a2c230f59210b39f92238fd427: .. ref-code-block:: cpp :class: doxyrest-title-code-block static void setThreadPool(std::shared_ptr<:ref:`ThreadPool`> pool) Set the thread pool to consume for async requests, otherwise it will use its own