Vidalia 0.2.12

BridgeDownloader.h

Go to the documentation of this file.
00001 /*
00002 **  This file is part of Vidalia, and is subject to the license terms in the
00003 **  LICENSE file, found in the top level directory of this distribution. If you
00004 **  did not receive the LICENSE file with this file, you may obtain it from the
00005 **  Vidalia source package distributed by the Vidalia Project at
00006 **  http://www.vidalia-project.net/. No part of Vidalia, including this file,
00007 **  may be copied, modified, propagated, or distributed except according to the
00008 **  terms described in the LICENSE file.
00009 */
00010 
00011 /*
00012 ** \file BridgeDownloader.h
00013 ** \brief Downloads a list of new bridge addresses via HTTPS
00014 */
00015 
00016 #ifndef _BRIDGEDOWNLOADER_H
00017 #define _BRIDGEDOWNLOADER_H
00018 
00019 #include <QHttp>
00020 #include <QSslError>
00021 #include <QStringList>
00022 
00023 
00024 class BridgeDownloader : public QObject
00025 {
00026   Q_OBJECT
00027 
00028 public:
00029   /** Available bridge download methods. */
00030   enum BridgeDownloadMethod {
00031     DownloadMethodHttps, /** Download via an HTTPS connection. */
00032   };
00033 
00034   /** Default constructor.
00035    */
00036   BridgeDownloader(QObject *parent = 0);
00037 
00038   /** Initiates a request for a set of bridges using the specified
00039    * download <b>method</b>. Returns true if the request was initiated
00040    * successfully, or false on error.
00041    */
00042   bool downloadBridges(BridgeDownloadMethod method);
00043 
00044   /** Enables HTTPS proxy support, using the proxy server <b>host</b> on
00045    * port <b>port</b>. A <b>username</b> and <b>password</b> can also
00046    * optionally be supplied, if required by the proxy.
00047    */
00048   void setProxy(const QString &host, int port,
00049                 const QString &username = QString(),
00050                 const QString &password = QString());
00051 
00052   /** Returns true if <b>method</b> is supported by the currently
00053    * available Qt libraries.
00054    */
00055   static bool isMethodSupported(BridgeDownloadMethod method);
00056 
00057 public slots:
00058   /** Cancels any pending bridge download requests.
00059    */
00060   void cancelBridgeRequest();
00061 
00062 signals:
00063   /** Emitted when the underlying QHttp object reads data from an HTTPS
00064    * response. <b>done</b> indicates how many bytes out of <b>total</b>
00065    * have been read so far. Note that <b>total</b> may be 0 if the expected
00066    * total size of the response is not known.
00067    */
00068   void downloadProgress(int done, int total);
00069 
00070   /** Emitted when the status of the bridge request changes. <b>status</b>
00071    * describes the new current state of the request.
00072    */
00073   void statusChanged(const QString &status);
00074 
00075   /** Emitted when the previous request for bridge addresses completes
00076    * successfully. The QStringList <b>bridges</b> contains a (possibly empty)
00077    * list of bridge addresses parsed from the received response.
00078    */
00079   void bridgeRequestFinished(const QStringList &bridges);
00080 
00081   /** Emitted when the previous request for bridge addresses fails. The
00082    * QString <b>error</b> is a human-readable string describing the error
00083    * encountered.
00084    */
00085   void bridgeRequestFailed(const QString &error);
00086 
00087 private slots:
00088   /** Called when the state of the underlying QHttp object changes. A
00089    * statusChanged() signal is emitted with the appropriate text
00090    * describing the new state of the request.
00091    */
00092   void httpsStateChanged(int state); 
00093 
00094   /** Called when the underlying QHttp object used to make the bridge
00095    * request completes. <b>error</b> is set to false if the request was
00096    * successful, or true if the request failed. If <b>id</b> does not
00097    * match the request ID previously returned by QHttp::get(), then the
00098    * signal is ignored since it is the result of a close() or abort()
00099    * request.
00100    */
00101   void httpsRequestFinished(int id, bool error);
00102 
00103   /** Called when the HTTPS connection encounters one or more
00104    * <b>sslErrors</b>. Currently the errors are just logged and
00105    * bridgeRequestFailed() is <i>not</i> emitted, since QHttp will also
00106    * emit 
00107    */
00108   void sslErrors(const QList<QSslError> &sslErrors);
00109 
00110 private:
00111   /** Initiates an HTTPS connection to bridges.torproject.org to start
00112    * downloading a set of bridges.
00113    */
00114   void startHttpsDownload();
00115 
00116   /** Used to connect to the bridge database, send an HTTPS request for
00117    * new bridge addresses and then read the response. */
00118   QHttp* _https;
00119   
00120   /** Unique numeric identifier of the current bridge request. */
00121   int _requestId;
00122 };
00123 
00124 #endif
00125