Vidalia 0.2.12

BootstrapStatus.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 you
00004 **  did not receive the LICENSE file with this file, you may obtain it from the
00005 **  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 the
00008 **  terms described in the LICENSE file.
00009 */
00010 
00011 /* 
00012 ** \file BootstrapStatus.h
00013 ** \brief Describes the Tor software's current bootstrap status
00014 */
00015 
00016 #ifndef _BOOTSTRAPSTATUS_H
00017 #define _BOOTSTRAPSTATUS_H
00018 
00019 #include "tcglobal.h"
00020 
00021 #include <QString>
00022 #include <QMetaType>
00023 
00024 
00025 class BootstrapStatus
00026 {
00027 public:
00028   /** Currently enumerated bootstrapping states defined by Tor's control
00029    * protocol (Tor >= 0.2.1.0-alpha-dev. */ 
00030   enum Status {
00031     UnrecognizedStatus,
00032     ConnectingToDirMirror,
00033     HandshakingWithDirMirror,
00034     CreatingOneHopCircuit,
00035     RequestingNetworkStatus,
00036     LoadingNetworkStatus,
00037     LoadingAuthorityCertificates,
00038     RequestingDescriptors,
00039     LoadingDescriptors,
00040     ConnectingToEntryGuard,
00041     HandshakingWithEntryGuard,
00042     EstablishingCircuit,
00043     BootstrappingDone
00044   };
00045   /** Actions the Tor software might recommend controllers take in response to
00046    * a bootstrap status problem event. */
00047   enum Recommendation {
00048     UnrecognizedRecommendation,
00049     RecommendIgnore,
00050     RecommendWarn
00051   };
00052 
00053   /** Default constructor. */
00054   BootstrapStatus();
00055 
00056   /** Constructor. */
00057   BootstrapStatus(tc::Severity severity,
00058                   Status status, int percentComplete,
00059                   const QString &description,
00060                   const QString &warning = QString(),
00061                   tc::ConnectionStatusReason reason = tc::UnrecognizedReason,
00062                   Recommendation action = UnrecognizedRecommendation);
00063 
00064   /** Returns the severity of this bootstrap status event. */
00065   tc::Severity severity() const { return _severity; }
00066 
00067   /** Returns the BootstrapStatus enum value indicated by this bootstrap
00068    * status event. */
00069   Status status() const { return _status; }
00070 
00071   /** Returns an integer between 0 and 100 representing an estimate of how
00072    * much of Tor's bootstrapping process it has completed. */
00073   int percentComplete() const { return _percentComplete; }
00074 
00075   /** Returns a description of Tor's current bootstrapping status. */
00076   QString description() const { return _description; }
00077   
00078   /** Returns a description of the most recent error Tor encountered while
00079    * attempting to bootstrap, if this event's severity is 'warn'. Otherwise,
00080    * this returns a default-constructed QString. */
00081   QString warning() const { return _warning; }
00082 
00083   /** Returns a ConnectionStatusReason enum value describing the most recent
00084    * error Tor encountered while attempting to bootstrap, if this event's
00085    * severity is 'warn'. Otherwise, this simply returns
00086    * tc::UnrecognizedReason. */
00087   tc::ConnectionStatusReason reason() const { return _reason; }
00088 
00089   /** Returns the action that the Tor software recommended be taken in
00090    * response to this bootstrap status event. */ 
00091   Recommendation recommendedAction() const { return _action; }
00092 
00093   /** Returns true if this object represents a valid bootstrap status
00094    * phase. */
00095   bool isValid() const;
00096 
00097   /** Converts a string TAG value to a BootstrapStatus enum value. */
00098   static Status statusFromString(const QString &tag);
00099   /** Converts a string RECOMMENDATION value to a RecommendAction enum
00100    * value. */
00101   static Recommendation actionFromString(const QString &str);
00102 
00103 private:
00104   /** Severity of the current bootstrap status.
00105    * \sa severity
00106    */
00107   tc::Severity _severity;
00108 
00109   /** Current bootstrapping status value.
00110    * \sa status
00111    */ 
00112   Status _status;
00113   
00114   /** Approximate percentage of Tor's bootstrapping process that is complete.
00115    * \sa percentComplete
00116    */
00117   int _percentComplete;
00118   
00119   /** Description of Tor's current bootstrapping status.
00120    * \sa description
00121    */
00122   QString _description;
00123   
00124   /** Description of the most recent error Tor encountered while attempting to
00125    * bootstrap. 
00126    * \sa warning
00127    */
00128   QString _warning;
00129 
00130   /** ConnectionStatusReason enum value describing the most recent error Tor
00131    * encountered while attempting to bootstrap.
00132    * \sa reason
00133    */
00134   tc::ConnectionStatusReason _reason;
00135 
00136   /** Recommendation enum value describing Tor's suggested response to this
00137    * bootstrap status event.
00138    * \sa recommendedAction
00139    */
00140   Recommendation _action;
00141 };
00142 
00143 Q_DECLARE_METATYPE(BootstrapStatus);
00144 
00145 #endif
00146