torcontrol.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 torcontrol.h
00013 ** \version $Id: torcontrol.h 3900 2009-06-26 23:20:39Z edmanm $
00014 ** \brief Object for interacting with the Tor process and control interface
00015 */
00016 
00017 #ifndef _TORCONTROL_H
00018 #define _TORCONTROL_H
00019 
00020 #include <QObject>
00021 #include <QHash>
00022 #include <QList>
00023 #include <QStringList>
00024 #include <QVariant>
00025 
00026 #include "controlconnection.h"
00027 #include "torprocess.h"
00028 #include "torevents.h"
00029 #include "torsignal.h"
00030 #include "routerdescriptor.h"
00031 #include "routerstatus.h"
00032 #include "bootstrapstatus.h"
00033 #include "addressmap.h"
00034 #include "protocolinfo.h"
00035 
00036 #if defined(Q_OS_WIN32)
00037 #include "torservice.h"
00038 #endif
00039 
00040 
00041 /** DescriptorAnnotations stores a map of annotation keys to (possibly empty)
00042  * annotation values. */
00043 typedef QHash<QString,QString> DescriptorAnnotations;
00044 
00045 
00046 class TorControl : public QObject
00047 {
00048   Q_OBJECT
00049   
00050 public:
00051   /** Default constructor */
00052   TorControl();
00053   /** Default destructor */
00054   ~TorControl();
00055 
00056   /** Start the Tor process */
00057   void start(const QString &tor, const QStringList &args);
00058   /** Stop the Tor process */
00059   bool stop(QString *errmsg = 0);
00060   /** Detect if the Tor process is running */
00061   bool isRunning();
00062   /** Detects if the Tor process is running under Vidalia. */
00063   bool isVidaliaRunningTor();
00064   /** Stops reading log messages from the Tor process's stdout. This has no
00065    * effect if isVidaliaRunningTor() is false. */
00066   void closeTorStdout();
00067 
00068   /** Connect to Tor's control socket */
00069   void connect(const QHostAddress &address, quint16 port);
00070   /** Disconnect from Tor's control socket */
00071   void disconnect();
00072   /** Check if we're connected to Tor's control socket */
00073   bool isConnected();
00074   /** Sends an authentication cookie to Tor. */
00075   bool authenticate(const QByteArray cookie, QString *errmsg = 0);
00076   /** Sends an authentication password to Tor. */
00077   bool authenticate(const QString password = QString(), QString *errmsg = 0);
00078   
00079   /** Sends a PROTOCOLINFO command to Tor and parses the response. */
00080   ProtocolInfo protocolInfo(QString *errmsg = 0);
00081 
00082   /** Returns the Tor software's current bootstrap phase and status. */
00083   BootstrapStatus bootstrapStatus(QString *errmsg = 0);
00084 
00085   /** Returns true if Tor either has an open circuit or (on Tor >= 
00086    * 0.2.0.1-alpha) has previously decided it's able to establish a circuit. */
00087   bool circuitEstablished();
00088 
00089   /** Sends a GETINFO message to Tor based on the given keys */
00090   bool getInfo(QHash<QString,QString> &map, QString *errmsg = 0);
00091   /** Sends a GETINFO message for a single info value to Tor */
00092   bool getInfo(QString key, QString &val, QString *errmsg = 0);
00093 
00094   /** Sends a GETINFO message to Tor using the given list of <b>keys</b> and
00095    * returns a QVariantMap containing the specified keys and their values as
00096    * returned by Tor. Returns a default constructed QVariantMap on failure. */
00097   QVariantMap getInfo(const QStringList &keys, QString *errmsg = 0);
00098   /** Sends a GETINFO message to Tor with a single <b>key</b> and returns a
00099    * QVariant containing the value returned by Tor. Returns a default
00100    * constructed QVariant on failure. */
00101   QVariant getInfo(const QString &key, QString *errmsg = 0);
00102 
00103 
00104   /** Sends a signal to Tor */
00105   bool signal(TorSignal::Signal sig, QString *errmsg = 0);
00106  
00107   /** Returns an address on which Tor is listening for application
00108    * requests. If none are available, a null QHostAddress is returned. */
00109   QHostAddress getSocksAddress(QString *errmsg = 0);
00110   /** Returns a (possibly empty) list of all currently configured 
00111    * SocksListenAddress entries. */
00112   QStringList getSocksAddressList(QString *errmsg = 0);
00113   /** Returns a valid SOCKS port for Tor, or 0 if Tor is not accepting
00114    * application requests. */
00115   quint16 getSocksPort(QString *errmsg = 0);
00116   /** Returns a list of all currently configured SOCKS ports. If Tor is not
00117    * accepting any application connections, an empty list will be returned. */
00118   QList<quint16> getSocksPortList(QString *errmsg = 0);
00119 
00120   /** Returns Tor's version as a string. */
00121   QString getTorVersionString();
00122   /** Returns Tor's version as a numeric value. */
00123   quint32 getTorVersion();
00124 
00125   /** Sets an event and its handler. If add is true, then the event is added,
00126    * otherwise it is removed. If set is true, then the given event will be
00127    * registered with Tor. */
00128   bool setEvent(TorEvents::TorEvent e, QObject *obj, 
00129                 bool add, bool set = true, QString *errmsg = 0);
00130   /** Registers for a set of logging events according to the given filter. */
00131   bool setLogEvents(uint filter, QObject *obj, QString *errmsg = 0);
00132   /** Register events of interest with Tor */
00133   bool setEvents(QString *errmsg = 0);
00134   
00135 
00136   /** Sets each configuration key in <b>map</b> to the value associated with its key. */
00137   bool setConf(QHash<QString,QString> map, QString *errmsg = 0);
00138   /** Sets a single configuration key to the given value. */
00139   bool setConf(QString key, QString value, QString *errmsg = 0);
00140   /** Sets a single configuration string that is formatted <key=escaped value>. */
00141   bool setConf(QString keyAndValue, QString *errmsg = 0);
00142   /** Gets values for a set of configuration keys, each of which has a single
00143    * value. */
00144   bool getConf(QHash<QString,QString> &map, QString *errmsg = 0);
00145   /** Gets a set of configuration keyvalues and stores them in <b>map</b>. */
00146   bool getConf(QHash<QString,QStringList> &map, QString *errmsg = 0);
00147   /** Gets a single configuration value for <b>key</b>. */
00148   bool getConf(QString key, QString &value, QString *errmsg = 0);
00149   /** Gets a list of configuration values for <b>key</b>. */
00150   bool getConf(QString key, QStringList &value, QString *errmsg = 0);
00151 
00152   /** Sends a GETCONF message to Tor using the given list of <b>keys</b> and
00153    * returns a QVariantMap containing the specified keys and their values as
00154    * returned by Tor. Returns a default constructed QVariantMap on failure. */
00155   QVariantMap getConf(const QStringList &keys, QString *errmsg = 0);
00156   /** Sends a GETCONF message to Tor with a single <b>key</b> and returns a
00157    * QVariant containing the value returned by Tor. Returns a default
00158    * constructed QVariant on failure. */
00159   QVariant getConf(const QString &key, QString *errmsg = 0);
00160   /** Sends a GETCONF message to Tor with the single key and returns a QString
00161    * containing the value returned by Tor */
00162   QString getHiddenServiceConf(const QString &key, QString *errmsg = 0);
00163   
00164   /** Asks Tor to save the current configuration to its torrc */
00165   bool saveConf(QString *errmsg = 0);
00166   /** Tells Tor to reset the given configuration keys back to defaults. */
00167   bool resetConf(QStringList keys, QString *errmsg = 0);
00168   /** Tells Tor to reset a configuration key back to its default value. */
00169   bool resetConf(QString key, QString *errmsg = 0);
00170 
00171   /** Returns the descriptor for the router whose fingerprint matches
00172    * <b>id</b>. If <b>id</b> is invalid or the router's descriptor cannot be
00173    * parsed, then an invalid RouterDescriptor is returned. */
00174   RouterDescriptor getRouterDescriptor(const QString &id, QString *errmsg = 0);
00175   /** Returns the status of the router whose fingerprint matches <b>id</b>. If
00176    * <b>id</b> is invalid or the router's status cannot be parsed, then an
00177    * invalid RouterStatus is returned. */
00178   RouterStatus getRouterStatus(const QString &id, QString *errmsg = 0);
00179   /** Returns a RouterStatus object for every known router in the network. If
00180    * the network status document cannot be parsed, then an empty NetworkStatus
00181    * is returned. */
00182   NetworkStatus getNetworkStatus(QString *errmsg = 0);
00183   /** Returns the annotations for the router whose fingerprint matches
00184    * <b>id</b>. If <b>id</b> is invalid or the router's descriptor cannot be
00185    * parsed, then an empty DescriptorAnnotations is returned and
00186    * <b>errmsg</b> is set if it's not NULL. (Tor >= 0.2.0.13-alpha only) */
00187   DescriptorAnnotations getDescriptorAnnotations(const QString &id,
00188                                                  QString *errmsg = 0);
00189 
00190   /** Gets a list of current circuits. */
00191   CircuitList getCircuits(QString *errmsg = 0);
00192   /** Gets a list of current streams. */
00193   StreamList getStreams(QString *errmsg = 0);
00194   
00195   /** Gets a list of address mappings of the type specified by <b>type</b>
00196    * (defaults to <i>AddressMapAll</i>. */
00197   AddressMap getAddressMap(
00198     AddressMap::AddressMapType type = AddressMap::AddressMapAll,
00199     QString *errmsg = 0);
00200 
00201 public slots:
00202   /** Closes the circuit specified by <b>circId</b>. If <b>ifUnused</b> is
00203    * true, then the circuit will not be closed unless it is unused. */
00204   bool closeCircuit(const CircuitId &circId, bool ifUnused = false,
00205                     QString *errmsg = 0);
00206   /** Closes the stream specified by <b>streamId</b>. */
00207   bool closeStream(const StreamId &streamId, QString *errmsg = 0);
00208 
00209 signals:
00210   /** Emitted when the Tor process has started */
00211   void started();
00212   /** Emitted when the Tor process fails to start. */
00213   void startFailed(QString errmsg);
00214   /** Emitted when the Tor process has stopped */
00215   void stopped(int exitCode, QProcess::ExitStatus exitStatus);
00216   /** Emitted when the Tor process has stopped. */
00217   void stopped();
00218   /** Emitted when the controller has connected to Tor */
00219   void connected();
00220   /** Emitted when the controller failed to connect to Tor. */
00221   void connectFailed(QString errmsg);
00222   /** Emitted when the controller has disconnected from Tor */
00223   void disconnected();
00224   /** Emitted when the control socket is connected and authenticated. */
00225   void authenticated();
00226   /** Emitted when Tor rejects our authentication attempt. */
00227   void authenticationFailed(QString errmsg);
00228 
00229 private:
00230   /** Instantiates a connection used to talk to Tor's control port */
00231   ControlConnection* _controlConn;
00232   /** Manages and monitors the Tor process */
00233   TorProcess* _torProcess;
00234   /** Keep track of which events we're interested in */
00235   TorEvents _torEvents;
00236   /** The version of Tor we're currently talking to. */
00237   QString _torVersion;
00238 #if defined(Q_OS_WIN32)
00239   /** Manages the Tor service, if supported and enabled */
00240   TorService* _torService;
00241 #endif
00242 
00243   /** Send a message to Tor and read the response */
00244   bool send(ControlCommand cmd, ControlReply &reply, QString *errmsg = 0);
00245   /** Send a message to Tor and discard the response */
00246   bool send(ControlCommand cmd, QString *errmsg = 0);
00247   /** Tells Tor the controller wants to enable <b>feature</b> via the
00248    * USEFEATURE control command. Returns true if the given feature was
00249    * successfully enabled. */
00250   bool useFeature(const QString &feature, QString *errmsg = 0);
00251 
00252 /* The slots below simply relay signals from the appropriate member objects */
00253 private slots:
00254   void onStarted();
00255   void onStartFailed(QString errmsg);
00256   void onStopped(int exitCode, QProcess::ExitStatus exitStatus);
00257   void onConnected();
00258   void onConnectFailed(QString errmsg);
00259   void onDisconnected();
00260   void onLogStdout(QString severity, QString message);
00261   void onAuthenticated();
00262 };
00263 
00264 #endif
00265 

Generated on Tue Jul 7 17:00:56 2009 for Vidalia by  doxygen 1.4.7