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
25class TorControlPrototype : public QObject, QScriptable
26{
27 Q_OBJECT
28
29public:
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 */
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
187public 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
195signals:
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 */
210 /** Emitted when the control socket is connected and 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 */
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 */
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 */
303
304 /** Emitted when Tor determines that the user's DNS provider is providing
305 * a hijacked address even for well-known websites.
306 */
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
QList< Circuit > CircuitList
Definition: Circuit.h:81
QString CircuitId
Definition: Circuit.h:24
QList< RouterStatus > NetworkStatus
Definition: RouterStatus.h:97
QString StreamId
Definition: Stream.h:28
QList< Stream > StreamList
Definition: Stream.h:97
QHash< QString, QString > DescriptorAnnotations
Definition: TorControl.h:42
stop errmsg QVariant
Q_DECLARE_METATYPE(TorControl *)
@ AddressMapAll
Definition: AddressMap.h:33
Definition: Stream.h:32
void startFailed(QString errmsg)
void bandwidthUpdate(quint64 bytesReceived, quint64 bytesSent)
void addressMapped(const QString &from, const QString &to, const QDateTime &expires)
Q_INVOKABLE QVariant ipToCountry(const QHostAddress &ip)
void connectFailed(QString errmsg)
Q_INVOKABLE QVariant saveConf()
Q_INVOKABLE QVariant authenticate(const QByteArray cookie)
Q_INVOKABLE QVariant setConf(QHash< QString, QString > map)
void dangerousPort(quint16 port, bool rejected)
Q_INVOKABLE NetworkStatus getNetworkStatus(QString *errmsg=0)
Q_INVOKABLE void disconnect()
Q_INVOKABLE QVariant getInfo(const QString &key)
void newDescriptors(const QStringList &ids)
Q_INVOKABLE bool getConf(QString key, QStringList &value, QString *errmsg=0)
Q_INVOKABLE QVariant authenticate(const QString &password=QString())
void socksError(tc::SocksError type, const QString &destination)
Q_INVOKABLE QList< quint16 > getSocksPortList(QString *errmsg=0)
bool closeStream(const StreamId &streamId, QString *errmsg=0)
void bug(const QString &reason)
Q_INVOKABLE void start(const QString &tor, const QStringList &args)
Q_INVOKABLE QVariant stop()
void circuitStatusChanged(const Circuit &circuit)
Q_INVOKABLE RouterDescriptor getRouterDescriptor(const QString &id, QString *errmsg=0)
Q_INVOKABLE QVariant setConf(QString keyAndValue)
Q_INVOKABLE void closeTorStdout()
Q_INVOKABLE RouterStatus getRouterStatus(const QString &id, QString *errmsg=0)
Q_INVOKABLE bool isVidaliaRunningTor()
void orPortReachabilityFinished(const QHostAddress &ip, quint16 port, bool reachable)
Q_INVOKABLE QVariant setEvents()
void bootstrapStatusChanged(const BootstrapStatus &status)
Q_INVOKABLE bool isConnected()
void serverDescriptorAccepted()
Q_INVOKABLE QStringList getRouterDescriptorText(const QString &id, QString *errmsg=0)
Q_INVOKABLE QVariant signal(TorSignal::Signal sig)
Q_INVOKABLE QVariant getSocksPort()
Q_INVOKABLE bool getConf(QHash< QString, QString > &map, QString *errmsg)
void stopped(int exitCode, QProcess::ExitStatus exitStatus)
void dirPortReachabilityFinished(const QHostAddress &ip, quint16 port, bool reachable)
Q_INVOKABLE QStringList getSocksAddressList(QString *errmsg=0)
Q_INVOKABLE void connect(const QHostAddress &address, quint16 port)
void serverDescriptorAccepted(const QHostAddress &ip, quint16 port)
void serverDescriptorRejected(const QHostAddress &ip, quint16 port, const QString &reason)
Q_INVOKABLE bool resetConf(QStringList keys, QString *errmsg=0)
Q_INVOKABLE StreamList getStreams(QString *errmsg=0)
Q_INVOKABLE QVariant setEvent(TorEvents::Event e, bool add=true, bool set=true)
Q_INVOKABLE QString getTorVersionString()
void clockSkewed(int skew, const QString &source)
Q_INVOKABLE void connect(const QString &path)
Q_INVOKABLE bool isRunning()
void checkingOrPortReachability(const QHostAddress &ip, quint16 port)
Q_INVOKABLE bool isCircuitEstablished()
Q_INVOKABLE QVariant getInfo(QHash< QString, QString > &map)
Q_INVOKABLE CircuitList getCircuits(QString *errmsg=0)
Q_INVOKABLE QVariant setConf(QString key, QString value)
Q_INVOKABLE QVariant getHiddenServiceConf(const QString &key)
Q_INVOKABLE QVariant resetConf(QString key)
Q_INVOKABLE QVariant getConf(QString key)
Q_INVOKABLE DescriptorAnnotations getDescriptorAnnotations(const QString &id, QString *errmsg=0)
void logMessage(tc::Severity level, const QString &msg)
bool closeCircuit(const CircuitId &circId, bool ifUnused=false, QString *errmsg=0)
Q_INVOKABLE quint32 getTorVersion()
Q_INVOKABLE AddressMap getAddressMap(AddressMap::AddressMapType type=AddressMap::AddressMapAll, QString *errmsg=0)
void checkingDirPortReachability(const QHostAddress &ip, quint16 port)
void externalAddressChanged(const QHostAddress &ip, const QString &hostname)
void authenticationFailed(QString errmsg)
void dangerousTorVersion(tc::TorVersionStatus reason, const QString &version, const QStringList &recommended)
void streamStatusChanged(const Stream &stream)
TorVersionStatus
Definition: tcglobal.h:86
SocksError
Definition: tcglobal.h:79
Severity
Definition: tcglobal.h:69