Vidalia  0.2.17
UPNPControl.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.torproject.org/projects/vidalia.html. No part of Vidalia, 
00007 **  including this file, may be copied, modified, propagated, or distributed 
00008 **  except according to the terms described in the LICENSE file.
00009 */
00010 
00011 /* 
00012 ** \file UPNPControl.h
00013 ** \brief Singleton object for interacting with UPNP device
00014 */
00015 
00016 #ifndef _UPNPCONTROL_H
00017 #define _UPNPCONTROL_H
00018 
00019 #include <QObject>
00020 #include <QMutex>
00021 
00022 /* Forward declaration to make it build */
00023 class UPNPControlThread;
00024 
00025 
00026 class UPNPControl : public QObject
00027 {
00028   Q_OBJECT
00029 
00030 public:
00031   /** UPnP-related error values. */
00032   enum UPNPError {
00033     Success,
00034     NoUPNPDevicesFound,
00035     NoValidIGDsFound,
00036     WSAStartupFailed,
00037     AddPortMappingFailed,
00038     GetPortMappingFailed,
00039     DeletePortMappingFailed,
00040     UnknownError
00041   };
00042   /** UPnP port forwarding state. */
00043   enum UPNPState {
00044     IdleState,
00045     ErrorState, 
00046     DiscoverState,
00047     UpdatingORPortState,
00048     UpdatingDirPortState,
00049     ForwardingCompleteState
00050   };
00051 
00052   /** Returns a pointer to this object's singleton instance. */
00053   static UPNPControl* instance();
00054   /** Terminates the UPnP control thread and frees memory allocated to this
00055    * object's singleton instance. */
00056   static void cleanup();
00057   /** Sets <b>desiredDirPort</b> and <b>desiredOrPort</b> to the currently
00058    * forwarded DirPort and ORPort values. */
00059   void getDesiredState(quint16 *desiredDirPort, quint16 *desiredOrPort);
00060   /** Sets the desired DirPort and ORPort port mappings to
00061    * <b>desiredDirPort</b> and <b>desiredOrPort</b>, respectively. */
00062   void setDesiredState(quint16 desiredDirPort, quint16 desiredOrPort);
00063 
00064   /** Returns the type of error that occurred last. */
00065   UPNPError error() const;
00066   /** Returns a QString describing the type of error that occurred last. */
00067   QString errorString() const;
00068 
00069   /** Returns the number of milliseconds to wait for devices to respond
00070    * when attempting to discover UPnP-enabled IGDs. */
00071   int discoverTimeout() const;
00072 
00073 signals:
00074   /** Emitted when the UPnP control thread status changes. */
00075   void stateChanged(UPNPControl::UPNPState state);
00076   
00077   /** Emitted when a UPnP error occurs. */
00078   void error(UPNPControl::UPNPError error);
00079  
00080 protected:
00081   /** Constructor. Initializes and starts a thread in which all blocking UPnP
00082    * operations will be performed. */
00083   UPNPControl();
00084   /** Destructor. cleanup() should be called before the object is destroyed. */
00085   ~UPNPControl();
00086 
00087   /** Sets the most recent UPnP-related error to <b>error</b> and emits the
00088    * error() signal.
00089    * \sa error
00090    */
00091   void setError(UPNPError error);
00092   
00093   /** Sets the current UPnP state to <b>state</b> and emits the stateChanged()
00094    * signal.
00095    * \sa stateChanged
00096    */
00097   void setState(UPNPState state);
00098 
00099 private:
00100   static UPNPControl* _instance; /**< UPNPControl singleton instance. */
00101 
00102   quint16 _forwardedORPort; /**< Currently forwarded ORPort. */
00103   quint16 _forwardedDirPort; /**< Currently forwarded DirPort. */
00104   QMutex* _mutex; /**< Mutex around variables shared with UPNPControlThread. */
00105   UPNPError _error; /**< Most recent UPNP error. */
00106   UPNPState _state; /**< Current UPNP status. */
00107 
00108   friend class UPNPControlThread;
00109   UPNPControlThread* _controlThread; /**< Thread used for UPnP operations. */
00110 };
00111 
00112 #endif
00113