Doxygen comments, removed incomplete unused event handling for VNC RW access, introduced terminateVnc method in VncWindow

1 files changed, 79 insertions, 35 deletions

diff --git a/src/client/vnc/vncthread.cpp b/src/client/vnc/vncthread.cpp
index 068a88d..fe52283 100644
--- a/src/client/vnc/vncthread.cpp
+++ b/src/client/vnc/vncthread.cpp
@@ -21,7 +21,13 @@
 
 #include <netinet/tcp.h>
 
-// greatest common divisor
+/**
+ * Calc greatest common divisor.
+ *
+ * @param a one number
+ * @param b another number
+ * @return greatest common divisor of a and b
+ */
 static int gcd(int a, int b)
 {
 	if (b == 0)
@@ -29,6 +35,14 @@ static int gcd(int a, int b)
 	return gcd(b, a % b);
 }
 
+/**
+ * Initialize this VNC client connection worker thread.
+ *
+ * @param host The IP address of the VNC server we're going to connect to
+ * @param port The port of the VNC server
+ * @param passwd The password of the VNC server
+ * @param quality The desired quality level for the VNC stream
+ */
 VncThread::VncThread(QString host, int port, QString passwd, int quality) :
 	QThread(), _frameBuffer(NULL), _painter(NULL), _hasNewLocalSize(false), _run(true)
 {
@@ -42,7 +56,6 @@ VncThread::VncThread(QString host, int port, QString passwd, int quality) :
 	moveToThread(this);
 }
 
-// ALWAYS delete this class from another thread using delete, not deleteLater, or you will deadlock the thread
 VncThread::~VncThread()
 {
 	qDebug("VNC worker destructor called.");
@@ -60,7 +73,16 @@ VncThread::~VncThread()
 		delete _painter;
 }
 
-// Calc matching pixel borders for both resolutions to prevent artifacts through bilinear scaling
+/**
+ * When using image scaling, calc matching pixel borders for both
+ * resolutions to prevent artifacts through bilinear scaling.
+ * If you simply round to the nearest number when scaling, you would
+ * slightly stretch or shrink the image area, which leads to strange
+ * sub-pixel-movements of parts of the image when being updated.
+ * The values calculated here are used to determine a larger area around
+ * the area that should actually be updated, that will not cause any
+ * artifacts when scaling down/up.
+ */
 void VncThread::calcScaling()
 {
 	if (_localSize.isEmpty() || _localSize.width() == 0 || _localSize.height() == 0)
@@ -80,6 +102,11 @@ void VncThread::calcScaling()
 ////////////////////////////////////////////////////////////////////////////////
 // Public
 
+/**
+ * Tell the client that the size of the viewer window has changed.
+ *
+ * @param size The new size of the viewer window
+ */
 void VncThread::setTargetSize(const QSize size)
 {
 	if (_localSize == size)
@@ -90,6 +117,16 @@ void VncThread::setTargetSize(const QSize size)
 	_hasNewLocalSize = true;
 }
 
+/**
+ * Worker thread's mainloop, connecting to the VNC server and handling the connection.
+ * The vnc client library is written in a blocking manner, so we just do everything in
+ * our own thread and just hand over the image updates to the vnc client window, which
+ * resides in the application's main thread.
+ *
+ * This thread checks if the vnc window signaled us to stop and if so, it deletes itself.
+ * This means that you should *never* delete this thread from anywhere. Just call VncThread::stop()
+ * and wait for it to delete itself.
+ */
 void VncThread::run()
 {
 	qDebug("[%s] VNC client started.", metaObject()->className());
@@ -160,6 +197,11 @@ void VncThread::run()
 	QThread::run();
 }
 
+/**
+ * Get name of the VNC server's desktop.
+ *
+ * @return Name of the remote desktop
+ */
 const QString VncThread::getDesktopName() const
 {
 	if (_client == NULL || _client->desktopName == NULL)
@@ -167,24 +209,16 @@ const QString VncThread::getDesktopName() const
 	return QString(_client->desktopName);
 }
 
-void VncThread::mouseEvent(int x, int y, int buttonMask)
-{
-	//QMutexLocker lock(&mutex);
-	if (!_run)
-		return;
-
-	_eventQueue.enqueue(new PointerEvent(x, y, buttonMask));
-}
-
-void VncThread::keyEvent(int key, bool pressed)
-{
-	//QMutexLocker lock(&mutex);
-	if (!_run)
-		return;
-
-	_eventQueue.enqueue(new KeyEvent(key, pressed));
-}
-
+/**
+ * Handle update of an area of the VNC framebuffer. Will do any scaling
+ * if necessary and then emit the imageUpdated signal, so the VncWindow
+ * knows that it needs to redraw.
+ *
+ * @param x X offset of the area in the framebuffer that changed
+ * @param y Y offset of the area in the framebuffer that changed
+ * @param w width of the area in the framebuffer that changed
+ * @param h height of the area in the framebuffer that changed
+ */
 void VncThread::processImageUpdate(const int x, const int y, const int w, const int h)
 {
 	if (_srcStepX > 1 || _srcStepY > 1)
@@ -223,14 +257,26 @@ void VncThread::processImageUpdate(const int x, const int y, const int w, const
 
 // *** callback stuff ***
 
-// the vnc lib is requesting the connection password
+/**
+ * Callback for the vnc client lib: The VNC server is requesting a password.
+ *
+ * @param client Struct representing the connection to the server.
+ * @return A strdup()ed copy of the password we'll try to connect with.
+ * 			The memory if free()d by the vnc client library.
+ */
 char* VncThread::passwdHandler(rfbClient *client)
 {
 	VncThread* t = (VncThread*)rfbClientGetClientData(client, 0);
 	return strdup(t->_passwd.toUtf8());
 }
 
-// the vnc lib is telling us the size and bit depth of the remote screen
+/**
+ * Callback for the vnc client lib: The size of the remote screen has
+ * been changed, so we're supposed to reallocate the local frame buffer.
+ *
+ * @param client Struct representing the connection to the server.
+ * @return true (signaling the vnc client that we successfully allocated a buffer)
+ */
 rfbBool VncThread::frameBufferHandler(rfbClient *client)
 {
 	VncThread *t = (VncThread*)rfbClientGetClientData(client, 0);
@@ -293,20 +339,18 @@ rfbBool VncThread::frameBufferHandler(rfbClient *client)
 	return true;
 }
 
+/**
+ * Callback for the vnc client lib: A part of the frame buffer has changed. That means we have to
+ * apply scaling if necessary, and then cause the vnc window to redraw the corresponding area.
+ *
+ * @param client Struct representing the connection to the server.
+ * @param x X offset of the area in the framebuffer that changed
+ * @param y Y offset of the area in the framebuffer that changed
+ * @param w width of the area in the framebuffer that changed
+ * @param h height of the area in the framebuffer that changed
+ */
 void VncThread::updateImage(rfbClient* client, int x, int y, int w, int h)
 {
 	VncThread* t = (VncThread*)rfbClientGetClientData(client, 0);
 	t->processImageUpdate(x, y, w, h);
 }
-
-// *** event stuff ***
-
-void PointerEvent::fire(rfbClient* cl)
-{
-	SendPointerEvent(cl, _x, _y, _buttonMask);
-}
-
-void KeyEvent::fire(rfbClient* cl)
-{
-	SendKeyEvent(cl, _key, _pressed);
-}