[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]
[vidalia-svn] r2587: Document the UPNPControl and UPNPControlThread classes. (in vidalia: . branches/upnp/src/vidalia/config)
Author: edmanm
Date: 2008-05-19 22:44:46 -0400 (Mon, 19 May 2008)
New Revision: 2587
Modified:
vidalia/
vidalia/branches/upnp/src/vidalia/config/upnpcontrol.cpp
vidalia/branches/upnp/src/vidalia/config/upnpcontrol.h
vidalia/branches/upnp/src/vidalia/config/upnpcontrolthread.cpp
vidalia/branches/upnp/src/vidalia/config/upnpcontrolthread.h
Log:
r333@thebe: edmanm | 2008-05-19 22:45:26 -0400
Document the UPNPControl and UPNPControlThread classes.
Property changes on: vidalia
___________________________________________________________________
svk:merge ticket from /local/vidalia [r333] on 45a62a8a-8088-484c-baad-c7b3e776dd32
Modified: vidalia/branches/upnp/src/vidalia/config/upnpcontrol.cpp
===================================================================
--- vidalia/branches/upnp/src/vidalia/config/upnpcontrol.cpp 2008-05-20 01:52:22 UTC (rev 2586)
+++ vidalia/branches/upnp/src/vidalia/config/upnpcontrol.cpp 2008-05-20 02:44:46 UTC (rev 2587)
@@ -24,8 +24,10 @@
#include "upnpcontrolthread.h"
+/** UPNPControl singleton instance. */
+UPNPControl* UPNPControl::pInstance = 0;
-UPNPControl* UPNPControl::pInstance = 0;
+/** Returns a pointer to this object's singleton instance. */
UPNPControl* UPNPControl::Instance()
{
if (0 == pInstance)
@@ -33,6 +35,8 @@
return pInstance;
}
+/** Constructor. Initializes and starts a thread in which all blocking UPnP
+ * operations will be performed. */
UPNPControl::UPNPControl()
{
_forwardedORPort = 0;
@@ -42,12 +46,17 @@
controlThread->start();
}
+/** Destructor. cleanup() should be called before the object is destroyed.
+ * \sa cleanup()
+ */
UPNPControl::~UPNPControl()
{
delete mutex;
delete controlThread;
}
+/** Terminates the UPnP control thread and frees memory allocated to this
+ * object's singleton instance. */
void
UPNPControl::cleanup()
{
@@ -56,6 +65,8 @@
pInstance = 0;
}
+/** Sets <b>desiredDirPort</b> and <b>desiredOrPort</b> to the currently
+ * forwarded DirPort and ORPort values. */
void
UPNPControl::getDesiredState(quint16 *desiredDirPort, quint16 *desiredOrPort)
{
@@ -66,6 +77,8 @@
controlThread->wakeup();
}
+/** Sets the desired DirPort and ORPort port mappings to <b>desiredDirPort</b>
+ * and <b>desiredOrPort</b>, respectively. */
void
UPNPControl::setDesiredState(quint16 desiredDirPort, quint16 desiredOrPort)
{
Modified: vidalia/branches/upnp/src/vidalia/config/upnpcontrol.h
===================================================================
--- vidalia/branches/upnp/src/vidalia/config/upnpcontrol.h 2008-05-20 01:52:22 UTC (rev 2586)
+++ vidalia/branches/upnp/src/vidalia/config/upnpcontrol.h 2008-05-20 02:44:46 UTC (rev 2587)
@@ -23,28 +23,38 @@
/* Forward declaration to make it build */
class UPNPControlThread;
+
class UPNPControl : public QObject
{
Q_OBJECT
public:
+ /** Returns a pointer to this object's singleton instance. */
static UPNPControl* Instance();
+ /** Terminates the UPnP control thread and frees memory allocated to this
+ * object's singleton instance. */
static void cleanup();
+ /** Sets <b>desiredDirPort</b> and <b>desiredOrPort</b> to the currently
+ * forwarded DirPort and ORPort values. */
void getDesiredState(quint16 *desiredDirPort, quint16 *desiredOrPort);
+ /** Sets the desired DirPort and ORPort port mappings to
+ * <b>desiredDirPort</b> and <b>desiredOrPort</b>, respectively. */
void setDesiredState(quint16 desiredDirPort, quint16 desiredOrPort);
protected:
+ /** Constructor. Initializes and starts a thread in which all blocking UPnP
+ * operations will be performed. */
UPNPControl();
+ /** Destructor. cleanup() should be called before the object is destroyed. */
~UPNPControl();
private:
- static UPNPControl* pInstance;
+ static UPNPControl* pInstance; /**< UPNPControl singleton instance. */
- /* Currently forwarded ports */
- quint16 _forwardedORPort;
- quint16 _forwardedDirPort;
- QMutex *mutex;
- UPNPControlThread *controlThread;
+ quint16 _forwardedORPort; /**< Currently forwarded ORPort. */
+ quint16 _forwardedDirPort; /**< Currently forwarded DirPort. */
+ QMutex *mutex; /**< Mutex around variables shared with UPNPControlThread. */
+ UPNPControlThread *controlThread; /**< Thread used for UPnP operations. */
};
#endif
Modified: vidalia/branches/upnp/src/vidalia/config/upnpcontrolthread.cpp
===================================================================
--- vidalia/branches/upnp/src/vidalia/config/upnpcontrolthread.cpp 2008-05-20 01:52:22 UTC (rev 2586)
+++ vidalia/branches/upnp/src/vidalia/config/upnpcontrolthread.cpp 2008-05-20 02:44:46 UTC (rev 2587)
@@ -9,7 +9,7 @@
*/
/*
-** \file upnpcontrol.h
+** \file upnpcontrolthread.cpp
** \version $Id$
** \brief Thread for configuring UPnP in the background
*/
@@ -30,10 +30,13 @@
#include "upnpcontrol.h"
-#define UPNPCONTROL_DEBUG 1
#define UPNPCONTROL_REINIT_MSEC 300000 // 5 minutes
#define UPNPCONTROL_MAX_WAIT_MSEC 60000 // 1 minute
+#define UPNPCONTROL_DISCOVER_TIMEOUT 2000 // 2 seconds
+
+/** Constructor. <b>control</b> will be used for retrieving the desired port
+ * forwarding state. */
UPNPControlThread::UPNPControlThread(UPNPControl *control)
{
_upnpInitialized = QTime();
@@ -47,12 +50,19 @@
_waitMutex = new QMutex();
}
+/** Destructor. The UPnP control thread must be stopped prior to destroying
+ * this object.
+ * \sa stop()
+ */
UPNPControlThread::~UPNPControlThread()
{
delete _waitCondition;
delete _waitMutex;
}
+/** Thread entry point. The thread has a main loop that periodically wakes up
+ * and updates the configured port mappings. Upon exiting, all port mappings
+ * will be removed. */
void
UPNPControlThread::run()
{
@@ -86,6 +96,10 @@
updatePort(_orPort, 0);
}
+/** Sets up port forwarding according the previously-configured desired state.
+ * The desired state is set using UPNPControl's setDesiredState() method.
+ * \sa UPNPControl::setDesiredState
+ */
void
UPNPControlThread::configurePorts() {
quint16 desiredDirPort, desiredOrPort;
@@ -137,11 +151,16 @@
if (retval) {
QString message;
- QTextStream(&message) << "Failed to configure automatic port forwarding (status: " << retval << ")";
+ QTextStream(&message)
+ << "Failed to configure automatic port forwarding (status: "
+ << retval << ")";
QMessageBox::warning(0, QString("Automatic port forwarding"), message);
}
}
+/** Terminates the UPnP control thread's run() loop.
+ * \sa run()
+ */
void
UPNPControlThread::stop()
{
@@ -161,6 +180,9 @@
wait();
}
+/** Wakes up the UPnP control thread's run() loop.
+ * \sa run()
+ */
void
UPNPControlThread::wakeup()
{
@@ -169,6 +191,8 @@
_waitMutex->unlock();
}
+/** Updates the port mapping for <b>oldPort</b>, changing it to
+ * <b>newPort</b>. */
int
UPNPControlThread::updatePort(quint16 oldPort, quint16 newPort)
{
@@ -177,13 +201,13 @@
#ifdef Q_OS_WIN32
// Workaround from http://trolltech.com/developer/knowledgebase/579
WSAData wsadata;
- if (WSAStartup(MAKEWORD(2,0), &wsadata)!=0) {
+ if (WSAStartup(MAKEWORD(2,0), &wsadata) != 0) {
vWarn("WSAStartup failure while disabling UPnP port forwarding");
}
#endif
- if (_upnpInitialized.isNull() && (oldPort!=0 || newPort !=0)) {
- retval = init_upnp();
+ if (_upnpInitialized.isNull() && (oldPort != 0 || newPort != 0)) {
+ retval = initializeUPNP();
if (0 == retval)
_upnpInitialized = QTime::currentTime();
else
@@ -205,17 +229,19 @@
return retval;
}
-/** Based on http://miniupnp.free.fr/files/download.php?file=xchat-upnp20061022.patch */
+/** Discovers UPnP-enabled IGDs on the network. Based on
+ * http://miniupnp.free.fr/files/download.php?file=xchat-upnp20061022.patch
+ * This method will block for UPNPCONTROL_DISCOVER_TIMEOUT milliseconds. */
int
-UPNPControlThread::init_upnp()
+UPNPControlThread::initializeUPNP()
{
- struct UPNPDev * devlist;
+ struct UPNPDev *devlist;
int retval;
memset(&urls, 0, sizeof(struct UPNPUrls));
memset(&data, 0, sizeof(struct IGDdatas));
- devlist = upnpDiscover(2000, NULL, NULL);
+ devlist = upnpDiscover(UPNPCONTROL_DISCOVER_TIMEOUT, NULL, NULL);
if (NULL == devlist) {
vWarn("upnpDiscover returned: NULL");
return 5;
@@ -233,6 +259,8 @@
return 0;
}
+/** Adds a port forwarding mapping from external:<b>port</b> to
+ * internal:<b>port</b>. Returns 0 on success, or non-zero on failure. */
int
UPNPControlThread::forwardPort(quint16 port)
{
@@ -274,6 +302,8 @@
return 0;
}
+/** Removes the port mapping for <b>port</b>. Returns 0 on success or non-zero
+ * on failure. */
int
UPNPControlThread::disablePort(quint16 port)
{
Modified: vidalia/branches/upnp/src/vidalia/config/upnpcontrolthread.h
===================================================================
--- vidalia/branches/upnp/src/vidalia/config/upnpcontrolthread.h 2008-05-20 01:52:22 UTC (rev 2586)
+++ vidalia/branches/upnp/src/vidalia/config/upnpcontrolthread.h 2008-05-20 02:44:46 UTC (rev 2587)
@@ -30,36 +30,59 @@
/* Forward declaration to make it build */
class UPNPControl;
+
class UPNPControlThread : public QThread
{
Q_OBJECT
public:
+ /** Constructor. <b>control</b> will be used for retrieving the desired port
+ * forwarding state. */
UPNPControlThread(UPNPControl *control);
+ /** Destructor. The UPnP control thread must be stopped prior to destroying
+ * this object. */
~UPNPControlThread();
+ /** Terminates the UPnP control thread's run() loop. */
void stop();
+ /** Wakes up the UPnP control thread's run() loop. */
void wakeup();
protected:
+ /** Thread entry point. The thread has a main loop that periodically wakes
+ * up and updates the configured port mappings. Upon exiting, all port
+ * mappings will be removed. */
void run();
private:
- QTime _upnpInitialized;
- bool _keepRunning;
- UPNPControl *_control;
- QWaitCondition *_waitCondition;
- QMutex *_waitMutex;
- quint16 _dirPort, _orPort;
+ /** Sets up port forwarding according the previously-configured desired
+ * state. The desired state is set using UPNPControl's setDesiredState()
+ * method. */
+ void configurePorts();
+ /** Discovers UPnP-enabled IGDs on the network. This method will block for
+ * UPNPCONTROL_DISCOVER_TIMEOUT milliseconds. */
+ int initializeUPNP();
+ /** Updates the port mapping for <b>oldPort</b>, changing it to
+ * <b>newPort</b>. */
+ int updatePort(quint16 oldPort, quint16 newPort);
+ /** Adds a port forwarding mapping from external:<b>port</b> to
+ * internal:<b>port</b>. Returns 0 on success, or non-zero on failure. */
+ int forwardPort(quint16 port);
+ /** Removes the port mapping for <b>port</b>. Returns 0 on success or
+ * non-zero on failure. */
+ int disablePort(quint16 port);
+
+ QTime _upnpInitialized; /**< Time at which the UPnP state was last set. */
+ bool _keepRunning; /**< True if the control thread should keep running. */
+ UPNPControl *_control; /**< Stores desired UPnP state. */
+ QWaitCondition *_waitCondition; /**< Used to wake up the control thread. */
+ QMutex *_waitMutex; /**< Mutex around shared variables. */
+ quint16 _dirPort; /**< Desired DirPort. */
+ quint16 _orPort; /**< Desired ORPort. */
- /** Used by miniupnpc library */
+ /* Used by miniupnpc library */
struct UPNPUrls urls;
struct IGDdatas data;
char lanaddr[16];
-
- void configurePorts();
- int init_upnp();
- int updatePort(quint16 oldPort, quint16 newPort);
- int forwardPort(quint16 port);
- int disablePort(quint16 port);
};
#endif
+