git.sur5r.net Git - minitube/blob - src/http/README.md

   1 # A wrapper for the Qt Network Access API
   2
   3 This is just a wrapper around Qt's QNetworkAccessManager and friends. I use it in my Qt apps at http://flavio.tordini.org . It allows me to add missing functionality as needed, e.g.:
   4
   5 - Throttling (as required by many web APIs nowadays)
   6 - Read timeouts (don't let your requests get stuck forever)
   7 - Automatic retries
   8 - User agent and request header defaults
   9 - Partial requests
  10 - Redirection support (now supported by Qt >= 5.6)
  11
  12 It has a simpler, higher-level API that I find easier to work with. The design emerged naturally in years of practical use.
  13
  14 A basic example:
  15
  16 ```
  17 QObject *reply = Http::instance().get("https://google.com/");
  18 connect(reply, SIGNAL(data(QByteArray)), SLOT(onSuccess(QByteArray)));
  19 connect(reply, SIGNAL(error(QString)), SLOT(onError(QString)));
  20
  21 void MyClass::onSuccess(const QByteArray &bytes) {
  22         qDebug() << "Feel the bytes!" << bytes;
  23 }
  24
  25 void MyClass::onError(const QString &message) {
  26         qDebug() << "Something's wrong here" << message;
  27 }
  28 ```
  29
  30 This is a real-world example of building a Http object suitable to a web service. It throttles requests, uses a custom user agent and caches results:
  31
  32 ```
  33 Http &myHttp() {
  34     static Http *http = [] {
  35         Http *http = new Http;
  36         http->addRequestHeader("User-Agent", userAgent());
  37
  38         ThrottledHttp *throttledHttp = new ThrottledHttp(*http);
  39         throttledHttp->setMilliseconds(1000);
  40
  41         CachedHttp *cachedHttp = new CachedHttp(*throttledHttp, "mycache");
  42         cachedHttp->setMaxSeconds(86400 * 30);
  43
  44         return cachedHttp;
  45     }();
  46     return *http;
  47 }
  48 ```
  49
  50 If the full power (and complexity) of QNetworkReply is needed you can always fallback to it:
  51
  52 ```
  53 HttpRequest req;
  54 req.url = "https://flavio.tordini.org/";
  55 QNetworkReply *reply = Http::instance().networkReply(req);
  56 // Use QNetworkReply as needed...
  57 ```
  58
  59 You can use this library under the MIT license and at your own risk. If you do, you're welcome contributing your changes and fixes.
  60
  61 Cheers,
  62
  63 Flavio