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

Generated on 31 Mar 2010 for Vidalia by  doxygen 1.6.1