Wt: Wt::Http::Client Class Reference

Wt 3.3.0

- Main Page
- Related Pages
- Modules
- Namespaces
- Classes

- Class List
- Class Hierarchy
- Class Members

Classes | Public Member Functions | Static Public Member Functions
Wt::Http::Client Class Reference
HTTP protocol (Wt::Http)

An HTTP client. More...

`#include <Wt/Http/Client>`

Inheritance diagram for Wt::Http::Client:
[legend]

List of all members.

## Classes
struct | URL
| Utility class representing an URL. More...
## Public Member Functions
| Client (WObject *parent=0)
| Default constructor.
| Client (WIOService &ioService, WObject *parent=0)
| Constructor.
virtual | ~Client ()
| Destructor.
void | setTimeout (int seconds)
| Sets an I/O timeout.
int | timeout () const
| Returns the I/O timeout.
void | setMaximumResponseSize (std::size_t bytes)
| Sets a maximum response size.
std::size_t | maximumResponseSize () const
| Returns the maximum response size.
void | setSslVerifyFile (const std::string &verifyFile)
| Sets a SSL certificate used for server identity verification.
void | setSslVerifyPath (const std::string &verifyPath)
| Sets a path with SSL certificates for server identity verification.
bool | get (const std::string &url)
| Starts a GET request.
bool | get (const std::string &url, const std::vector< Message::Header > headers)
| Starts a GET request.
bool | post (const std::string &url, const Message &message)
| Starts a POST request.
bool | put (const std::string &url, const Message &message)
| Starts a PUT request.
bool | deleteRequest (const std::string &url, const Message &message)
| Starts a DELETE request.
bool | request (Http::Method method, const std::string &url, const Message &message)
| Starts a request.
void | abort ()
| Aborts the curent request.
Signal < boost::system::error_code, Message > & | done ()
| Signal that is emitted when the current request is done.
## Static Public Member Functions
static bool | parseUrl (const std::string &url, URL &parsedUrl)
| Utility method to parse a URL.

## Detailed Description

An HTTP client.

This class implements an HTTP client. It can be used to interact with web services using the HTTP protocol.

The client uses asynchronous I/O and only provides an asynchronous interface: you cannot actively wait for an operation to complete, instead the client will notify you of the result using the done() signal.

Because the client uses asynchronous I/O, it does its work within the scope of an event-driven thread pool implementation. By default, this is the same thread pool that is used by the Wt server, available through WServer::ioService(), but you may also use the client by providing it an explicit I/O service to be used.

The client supports the HTTP and HTTPS (if Wt was built with OpenSSL support) protocols, and can be used for GET and POST methods. One client can do only one operation at a time.

Usage example:

        ...
        Http::Client *client = new Http::Client(this);
        client->setTimeout(15);
        client->setMaximumResponseSize(10 * 1024);
        client->done().connect(boost::bind(&MyWidget::handleHttpResponse, this, _1, _2));
        if (client->get("http://www.webtoolkit.eu/wt/blog/feed/"))
          WApplication::instance()->deferRendering();
        } else {
          // in case of an error in the %URL
        }
     }

     void handleHttpResponse(boost::system::error_code err, const Http::Message& response)
     {
        WApplication::instance()->resumeRendering();

        if (!err && response.status() == 200) {
           ... parse response.body()
        }
     }

The function connected to the done() signal will be run within the context of the application that created the client. WServer::post() is used for this.

## Constructor & Destructor Documentation

Wt::Http::Client::Client | ( | WObject * | parent = `0` | ) |

Default constructor.

The client uses the I/O service and thread-pool from the current WApplication::instance().

Wt::Http::Client::Client | ( | WIOService & | ioService,
|  | WObject * | parent = `0`
| ) |  |

Constructor.

The client uses the given I/O service and thread-pool, and is useful to use the client outside the context of a web application.

Wt::Http::Client::~Client | ( |  | ) | `[virtual]`

Destructor.

If the client is still busy, the current request is aborted.

See also:
  abort()

## Member Function Documentation

void Wt::Http::Client::abort | ( |  | ) |

Aborts the curent request.

If the client is currently busy, this cancels the pending request. done() will be emitted with an error_code. (FIXME: which one ?)

bool Wt::Http::Client::deleteRequest | ( | const std::string & | url,
|  | const Message & | message
| ) |  |

Starts a DELETE request.

The function starts an asynchronous DELETE request, and returns immediately.

The function returns `true` when the DELETE request has been scheduled, and thus done() will be emitted eventually.

