Vidalia 0.2.12

TorEvents.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
00004 **  you did not receive the LICENSE file with this file, you may obtain it
00005 **  from the 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
00008 **  the terms described in the LICENSE file.
00009 */
00010 
00011 /*
00012 ** \file TorEvents.h
00013 ** \brief Parses and dispatches events from Tor
00014 */
00015 
00016 #ifndef _TOREVENTS_H
00017 #define _TOREVENTS_H
00018 
00019 #include "tcglobal.h"
00020 
00021 #include <QObject>
00022 #include <QMultiHash>
00023 #include <QList>
00024 #include <QFlags>
00025 
00026 class Circuit;
00027 class Stream;
00028 class BootstrapStatus;
00029 class ControlReply;
00030 class ReplyLine;
00031 
00032 class QString;
00033 class QDateTime;
00034 class QHostAddress;
00035 
00036 
00037 class TorEvents : public QObject
00038 {
00039   Q_OBJECT
00040 
00041 public:
00042   /** Asynchronous events sent from Tor to the controller */
00043   enum Event {
00044     Unknown       = 0,
00045     Bandwidth     = (1u << 0),
00046     LogDebug      = (1u << 1),
00047     LogInfo       = (1u << 2),
00048     LogNotice     = (1u << 3),
00049     LogWarn       = (1u << 4),
00050     LogError      = (1u << 5),
00051     CircuitStatus = (1u << 6),
00052     StreamStatus  = (1u << 7),
00053     OrConnStatus  = (1u << 8),
00054     NewDescriptor = (1u << 9),
00055     AddressMap    = (1u << 10),
00056     GeneralStatus = (1u << 11),
00057     ClientStatus  = (1u << 12),
00058     ServerStatus  = (1u << 13)
00059   };
00060   static const Event EVENT_MIN = TorEvents::Bandwidth;
00061   static const Event EVENT_MAX = TorEvents::ServerStatus;
00062   Q_DECLARE_FLAGS(Events, Event);
00063 
00064   /** Default Constructor */
00065   TorEvents(QObject *parent = 0);
00066 
00067   /** Parses an event message and emits the proper signal */
00068   void handleEvent(const ControlReply &reply);
00069 
00070   /** Converts an Event to a string */
00071   static QString toString(TorEvents::Event e);
00072 
00073 signals:
00074   /** Emitted when Tor writes the message <b>msg</b> to the control port
00075    * with message severity <b>level</b>.
00076    */
00077   void logMessage(tc::Severity level, const QString &msg);
00078 
00079   /** Emitted when Tor sends a bandwidth usage update (roughly once every
00080    * second). <b>bytesReceived</b> is the number of bytes read by Tor over
00081    * the previous second and <b>bytesWritten</b> is the number of bytes
00082    * sent over the same interval.
00083    */
00084   void bandwidthUpdate(quint64 bytesReceived, quint64 bytesSent);
00085 
00086   /** Emitted when the stream status of <b>stream</b> has changed.
00087    */
00088   void streamStatusChanged(const Stream &stream);
00089 
00090   /** Emitted when the circuit status of <b>circuit</b> has changed.
00091    */
00092   void circuitStatusChanged(const Circuit &circuit);
00093 
00094   /** Emitted when Tor has mapped the address <b>from</b> to the address
00095    * <b>to</b>. <b>expires</b> indicates the time at which when the address
00096    * mapping will no longer be considered valid.
00097    */
00098   void addressMapped(const QString &from, const QString &to,
00099                      const QDateTime &expires);
00100 
00101   /** Emitted when Tor has received one or more new router descriptors.
00102    * <b>ids</b> contains a list of digests of the new descriptors.
00103    */
00104   void newDescriptors(const QStringList &ids);
00105 
00106   /** Indicates Tor has been able to successfully establish one or more
00107    * circuits.
00108    */
00109   void circuitEstablished();
00110 
00111   /** Indicates that Tor has decided the user's Tor software <b>version</b>
00112    * is no longer recommended for some <b>reason</b>. <b>recommended</b> is
00113    * a list of Tor software versions that are considered current.
00114    */
00115   void dangerousTorVersion(tc::TorVersionStatus reason,
00116                            const QString &version,
00117                            const QStringList &recommended);
00118 
00119   /** Emitted during Tor's startup process to indicate how far in its
00120    * bootstrapping process it has progressed. <b>status</b> may indicate
00121    * the current bootstrapping stage or an error during bootstrapping.
00122    */
00123   void bootstrapStatusChanged(const BootstrapStatus &status);
00124 
00125   /** Emitted when the user attempts to establish a connection to some
00126    * destination on port <b>port</b>, which is a port known to use
00127    * plaintext connections (as determined by Tor's WarnPlaintextPorts and
00128    * RejectPlaintextPorts torrc options). <b>rejected</b> indicates whether
00129    * Tor rejected the connection or permitted it to connect anyway.
00130    */
00131   void dangerousPort(quint16 port, bool rejected);
00132 
00133   /** Emitted when Tor detects a problem with a SOCKS connection from the
00134    * user, such as a bad hostname, dangerous SOCKS protocol type, or a bad
00135    * hostname. <b>type</b> indicates the type of error encountered and
00136    * <b>destination</b> (if non-empty) specifies the attempted connection
00137    * destination address or hostname.
00138    */
00139   void socksError(tc::SocksError error, const QString &destination);
00140 
00141   /** Emitted when Tor has encountered an internal bug. <b>reason</b> is
00142    * Tor's description of the bug.
00143    */
00144   void bug(const QString &reason);
00145 
00146   /** Emitted when Tor decides the client's external IP address has changed
00147    * to <b>ip</b>. If <b>hostname</b> is non-empty, Tor obtained the new
00148    * value for <b>ip</b> by resolving <b>hostname</b>. 
00149    */
00150   void externalAddressChanged(const QHostAddress &ip, const QString &hostname);
00151 
00152   /** Indicates that Tor has determined the client's clock is potentially
00153    * skewed by <b>skew</b> seconds relative to <b>source</b>.
00154    */
00155   void clockSkewed(int skew, const QString &source);
00156 
00157   /** Emitted when Tor determines that the user's DNS provider is providing
00158    * an address for non-existent domains when it should really be saying
00159    * "NXDOMAIN".
00160    */
00161   void dnsHijacked();
00162 
00163   /** Emitted when Tor determines that the user's DNS provider is providing
00164    * a hijacked address even for well-known websites.
00165    */
00166   void dnsUseless();
00167 
00168   /** Indicates Tor has started testing the reachability of its OR port 
00169    * using the IP address <b>ip</b> and port <b>port</b>.
00170    */
00171   void checkingOrPortReachability(const QHostAddress &ip, quint16 port);
00172 
00173   /** Tor has completed testing the reachability of its OR port using
00174    * the IP address <b>ip</b> and port <b>port</b>. If the user's OR port
00175    * was reachable, <b>reachable</b> will be set to true.
00176    */
00177   void orPortReachabilityFinished(const QHostAddress &ip, quint16 port,
00178                                   bool reachable);
00179 
00180   /** Indicates Tor has started testing the reachability of its directory
00181    * port using the IP address <b>ip</b> and port <b>port</b>.
00182    */
00183   void checkingDirPortReachability(const QHostAddress &ip, quint16 port);
00184 
00185   /** Tor has completed testing the reachability of its directory port using
00186    * the IP address <b>ip</b> and port <b>port</b>. If the user's directory
00187    * port was reachable, <b>reachable</b> will be set to true.
00188    */
00189   void dirPortReachabilityFinished(const QHostAddress &ip, quint16 port,
00190                                    bool reachable);
00191 
00192   /** Emitted when the directory authority with IP address <b>ip</b> and
00193    * port <b>port</b> rejected the user's server descriptor. <b>reason</b>
00194    * describes why the descriptor was rejected (e.g., malformed, skewed
00195    * clock, etc.).
00196    */
00197   void serverDescriptorRejected(const QHostAddress &ip, quint16 port,
00198                                 const QString &reason);
00199 
00200   /** Emitted when the directory authority with IP address <b>ip</b> and
00201    * port <b>port</b> accepted the user's server descriptor.
00202    */
00203   void serverDescriptorAccepted(const QHostAddress &ip, quint16 port);
00204 
00205   /** Emitted when at least one directory authority has accepted the user's
00206    * server descriptor.
00207    */
00208   void serverDescriptorAccepted();
00209 
00210 private:
00211   /** Parses the event type from the event message */
00212   static Event parseEventType(const ReplyLine &line);
00213   /** Converts a string to an Event */
00214   static Event toTorEvent(const QString &event);
00215   /** Splits a string in the form "IP:PORT" into a QHostAddress and quint16
00216    * pair. If either portion is invalid, a default-constructed QPair() is
00217    * returned. */
00218    static QPair<QHostAddress,quint16> splitAddress(const QString &address);
00219   
00220   /** Handle a bandwidth update event */
00221   void handleBandwidthUpdate(const ReplyLine &line);
00222   /** Handle a circuit status event */
00223   void handleCircuitStatus(const ReplyLine &line);
00224   /** Handle a stream status event */
00225   void handleStreamStatus(const ReplyLine &line);
00226   /** Handle a log message event */
00227   void handleLogMessage(const ReplyLine &line);
00228   /** Handle an OR connection status event. */
00229   void handleOrConnStatus(const ReplyLine &line);
00230   /** Handles a new list of descriptors event. */
00231   void handleNewDescriptor(const ReplyLine &line);
00232   /** Handles a new or updated address map event. */
00233   void handleAddressMap(const ReplyLine &line);
00234 
00235   /** Handles a Tor status event. */
00236   void handleStatusEvent(Event type, const ReplyLine &line);
00237   /** Parses and posts a general Tor status event. */
00238   void handleGeneralStatusEvent(tc::Severity severity,
00239                                 const QString &action,
00240                                 const QHash<QString,QString> &args);
00241   /** Parses and posts a Tor client status event. */
00242   void handleClientStatusEvent(tc::Severity severity,
00243                                const QString &action,
00244                                const QHash<QString,QString> &args);
00245   /** Parses and posts a Tor server status event. */
00246   void handleServerStatusEvent(tc::Severity severity,
00247                                const QString &action,
00248                                const QHash<QString,QString> &args);
00249 };
00250 
00251 Q_DECLARE_OPERATORS_FOR_FLAGS(TorEvents::Events)
00252 
00253 #endif
00254