torcontrol.h

Go to the documentation of this file.
00001 /****************************************************************
00002  *  Vidalia is distributed under the following license:
00003  *
00004  *  Copyright (C) 2006,  Matt Edman, Justin Hipple
00005  *
00006  *  This program is free software; you can redistribute it and/or
00007  *  modify it under the terms of the GNU General Public License
00008  *  as published by the Free Software Foundation; either version 2
00009  *  of the License, or (at your option) any later version.
00010  *
00011  *  This program is distributed in the hope that it will be useful,
00012  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
00013  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
00014  *  GNU General Public License for more details.
00015  *
00016  *  You should have received a copy of the GNU General Public License
00017  *  along with this program; if not, write to the Free Software
00018  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, 
00019  *  Boston, MA  02110-1301, USA.
00020  ****************************************************************/
00021 
00022 /** 
00023  * \file torcontrol.h
00024  * \version $Id: torcontrol.h 1853 2007-08-23 01:06:21Z edmanm $
00025  * \brief Object for interacting with the Tor process and control interface
00026  */
00027 
00028 #ifndef _TORCONTROL_H
00029 #define _TORCONTROL_H
00030 
00031 #include <QObject>
00032 #include <QHash>
00033 #include <QList>
00034 #include <QStringList>
00035 
00036 #include "controlconnection.h"
00037 #include "torprocess.h"
00038 #include "torevents.h"
00039 #include "torsignal.h"
00040 #include "routerdescriptor.h"
00041 #include "addressmap.h"
00042 #include "protocolinfo.h"
00043 
00044 #if defined(Q_OS_WIN32)
00045 #include "torservice.h"
00046 #endif
00047 
00048 
00049 class TorControl : public QObject
00050 {
00051   Q_OBJECT
00052   
00053 public:
00054   /** Default constructor */
00055   TorControl();
00056   /** Default destructor */
00057   ~TorControl();
00058 
00059   /** Start the Tor process */
00060   void start();
00061   /** Stop the Tor process */
00062   bool stop(QString *errmsg = 0);
00063   /** Detect if the Tor process is running */
00064   bool isRunning();
00065   /** Detects if the Tor process is running under Vidalia. */
00066   bool isVidaliaRunningTor();
00067   
00068   /** Connect to Tor's control socket */
00069   void connect();
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   /** Sends a GETINFO message to Tor based on the given keys */
00083   bool getInfo(QHash<QString,QString> &map, QString *errmsg = 0);
00084   /** Sends a GETINFO message for a single info value to Tor */
00085   bool getInfo(QString key, QString &val, QString *errmsg = 0);
00086 
00087   /** Sends a signal to Tor */
00088   bool signal(TorSignal::Signal sig, QString *errmsg = 0);
00089  
00090   /** Returns an address on which Tor is listening for application
00091    * requests. If none are available, a null QHostAddress is returned. */
00092   QHostAddress getSocksAddress(QString *errmsg = 0);
00093   /** Returns a (possibly empty) list of all currently configured 
00094    * SocksListenAddress entries. */
00095   QStringList getSocksAddressList(QString *errmsg = 0);
00096   /** Returns a valid SOCKS port for Tor, or 0 if Tor is not accepting
00097    * application requests. */
00098   quint16 getSocksPort(QString *errmsg = 0);
00099   /** Returns a list of all currently configured SOCKS ports. If Tor is not
00100    * accepting any application connections, an empty list will be returned. */
00101   QList<quint16> getSocksPortList(QString *errmsg = 0);
00102 
00103   /** Returns Tor's version as a string. */
00104   QString getTorVersionString();
00105   /** Returns Tor's version as a numeric value. */
00106   quint32 getTorVersion();
00107 
00108   /** Sets an event and its handler. If add is true, then the event is added,
00109    * otherwise it is removed. If set is true, then the given event will be
00110    * registered with Tor. */
00111   bool setEvent(TorEvents::TorEvent e, QObject *obj, 
00112                 bool add, bool set = true, QString *errmsg = 0);
00113   /** Registers for a set of logging events according to the given filter. */
00114   bool setLogEvents(uint filter, QObject *obj, QString *errmsg = 0);
00115   /** Register events of interest with Tor */
00116   bool setEvents(QString *errmsg = 0);
00117   
00118 
00119   /** Sets each configuration key in <b>map</b> to the value associated with its key. */
00120   bool setConf(QHash<QString,QString> map, QString *errmsg = 0);
00121   /** Sets a single configuration key to the given value. */
00122   bool setConf(QString key, QString value, QString *errmsg = 0);
00123   /** Gets values for a set of configuration keys, each of which has a single
00124    * value. */
00125   bool getConf(QHash<QString,QString> &map, QString *errmsg = 0);
00126   /** Gets a set of configuration keyvalues and stores them in <b>map</b>. */
00127   bool getConf(QHash<QString,QStringList> &map, QString *errmsg = 0);
00128   /** Gets a single configuration value for <b>key</b>. */
00129   bool getConf(QString key, QString &value, QString *errmsg = 0);
00130   /** Gets a list of configuration values for <b>key</b>. */
00131   bool getConf(QString key, QStringList &value, QString *errmsg = 0);
00132   /** Asks Tor to save the current configuration to its torrc */
00133   bool saveConf(QString *errmsg = 0);
00134   /** Tells Tor to reset the given configuration keys back to defaults. */
00135   bool resetConf(QStringList keys, QString *errmsg = 0);
00136   /** Tells Tor to reset a configuration key back to its default value. */
00137   bool resetConf(QString key, QString *errmsg = 0);
00138 
00139   /** Gets a descriptor for the given router name. */
00140   RouterDescriptor getDescriptorByName(QString name, QString *errmsg = 0);
00141   /** Gets a descriptor for the given router ID. */
00142   RouterDescriptor getDescriptorById(QString id, QString *errmsg = 0);
00143   /** Gets descriptors for the given list of router names. */
00144   QList<RouterDescriptor> getDescriptorListByName(QStringList names, QString *errmsg = 0);
00145   /** Gets descriptors for the given list of router IDs. */
00146   QList<RouterDescriptor> getDescriptorListById(QStringList ids, QString *errmsg = 0);
00147   /** Gets a list of descriptors for all routers Tor knows about. */
00148   QList<RouterDescriptor> getRouterList(QString *errmsg = 0);
00149   /** Gets a list of router IDs for all routers Tor knows about. */
00150   QStringList getRouterIDList(QString *errmsg = 0);
00151 
00152   /** Gets a list of current circuits. */
00153   QList<Circuit> getCircuits(QString *errmsg = 0);
00154   /** Gets a list of current streams. */
00155   QList<Stream> getStreams(QString *errmsg = 0);
00156   
00157   /** Gets a list of address mappings of the type specified by <b>type</b>
00158    * (defaults to <i>AddressMapAll</i>. */
00159   AddressMap getAddressMap(
00160     AddressMap::AddressMapType type = AddressMap::AddressMapAll,
00161     QString *errmsg = 0);
00162 
00163 public slots:
00164   /** Closes the circuit specified by <b>circid</b>. If <b>ifUnused</b> is
00165    * true, then the circuit will not be closed unless it is unused. */
00166   bool closeCircuit(quint64 circid, bool ifUnused = false, QString *errmsg = 0);
00167   /** Closes the stream specified by <b>streamid</b>. */
00168   bool closeStream(quint64 streamid, QString *errmsg = 0);
00169 
00170 signals:
00171   /** Emitted when the Tor process has started */
00172   void started();
00173   /** Emitted when the Tor process fails to start. */
00174   void startFailed(QString errmsg);
00175   /** Emitted when the Tor process has stopped */
00176   void stopped(int exitCode, QProcess::ExitStatus exitStatus);
00177   /** Emitted when the Tor process has stopped. */
00178   void stopped();
00179   /** Emitted when the controller has connected to Tor */
00180   void connected();
00181   /** Emitted when the controller failed to connect to Tor. */
00182   void connectFailed(QString errmsg);
00183   /** Emitted when the controller has disconnected from Tor */
00184   void disconnected();
00185   /** Emitted when the control socket is connected and authenticated. */
00186   void authenticated();
00187   /** Emitted when Tor rejects our authentication attempt. */
00188   void authenticationFailed(QString errmsg);
00189 
00190 private:
00191   /** Instantiates a connection used to talk to Tor's control port */
00192   ControlConnection* _controlConn;
00193   /** Manages and monitors the Tor process */
00194   TorProcess* _torProcess;
00195   /** Keep track of which events we're interested in */
00196   TorEvents _torEvents;
00197   /** The version of Tor we're currently talking to. */
00198   QString _torVersion;
00199 #if defined(Q_OS_WIN32)
00200   /** Manages the Tor service, if supported and enabled */
00201   TorService* _torService;
00202 #endif
00203 
00204   /** Send a message to Tor and read the response */
00205   bool send(ControlCommand cmd, ControlReply &reply, QString *errmsg = 0);
00206   /** Send a message to Tor and discard the response */
00207   bool send(ControlCommand cmd, QString *errmsg = 0);
00208   /** Disconnects signals from the TorProcess and frees its memory. */
00209   void closeTorProcess();
00210   
00211 /* The slots below simply relay signals from the appropriate member objects */
00212 private slots:
00213   void onStarted();
00214   void onStartFailed(QString errmsg);
00215   void onStopped(int exitCode, QProcess::ExitStatus exitStatus);
00216   void onConnected();
00217   void onConnectFailed(QString errmsg);
00218   void onDisconnected();
00219   void onLogStdout(QString severity, QString message);
00220   void onAuthenticated();
00221 };
00222 
00223 #endif
00224 

Generated on Wed Sep 5 15:49:28 2007 for Vidalia by  doxygen 1.5.3