The function returns `false` if the client could not schedule the request, for example if the `url` is invalid or if the URL scheme is not supported.

See also:
  request(), done()

Signal<boost::system::error_code, Message>& Wt::Http::Client::done | ( |  | ) |

Signal that is emitted when the current request is done.

The `error` is 0 if the HTTP request was successful. Then, the `message` contains the result.

If the `error` is not 0, then an error message is given by `error.message()`.

Typical code to process the result is:

     void handle(boost::system::error_code err, const Http::Message& response)
     {
       if (!err) {
         if (response.status() == 200) {
           ... success
         }
       } else {
         Wt::log("error") << "Http::Client error: " << err.message();
       }
     }

bool Wt::Http::Client::get | ( | const std::string & | url | ) |

Starts a GET request.

The function starts an asynchronous GET request, and returns immediately.

The function returns `true` when the GET request has been scheduled, and thus done() will be emitted eventually.

The function returns `false` if the client could not schedule the request, for example if the `url` is invalid or if the URL scheme is not supported.

See also:
  request(), done()

bool Wt::Http::Client::get | ( | const std::string & | url,
|  | const std::vector< Message::Header > | headers
| ) |  |

Starts a GET request.

The function starts an asynchronous GET request, and returns immediately.

The function returns `true` when the GET request has been scheduled, and thus done() will be emitted eventually.

The function returns `false` if the client could not schedule the request, for example if the `url` is invalid or if the URL scheme is not supported.

This function accepts one or more headers.

See also:
  request(), done()

std::size_t Wt::Http::Client::maximumResponseSize | ( |  | ) | const

Returns the maximum response size.

See also:
  setMaximumResponseSize()

bool Wt::Http::Client::parseUrl | ( | const std::string & | url,
|  | URL & | parsedUrl
| ) |  | `[static]`

Utility method to parse a URL.

This parses a URL into an URL object.

The method returns true if the URL could be parsed successfully.

bool Wt::Http::Client::post | ( | const std::string & | url,
|  | const Message & | message
| ) |  |

Starts a POST request.

The function starts an asynchronous POST request, and returns immediately.

The function returns `true` when the POST request has been scheduled, and thus done() will be emitted eventually.

The function returns `false` if the client could not schedule the request, for example if the `url` is invalid or if the URL scheme is not supported.

See also:
  request(), done()

bool Wt::Http::Client::put | ( | const std::string & | url,
|  | const Message & | message
| ) |  |

Starts a PUT request.

The function starts an asynchronous PUT request, and returns immediately.

The function returns `true` when the PUT request has been scheduled, and thus done() will be emitted eventually.

The function returns `false` if the client could not schedule the request, for example if the `url` is invalid or if the URL scheme is not supported.

See also:
  request(), done()

bool Wt::Http::Client::request | ( | Http::Method | method,
|  | const std::string & | url,
|  | const Message & | message
| ) |  |

Starts a request.

The function starts an asynchronous HTTP request, and returns immediately.

The function returns `true` when the request has been scheduled, and thus done() will be emitted eventually.

The function returns `false` if the client could not schedule the request, for example if the `url` is invalid or if the URL scheme is not supported.

See also:
  request(), done()

void Wt::Http::Client::setMaximumResponseSize | ( | std::size_t | bytes | ) |

Sets a maximum response size.

The response is stored in-memory. To avoid a DoS by a malicious downstream HTTP server, the response size is bounded by an upper limit.

The limit includes status line, headers and response body.

The default value is 64 kilo bytes.

void Wt::Http::Client::setSslVerifyFile | ( | const std::string & | verifyFile | ) |

Sets a SSL certificate used for server identity verification.

This setting only affects a https request: it configures a certificate file to be used to verify the identity of the server.

Note:
  Certificate verification does not work reliably yet.

void Wt::Http::Client::setSslVerifyPath | ( | const std::string & | verifyPath | ) |

Sets a path with SSL certificates for server identity verification.

This setting only affects a https request: it configures a directory containing certificates to be used to verify the identity of the server.

Note:
  Certificate verification does not work reliably yet.

void Wt::Http::Client::setTimeout | ( | int | seconds | ) |

Sets an I/O timeout.

This sets a timeout wiating for I/O operations. The timeout does not bound the total timeout, since the timer is reset on each I/O progress.

The default timeout is 10 seconds.

int Wt::Http::Client::timeout | ( |  | ) | const

Returns the I/O timeout.

See also:
  setTimeout()

All Classes Namespaces Functions Variables Typedefs Enumerations Enumerator