Vidalia  0.3.1
TorControlPrototype.h
Go to the documentation of this file.
1 /*
2 ** This file is part of Vidalia, and is subject to the license terms in the
3 ** LICENSE file, found in the top level directory of this distribution. If you
4 ** did not receive the LICENSE file with this file, you may obtain it from the
5 ** Vidalia source package distributed by the Vidalia Project at
6 ** http://www.torproject.org/projects/vidalia.html. No part of Vidalia,
7 ** including this file, may be copied, modified, propagated, or distributed
8 ** except according to the terms described in the LICENSE file.
9 */
10 
11 /*
12 ** \file TorControlPrototype.h
13 ** \brief Prototype for TorControl class
14 */
15 
16 #ifndef _TORCONTROLPROTO_H
17 #define _TORCONTROLPROTO_H
18 
19 #include <QtGui>
20 #include <QtScript>
21 
22 #include "TorControl.h"
23 #include "ProtocolInfo.h"
24 
25 class TorControlPrototype : public QObject, QScriptable
26 {
27  Q_OBJECT
28 
29 public:
31 
32  static int metaTypeId();
33  static QString name();
34 
35  /** Start the Tor process */
36  Q_INVOKABLE void start(const QString &tor, const QStringList &args);
37  /** Stop the Tor process */
38  Q_INVOKABLE QVariant stop();
39  /** Detect if the Tor process is running */
40  Q_INVOKABLE bool isRunning();
41  /** Detects if the Tor process is running under Vidalia. */
42  Q_INVOKABLE bool isVidaliaRunningTor();
43  /** Stops reading log messages from the Tor process's stdout. This has no
44  * effect if isVidaliaRunningTor() is false. */
45  Q_INVOKABLE void closeTorStdout();
46 
47  /** Connect to Tor's control socket */
48  Q_INVOKABLE void connect(const QHostAddress &address, quint16 port);
49  Q_INVOKABLE void connect(const QString &path);
50  /** Disconnect from Tor's control socket */
51  Q_INVOKABLE void disconnect();
52  /** Check if we're connected to Tor's control socket */
53  Q_INVOKABLE bool isConnected();
54  /** Sends an authentication cookie to Tor. */
55  Q_INVOKABLE QVariant authenticate(const QByteArray cookie);
56  /** Sends an authentication password to Tor. */
57  Q_INVOKABLE QVariant authenticate(const QString &password = QString());
58 
59  /** Sends a PROTOCOLINFO command to Tor and parses the response. */
60 // Q_INVOKABLE QVariant protocolInfo();
61 
62  /** Returns the Tor software's current bootstrap phase and status. */
63 // Q_INVOKABLE BootstrapStatus bootstrapStatus(QString *errmsg = 0);
64 
65  /** Returns true if Tor either has an open circuit or (on Tor >=
66  * 0.2.0.1-alpha) has previously decided it's able to establish a circuit. */
67  Q_INVOKABLE bool isCircuitEstablished();
68 
69  /** Sends a GETINFO message to Tor based on the given keys */
70  Q_INVOKABLE QVariant getInfo(QHash<QString,QString> &map);
71  /** Sends a GETINFO message for a single info value to Tor */
72 // Q_INVOKABLE QVariant getInfo(QString key);
73 
74  /** Sends a GETINFO message to Tor using the given list of <b>keys</b> and
75  * returns a QVariantMap containing the specified keys and their values as
76  * returned by Tor. Returns a default constructed QVariantMap on failure. */
77 // Q_INVOKABLE QVariantMap getInfo(const QStringList &keys, QString *errmsg = 0);
78  /** Sends a GETINFO message to Tor with a single <b>key</b> and returns a
79  * QVariant containing the value returned by Tor. Returns a default
80  * constructed QVariant on failure. */
81  Q_INVOKABLE QVariant getInfo(const QString &key);
82 
83  /** Sends a signal to Tor */
84  Q_INVOKABLE QVariant signal(TorSignal::Signal sig);
85 
86  /** Returns an address on which Tor is listening for application
87  * requests. If none are available, a null QHostAddress is returned. */
88 // Q_INVOKABLE QVariant getSocksAddress();
89  /** Returns a (possibly empty) list of all currently configured
90  * SocksListenAddress entries. */
91  Q_INVOKABLE QStringList getSocksAddressList(QString *errmsg = 0);
92  /** Returns a valid SOCKS port for Tor, or 0 if Tor is not accepting
93  * application requests. */
94  Q_INVOKABLE QVariant getSocksPort();
95  /** Returns a list of all currently configured SOCKS ports. If Tor is not
96  * accepting any application connections, an empty list will be returned. */
97  Q_INVOKABLE QList<quint16> getSocksPortList(QString *errmsg = 0);
98 
99  /** Returns Tor's version as a string. */
100  Q_INVOKABLE QString getTorVersionString();
101  /** Returns Tor's version as a numeric value. */
102  Q_INVOKABLE quint32 getTorVersion();
103 
104  /** Sets an event and its handler. If add is true, then the event is added,
105  * otherwise it is removed. If set is true, then the given event will be
106  * registered with Tor. */
107  Q_INVOKABLE QVariant setEvent(TorEvents::Event e, bool add = true, bool set = true);
108  /** Register events of interest with Tor */
109  Q_INVOKABLE QVariant setEvents();
110 
111  /** Sets each configuration key in <b>map</b> to the value associated with its key. */
112  Q_INVOKABLE QVariant setConf(QHash<QString,QString> map);
113  /** Sets a single configuration key to the given value. */
114  Q_INVOKABLE QVariant setConf(QString key, QString value);
115  /** Sets a single configuration string that is formatted <key=escaped value>. */
116  Q_INVOKABLE QVariant setConf(QString keyAndValue);
117  /** Gets values for a set of configuration keys, each of which has a single
118  * value. */
119  Q_INVOKABLE bool getConf(QHash<QString,QString> &map, QString *errmsg);
120  /** Gets a set of configuration keyvalues and stores them in <b>map</b>. */
121  Q_INVOKABLE bool getConf(QHash<QString,QStringList> &map, QString *errmsg = 0);
122  /** Gets a single configuration value for <b>key</b>. */
123  Q_INVOKABLE QVariant getConf(QString key);
124  /** Gets a list of configuration values for <b>key</b>. */
125  Q_INVOKABLE bool getConf(QString key, QStringList &value, QString *errmsg = 0);
126 
127  /** Sends a GETCONF message to Tor using the given list of <b>keys</b> and
128  * returns a QVariantMap containing the specified keys and their values as
129  * returned by Tor. Returns a default constructed QVariantMap on failure. */
130  Q_INVOKABLE QVariantMap getConf(const QStringList &keys, QString *errmsg = 0);
131  /** Sends a GETCONF message to Tor with a single <b>key</b> and returns a
132  * QVariant containing the value returned by Tor. Returns a default
133  * constructed QVariant on failure. */
134 // Q_INVOKABLE QVariant getConf(const QString &key, QString *errmsg = 0);
135  /** Sends a GETCONF message to Tor with the single key and returns a QString
136  * containing the value returned by Tor */
137  Q_INVOKABLE QVariant getHiddenServiceConf(const QString &key);
138 
139  /** Asks Tor to save the current configuration to its torrc */
140  Q_INVOKABLE QVariant saveConf();
141  /** Tells Tor to reset the given configuration keys back to defaults. */
142  Q_INVOKABLE bool resetConf(QStringList keys, QString *errmsg = 0);
143  /** Tells Tor to reset a configuration key back to its default value. */
144  Q_INVOKABLE QVariant resetConf(QString key);
145 
146  /** Returns an unparsed router descriptor for the router whose fingerprint
147  * matches <b>id</b>. The returned text can later be parsed by the
148  * RouterDescriptor class. If <b>id</b> is invalid, then an empty
149  * QStringList is returned. */
150  Q_INVOKABLE QStringList getRouterDescriptorText(const QString &id, QString *errmsg = 0);
151  /** Returns the descriptor for the router whose fingerprint matches
152  * <b>id</b>. If <b>id</b> is invalid or the router's descriptor cannot be
153  * parsed, then an invalid RouterDescriptor is returned. */
154  Q_INVOKABLE RouterDescriptor getRouterDescriptor(const QString &id, QString *errmsg = 0);
155  /** Returns the status of the router whose fingerprint matches <b>id</b>. If
156  * <b>id</b> is invalid or the router's status cannot be parsed, then an
157  * invalid RouterStatus is returned. */
158  Q_INVOKABLE RouterStatus getRouterStatus(const QString &id, QString *errmsg = 0);
159  /** Returns a RouterStatus object for every known router in the network. If
160  * the network status document cannot be parsed, then an empty NetworkStatus
161  * is returned. */
162  Q_INVOKABLE NetworkStatus getNetworkStatus(QString *errmsg = 0);
163  /** Returns the annotations for the router whose fingerprint matches
164  * <b>id</b>. If <b>id</b> is invalid or the router's descriptor cannot be
165  * parsed, then an empty DescriptorAnnotations is returned and
166  * <b>errmsg</b> is set if it's not NULL. (Tor >= 0.2.0.13-alpha only) */
167  Q_INVOKABLE DescriptorAnnotations getDescriptorAnnotations(const QString &id,
168  QString *errmsg = 0);
169 
170  /** Gets a list of current circuits. */
171  Q_INVOKABLE CircuitList getCircuits(QString *errmsg = 0);
172  /** Gets a list of current streams. */
173  Q_INVOKABLE StreamList getStreams(QString *errmsg = 0);
174 
175  /** Gets a list of address mappings of the type specified by <b>type</b>
176  * (defaults to <i>AddressMapAll</i>. */
177  Q_INVOKABLE AddressMap getAddressMap(
179  QString *errmsg = 0);
180 
181  /** Gets the ISO-3166 two-letter country code for <b>ip</b> from Tor.
182  * Returns a default-constructed QString on failure or if a country code
183  * is not known for <b>ip</b>. On failure, <b>errmsg</b> will be set if
184  * it's not NULL. */
185  Q_INVOKABLE QVariant ipToCountry(const QHostAddress &ip);
186 
187 public slots:
188  /** Closes the circuit specified by <b>circId</b>. If <b>ifUnused</b> is
189  * true, then the circuit will not be closed unless it is unused. */
190  bool closeCircuit(const CircuitId &circId, bool ifUnused = false,
191  QString *errmsg = 0);
192  /** Closes the stream specified by <b>streamId</b>. */
193  bool closeStream(const StreamId &streamId, QString *errmsg = 0);
194 
195 signals:
196  /** Emitted when the Tor process has started */
197  void started();
198  /** Emitted when the Tor process fails to start. */
199  void startFailed(QString errmsg);
200  /** Emitted when the Tor process has stopped */
201  void stopped(int exitCode, QProcess::ExitStatus exitStatus);
202  /** Emitted when the Tor process has stopped. */
203  void stopped();
204  /** Emitted when the controller has connected to Tor */
205  void connected();
206  /** Emitted when the controller failed to connect to Tor. */
207  void connectFailed(QString errmsg);
208  /** Emitted when the controller has disconnected from Tor */
209  void disconnected();
210  /** Emitted when the control socket is connected and authenticated. */
211  void authenticated();
212  /** Emitted when Tor rejects our authentication attempt. */
213  void authenticationFailed(QString errmsg);
214 
215  /** Emitted when Tor writes the message <b>msg</b> to the control port
216  * with message severity <b>level</b>.
217  */
218  void logMessage(tc::Severity level, const QString &msg);
219 
220  /** Emitted when Tor sends a bandwidth usage update (roughly once every
221  * second). <b>bytesReceived</b> is the number of bytes read by Tor over
222  * the previous second and <b>bytesWritten</b> is the number of bytes
223  * sent over the same interval.
224  */
225  void bandwidthUpdate(quint64 bytesReceived, quint64 bytesSent);
226 
227  /** Emitted when the stream status of <b>stream</b> has changed.
228  */
229  void streamStatusChanged(const Stream &stream);
230 
231  /** Emitted when the circuit status of <b>circuit</b> has changed.
232  */
233  void circuitStatusChanged(const Circuit &circuit);
234 
235  /** Emitted when Tor has mapped the address <b>from</b> to the address
236  * <b>to</b>. <b>expires</b> indicates the time at which when the address
237  * mapping will no longer be considered valid.
238  */
239  void addressMapped(const QString &from, const QString &to,
240  const QDateTime &expires);
241 
242  /** Emitted when Tor has received one or more new router descriptors.
243  * <b>ids</b> contains a list of digests of the new descriptors.
244  */
245  void newDescriptors(const QStringList &ids);
246 
247  /** Indicates Tor has been able to successfully establish one or more
248  * circuits.
249  */
250  void circuitEstablished();
251 
252  /** Indicates that Tor has decided the user's Tor software <b>version</b>
253  * is no longer recommended for some <b>reason</b>. <b>recommended</b> is
254  * a list of Tor software versions that are considered current.
255  */
257  const QString &version,
258  const QStringList &recommended);
259 
260  /** Emitted during Tor's startup process to indicate how far in its
261  * bootstrapping process it has progressed. <b>status</b> may indicate
262  * the current bootstrapping stage or an error during bootstrapping.
263  */
264  void bootstrapStatusChanged(const BootstrapStatus &status);
265 
266  /** Emitted when the user attempts to establish a connection to some
267  * destination on port <b>port</b>, which is a port known to use
268  * plaintext connections (as determined by Tor's WarnPlaintextPorts and
269  * RejectPlaintextPorts torrc options). <b>rejected</b> indicates whether
270  * Tor rejected the connection or permitted it to connect anyway.
271  */
272  void dangerousPort(quint16 port, bool rejected);
273 
274  /** Emitted when Tor detects a problem with a SOCKS connection from the
275  * user, such as a bad hostname, dangerous SOCKS protocol type, or a bad
276  * hostname. <b>type</b> indicates the type of error encountered and
277  * <b>destination</b> (if non-empty) specifies the attempted connection
278  * destination address or hostname.
279  */
280  void socksError(tc::SocksError type, const QString &destination);
281 
282  /** Emitted when Tor decides the client's external IP address has changed
283  * to <b>ip</b>. If <b>hostname</b> is non-empty, Tor obtained the new
284  * value for <b>ip</b> by resolving <b>hostname</b>.
285  */
286  void externalAddressChanged(const QHostAddress &ip, const QString &hostname);
287 
288  /** Indicates that Tor has determined the client's clock is potentially
289  * skewed by <b>skew</b> seconds relative to <b>source</b>.
290  */
291  void clockSkewed(int skew, const QString &source);
292 
293  /** Emitted when Tor has encountered an internal bug. <b>reason</b> is
294  * Tor's description of the bug.
295  */
296  void bug(const QString &reason);
297 
298  /** Emitted when Tor determines that the user's DNS provider is providing
299  * an address for non-existent domains when it should really be saying
300  * "NXDOMAIN".
301  */
302  void dnsHijacked();
303 
304  /** Emitted when Tor determines that the user's DNS provider is providing
305  * a hijacked address even for well-known websites.
306  */
307  void dnsUseless();
308 
309  /** Indicates Tor has started testing the reachability of its OR port
310  * using the IP address <b>ip</b> and port <b>port</b>.
311  */
312  void checkingOrPortReachability(const QHostAddress &ip, quint16 port);
313 
314  /** Tor has completed testing the reachability of its OR port using
315  * the IP address <b>ip</b> and port <b>port</b>. If the user's OR port
316  * was reachable, <b>reachable</b> will be set to true.
317  */
318  void orPortReachabilityFinished(const QHostAddress &ip, quint16 port,
319  bool reachable);
320 
321  /** Indicates Tor has started testing the reachability of its directory
322  * port using the IP address <b>ip</b> and port <b>port</b>.
323  */
324  void checkingDirPortReachability(const QHostAddress &ip, quint16 port);
325 
326  /** Tor has completed testing the reachability of its directory port using
327  * the IP address <b>ip</b> and port <b>port</b>. If the user's directory
328  * port was reachable, <b>reachable</b> will be set to true.
329  */
330  void dirPortReachabilityFinished(const QHostAddress &ip, quint16 port,
331  bool reachable);
332 
333  /** Emitted when the directory authority with IP address <b>ip</b> and
334  * port <b>port</b> rejected the user's server descriptor. <b>reason</b>
335  * describes why the descriptor was rejected (e.g., malformed, skewed
336  * clock, etc.).
337  */
338  void serverDescriptorRejected(const QHostAddress &ip, quint16 port,
339  const QString &reason);
340 
341  /** Emitted when the directory authority with IP address <b>ip</b> and
342  * port <b>port</b> accepted the user's server descriptor.
343  */
344  void serverDescriptorAccepted(const QHostAddress &ip, quint16 port);
345 
346  /** Emitted when at least one directory authority has accepted the user's
347  * server descriptor.
348  */
350 };
351 
353 
354 #endif
355 
356 
SocksError
Definition: tcglobal.h:79
Q_INVOKABLE CircuitList getCircuits(QString *errmsg=0)
stop errmsg QVariant
Definition: Stream.h:31
Q_INVOKABLE QVariant authenticate(const QByteArray cookie)
Q_INVOKABLE void start(const QString &tor, const QStringList &args)
Q_INVOKABLE quint32 getTorVersion()
Q_INVOKABLE QList< quint16 > getSocksPortList(QString *errmsg=0)
void dirPortReachabilityFinished(const QHostAddress &ip, quint16 port, bool reachable)
Q_DECLARE_METATYPE(TorControl *)
Q_INVOKABLE QVariant getInfo(QHash< QString, QString > &map)
Q_INVOKABLE QStringList getRouterDescriptorText(const QString &id, QString *errmsg=0)
Q_INVOKABLE bool isVidaliaRunningTor()
Q_INVOKABLE QVariant stop()
void startFailed(QString errmsg)
Q_INVOKABLE NetworkStatus getNetworkStatus(QString *errmsg=0)
Q_INVOKABLE bool isRunning()
Q_INVOKABLE QVariant setEvent(TorEvents::Event e, bool add=true, bool set=true)
void bootstrapStatusChanged(const BootstrapStatus &status)
void newDescriptors(const QStringList &ids)
bool closeStream(const StreamId &streamId, QString *errmsg=0)
void socksError(tc::SocksError type, const QString &destination)
QList< Stream > StreamList
Definition: Stream.h:97
void authenticationFailed(QString errmsg)
Q_INVOKABLE QVariant getHiddenServiceConf(const QString &key)
Q_INVOKABLE RouterStatus getRouterStatus(const QString &id, QString *errmsg=0)
Q_INVOKABLE QVariant ipToCountry(const QHostAddress &ip)
Q_INVOKABLE bool isConnected()
QString StreamId
Definition: Stream.h:28
Q_INVOKABLE RouterDescriptor getRouterDescriptor(const QString &id, QString *errmsg=0)
void checkingOrPortReachability(const QHostAddress &ip, quint16 port)
void connectFailed(QString errmsg)
void orPortReachabilityFinished(const QHostAddress &ip, quint16 port, bool reachable)
void addressMapped(const QString &from, const QString &to, const QDateTime &expires)
void bandwidthUpdate(quint64 bytesReceived, quint64 bytesSent)
Q_INVOKABLE QVariant saveConf()
TorVersionStatus
Definition: tcglobal.h:86
void serverDescriptorAccepted()
void dangerousTorVersion(tc::TorVersionStatus reason, const QString &version, const QStringList &recommended)
Severity
Definition: tcglobal.h:69
void circuitStatusChanged(const Circuit &circuit)
void checkingDirPortReachability(const QHostAddress &ip, quint16 port)
QList< Circuit > CircuitList
Definition: Circuit.h:81
bool closeCircuit(const CircuitId &circId, bool ifUnused=false, QString *errmsg=0)
void externalAddressChanged(const QHostAddress &ip, const QString &hostname)
Q_INVOKABLE QVariant signal(TorSignal::Signal sig)
Q_INVOKABLE QVariant setEvents()
Q_INVOKABLE QVariant getSocksPort()
Q_INVOKABLE bool isCircuitEstablished()
Q_INVOKABLE void connect(const QHostAddress &address, quint16 port)
QHash< QString, QString > DescriptorAnnotations
Definition: TorControl.h:42
QString CircuitId
Definition: Circuit.h:24
void logMessage(tc::Severity level, const QString &msg)
void serverDescriptorRejected(const QHostAddress &ip, quint16 port, const QString &reason)
Q_INVOKABLE StreamList getStreams(QString *errmsg=0)
Q_INVOKABLE DescriptorAnnotations getDescriptorAnnotations(const QString &id, QString *errmsg=0)
Q_INVOKABLE void closeTorStdout()
Q_INVOKABLE void disconnect()
Q_INVOKABLE QVariant setConf(QHash< QString, QString > map)
QList< RouterStatus > NetworkStatus
Definition: RouterStatus.h:97
void streamStatusChanged(const Stream &stream)
void bug(const QString &reason)
void dangerousPort(quint16 port, bool rejected)
Q_INVOKABLE QStringList getSocksAddressList(QString *errmsg=0)
Q_INVOKABLE bool resetConf(QStringList keys, QString *errmsg=0)
Q_INVOKABLE QString getTorVersionString()
Q_INVOKABLE bool getConf(QHash< QString, QString > &map, QString *errmsg)
void clockSkewed(int skew, const QString &source)
Q_INVOKABLE AddressMap getAddressMap(AddressMap::AddressMapType type=AddressMap::AddressMapAll, QString *errmsg=0)