Merge branch 'input-events'

Conflicts:
	doc/LaTeX/devel/0300-pvs.tex

8 files changed, 199 insertions, 2 deletions

diff --git a/doc/LaTeX/bilder/menu-key.png b/doc/LaTeX/bilder/menu-key.png
new file mode 100644
index 0000000..8cec826
--- /dev/null
+++ b/doc/LaTeX/bilder/menu-key.png
diff --git a/doc/LaTeX/bilder/vnc-frame-buttons.png b/doc/LaTeX/bilder/vnc-frame-buttons.png
new file mode 100644
index 0000000..0a0a69d
--- /dev/null
+++ b/doc/LaTeX/bilder/vnc-frame-buttons.png
diff --git a/doc/LaTeX/bilder/vnc-frame-buttons.xcf b/doc/LaTeX/bilder/vnc-frame-buttons.xcf
new file mode 100644
index 0000000..faf5261
--- /dev/null
+++ b/doc/LaTeX/bilder/vnc-frame-buttons.xcf
diff --git a/doc/LaTeX/devel/0100-build.tex b/doc/LaTeX/devel/0100-build.tex
index f5cf05e..66d94da 100644
--- a/doc/LaTeX/devel/0100-build.tex
+++ b/doc/LaTeX/devel/0100-build.tex
@@ -22,6 +22,8 @@ Der Pool Video Switch benötigt zum Kompilieren folgende Pakete (und ihre Abhän
 	Dies wird nur benötigt, falls Unterstützung weiterer Sprachen implementiert werden soll, da in diesem Paket das Hilfsprogramm \textbf{linguist} enthalten ist.
  \item cmake >= 2.4.0\\
 	Eingesetztes Buildsystem und der Makefile-Generator. Um distributionsspezifische Pakete zu erzeugen wird CPack benutzt.
+ \item libxtst-dev, libxi-dev\\
+	Diese Bibliotheken dienen zur Implementierung der Fernsteuerungsfunktionen.
 \end{itemize}
 
 \section{Kompilieren aus Quellen}
diff --git a/doc/LaTeX/devel/0300-pvs.tex b/doc/LaTeX/devel/0300-pvs.tex
index a2069de..4978571 100644
--- a/doc/LaTeX/devel/0300-pvs.tex
+++ b/doc/LaTeX/devel/0300-pvs.tex
@@ -235,6 +235,164 @@ Falls innerhalb einer festgesetzten Zeit (30 Sekunden) keine MCASTFTRETRY-Nachri
 beginnt die Übertragung.
 Die Nachricht MCASTFTCONFIG dient zum Setzen netzwerkweiter Parameter von der Steuerkonsole aus.
 
+\section{Fernsteuerung}
+
+Die Fernsteuerung eines Clients erfolgt durch den clientseitigen Empfang von \texttt{PVSCOMMAND}-Nachrichten
+mit dem Ident \texttt{INPUTEVENT}.
+Dieser ist die Base64-kodierte Binärdarstellung eines Eingabeereignisses angehängt, das
+clientseitig nachvollzogen werden soll.
+\begin{table}
+ \begin{tabular}{|l|l|p{4cm}|p{4cm}|}
+  \hline
+  \textbf{\texttt{type}} & \textbf{\texttt{code}} & \textbf{\texttt{value}} & \textbf{Beschreibung} \\
+  \hline
+  \multirow{2}{*}{\texttt{ET\_KEY}} & 
+    \texttt{EC\_PRESS} & 
+    \multirow{2}{4cm}{Auslösende Taste und gehaltene Modifikatortasten} & 
+    Taste gedrückt \\
+  \cline{2-2}\cline{4-4}
+  &
+    \texttt{EC\_RELEASE} &
+    &
+    Taste losgelassen\newline \\
+  \hline
+  \multirow{2}{*}{\texttt{ET\_BUTTON}} &
+    \texttt{EC\_PRESS} &
+    \multirow{2}{4cm}{Auslösende und
+    gedrückte Maustasten} &
+    Maustaste gedrückt \\
+  \cline{2-2}\cline{4-4}
+  &
+    \texttt{EC\_RELEASE} &
+    &
+    Maustaste losgelassen \\
+  \hline
+  \texttt{ET\_POINTER} &
+    --- &
+    Absolute Koordinaten &
+    Mauszeiger bewegt \\
+  \hline
+  \multirow{4}{*}{\texttt{ET\_SPECIAL}} &
+    \texttt{EC\_REBOOT} &
+    --- &
+    Systemneustart \\
+  \cline{2-4}
+  &
+    \texttt{EC\_KILL\_X} &
+    --- &
+    X-Server töten \\
+  \cline{2-4}
+  &
+    \texttt{EC\_SYSRQ} &
+    Kommando &
+    Magic-SysRq-Taste \\
+  \cline{2-4}
+  &
+    \texttt{EC\_SAY\_HELLO} &
+    --- &
+    Harmloses Kommando für Funktionstest \\
+  \hline
+ \end{tabular}
+ \caption{Mögliche Eingabeereignisse\label{tab:input-events}\index{Eingabeereignis!\texttt{InputEvent}}}
+\end{table}
+Tabelle \ref{tab:input-events} zeigt die möglichen Eingabeereignisse.
+Eingabeereignisse werden durch die PVS Input Library (libpvsinput) behandelt,
+deren Funktion an dieser Stelle dargestellt werden soll.
+
+\subsection{Behandlung eines Eingabeereignisses}
+\index{Eingabeereignis!Behandlung}
+
+Ein Eingabeereignis durchläuft die folgenden Stationen:
+\begin{enumerate}
+ \item Die Steuerkonsole generiert ein Eingabeereignis und übergibt dieses an die Netzwerktransportschicht.
+ \item Der PVS-Client empfängt das Eingabeereignis und übergibt die Behandlung einer Instanz der
+  Klasse \texttt{InputEventHandlerChain}\index{Klasse!\texttt{InputEventHandlerChain}}.
+ \item Die Klasse \texttt{InputEventHandlerChain} arbeitet eine Liste von Instanzen der Klasse 
+  \texttt{InputEventHandler}\index{Klasse!\texttt{InputEventHandler}} der Reihe nach ab, um zu sehen, ob eine dieser Instanzen
+  das Ereignis bearbeiten kann.
+ \item Falls die betrachtete Instanz das Ereignis bearbeiten kann, wird geprüft, ob der dafür
+  nötige Sicherheitskontext vorhanden ist.
+ \item Falls dies ebenfalls der Fall ist, wird die entsprechende Aktion in einer implementierung
+  der abstrakten Methode \texttt{InputEventHandler::handle} ausgeführt und die weitere Bearbeitung
+  beendet.
+ \item Falls keiner der vorherigen Handler das Ereignis behandelt hat, wird es durch
+  die Klasse \texttt{PrivilegedHandlerForwarder}\index{Klasse!\texttt{PrivilegedHandlerForwarder}} an den zusätzlichen Daemon \texttt{pvsprivinputd}
+  weitergegeben.
+ \item Der \texttt{pvsprivinputd}\index{pvsprivinputd} besitzt ebenfalls eine \texttt{InputEventHandlerChain}, die
+  nach dem gleichen Muster bearbeitet wird.
+  Falls hierbei kein passender Handler gefunden wird, wird das Ereignis in eine Logdatei geschrieben
+  und die Bearbeitung aufgegeben.
+\end{enumerate}
+Ereignishandler sind implementiert für Maus- und Tastatureingaben unter Linux/X11 (mit Hilfe der XTest-Erweiterung),
+sowie zur Simulation von Strg+Alt+Entf, Strg+Alt+Rück und Magic SysRq.
+
+\subsection{Erweiterungen}
+
+Weitere Eingabehandler lassen sich der libpvsinput hinzufügen.
+Dazu muss eine Klasse bereitgestellt werden, die von der Template-Klasse
+\texttt{InputEventHandler} erbt.
+Diese akzeptiert eine variable Anzahl\footnote{%
+  Bis zu 16, diese Zahl lässt sich jedoch durch Neugenerierung
+  der Datei \texttt{src/input/detail/ typelist\_autogen.h} erhöhen. 
+  Ein entsprechendes Programm ist im Quellcode zu finden.}
+von Templateparametern, die verschiedene Aspekte der Eingabeereignisbehandlung konfigurieren.
+
+Durch die Angabe eines Templateparameters \texttt{input\_policy::Match<\textit{typ}, \textit{code}, \textit{wert}>}\index{Klasse!\texttt{input\_policy::Match}},
+wobei \textit{code} und \textit{wert} weggelassen werden können, wird spezifiziert,
+dass der betreffende Handler nur für Eingabeereignisse mit den entsprechenden Feldwerten aufgerufen wird.
+Wird kein solcher Parameter angegeben, wird der betreffende Handler niemals aufgerufen.
+Mehrere \texttt{Match}-Parameter werden mittels logischem ODER verknüpft.
+
+Ein Templateparameter der Form \texttt{input\_policy::Require<\textit{Merkmal\dots}>}\index{Klasse!\texttt{input\_policy::Require}}
+gibt an, dass dieser Handler nur auf einem System lauffähig ist, das die entsprechenden \textit{Merkmale}
+aufweist.
+Eine Liste von Systemmerkmalen wird in der Datei \texttt{src/input/detail/systemTraits.h}
+zentral verwaltet.
+Hier lassen sich neue Merkmale mit Hilfe des Makros \texttt{DEFINE\_SYSTEM\_TRAIT} definieren
+und mit Hilfe des Präprozessors zwischen den Zeilen \texttt{BEGIN\_SYSTEM\_TRAITS} und
+\texttt{END\_SYSTEM\_TRAITS} einfügen.
+Diese Vorgehensweise beschränkt die Nutzung des Präprozessors auf eine Datei.
+Wird kein \texttt{Require}-Parameter angegeben, so wird der entsprechende Handler als
+immer lauffähig eingestuft.
+Mehrere \texttt{Require}-Parameter werden mittels logischem ODER verknüpft.
+
+Weiterhin kann ein Templateparameter der Form \texttt{input\_policy::Security<\textit{Richtlinie}>}\index{Klasse!\texttt{input\_policy::Security}}
+angegeben werden. Hierbei stehen für \textit{Richtlinie} die Klassen \texttt{input\_policy::AllowLocal\-OrPrivileged}
+oder \texttt{input\_policy::AllowEverybody} zur Verfügung.
+Hierdurch wird bestimmt, welche Sicherheitsanforderungen zur Ausführung des Handlers erfüllt sein
+müssen.
+Die Richtlinie \texttt{input\_policy::AllowLocalOrPrivileged} bestimmt, dass nur Benutzer,
+deren Sitzung lokal ist, oder solche, die nach der Konfiguration des pvsprivinputd als privilegiert
+gelten, die entsprechende Aktion aufrufen dürfen (hierbei geht es um den Benutzer, der den PVS-Client
+ausführt, und nicht den Benutzer, der die Steuerkonsole bedient).
+Die Richtlinie \texttt{input\_policy::AllowEverybody} erlaubt die Ausführung der Aktion ohne
+besonderen Sicherheitskontext.
+Neue Sicherheitsrichtlinien der Form \texttt{input\_policy::Security<\textit{T}>} lassen sich
+nutzen, indem eine Klasse \textit{T} eingeführt wird, die eine Methode\\
+\makebox[1cm]{}\texttt{static bool allow(InputEventContext const*)}\\
+besitzt, an die die Entscheidung, ob eine Aktion zuzulassen ist, delegiert wird.
+
+Der zu implementierende Eingabehandler braucht weiterhin eine Implementierung der abstrakten
+Methode\\
+\makebox[1cm]{}\texttt{virtual void handle(InputEvent const\&, InputEventContext const*)},\\
+in der die entsprechende Aktion ausgeführt wird.
+
+Die Aufnahme des neuen Handlers in die Liste der abzuarbeitenden Handle erfolgt,
+je nachdem ob erweiterte Berechtigungen zur Bearbeitung notwendig sind,
+in einer der Dateien \texttt{privilegedHandlerChain.cpp} oder \texttt{unprivilegedHandler\-Chain.cpp}
+in \texttt{src/input}, wo dem Kettenaufruf eine Zeile der Form\\
+\makebox[1cm]{}\texttt{.add<\textit{Handler}>()}\\
+hinzugefügt wird.
+Die Verwendung des Präprozessors zum Ausschluss von Handlern, die auf dem
+Zielsystem nicht lauffähig sind, ist an dieser Stelle nicht notwendig und wird durch die
+\texttt{Require}-Richtlinie umgesetzt.
+Notwendig ist lediglich, die Übersetzung des Handlers auf inkompatiblen Systemen zu verhindern.
+Dies kann mit Hilfe des Build-Systems oder durch die Klammerung der gesamten Übersetzungseinheit
+in Präprozessorbedingungen geschehen.
+
+Eine API-Referenz zur libpvsinput (Stand: 4.~November~2010) findet sich im Projektwiki
+unter \url{http://lab.openslx.org/projects/pvs/wiki/RemoteKeyMouse}.
+
 \section{Netzwerkkommunikation}
 \index{Netzwerkkommunikation}
 
@@ -278,6 +436,7 @@ PVSCOMMAND & VNCSRVRESULT & result code & Der Rückgabewert des pvs-vncsrv Skrip
 PVSCOMMAND & MCASTFTANNOUNCE & sender transferID basename size port & Ankündigung eines Multicast-Transfer \\
 PVSCOMMAND & MCASTFTRETRY & sender transferID & Rückmeldung: Konfiguration des Multicast-Empfängers fehlgeschlagen, bitte auf anderem Port noch einmal versuchen \\
 PVSCOMMAND & MCASTFTCONFIG & blob & Multicast-Konfiguration aus dem angehängten Binärblob neu laden \\
+PVSCOMMAND & INPUTEVENT & Base64-kodierte InputEvent-Struktur & Fernsteuerung \\
 PVSMESSAGE & BROADCAST & MESSAGE &\\
 PVSMESSAGE & clientToAdd & & Client hinzufügen (Chat)\\
 PVSMESSAGE & clientToRemove & & Client entfernen (Chat)\\
diff --git a/doc/LaTeX/mystyle-pdf.tex b/doc/LaTeX/mystyle-pdf.tex
index d2993f4..034ae31 100644
--- a/doc/LaTeX/mystyle-pdf.tex
+++ b/doc/LaTeX/mystyle-pdf.tex
@@ -108,3 +108,5 @@
 %  pdftitle={PVS Dokumentation}
   pdftitle={GZ:if expand("\%") == ""|browse confirm w|else|confirm w|endif}
 ]{hyperref}
+
+\usepackage{multirow}
\ No newline at end of file
diff --git a/doc/LaTeX/user/0001-chapter.tex b/doc/LaTeX/user/0001-chapter.tex
index 35f1128..200ffa5 100644
--- a/doc/LaTeX/user/0001-chapter.tex
+++ b/doc/LaTeX/user/0001-chapter.tex
@@ -58,6 +58,40 @@ Für die Verbundene Clients besteht die Möglichkeit die VNC-Quality (HIGH, MEDI
 festlegen, ob die Clients zur Verbindung mit dem pvsmgr ein von System generiertes Passwort eingeben müssen oder nicht. Auf dem Toolbar werden weitere Funktionen wie:
 Screeshots aufnehmen, Chat mit dem einzelnen Client starten oder alle Clients auf einem Klick zu blockieren. Das Blockieren der Clients schließt natürlich der Dozent-Rechner
 aus. Der Dozent-Rechner hebt sich von einem anderer verbundenen Machine durch den Rot-Blau Zeichnen neben dem grünen Punkt hervor.
+\\
+Befindet sich die Maus über einem VNC-Frame, so ist über dem Bildschirminhalt eine Reihe von
+Buttons zu sehen (Siehe Abbildung \ref{png:buttons}).
+\begin{figure}[h]
+  \centering
+    \includegraphics[scale=1]{bilder/vnc-frame-buttons.png}
+  \caption{Buttons}
+  \label{png:buttons}
+\end{figure}
+Diese erlauben die Ausfürung der folgenden Funktionen:
+\begin{enumerate}
+ \item Anzeige maximieren
+ \item Bildschirmfoto
+ \item Bildschirm für den Benutzer sperren
+ \item Client zum ,,Super-Client'' machen
+ \item Fernsteuerung aktivieren
+ \item Fernsteuerung aller Clients
+\end{enumerate}
+Wird der Button für die Aktivierung der Fernsteuerung gedrückt, werden alle Tastatur- und Mauseingaben,
+die getätigt werden, während sich der Mauszeiger über dem Anzeigebereich des VNC-Frames befindet,
+an den betreffenden Client gesendet.
+So ist es möglich, die Steuerung von Tastatur und Maus eines angeschlossenen Rechners zu übernehmen.
+\\
+Davon sind auch Tastenkombinationen wie Alt+Tabulator betroffen. 
+Um solche Kombinationen am Rechner der Steuerkonsole einzugeben, muss der Mauszeiger von der
+Anzeigefläche wegbewegt werden.
+\\
+Weiterhin ist auch die Simulation von System-Tastenkombinationen möglich:
+Hierzu muss 5 Sekunden lang die Menü-Taste 
+ \includegraphics[height=1.6ex]{bilder/menu-key.png} 
+gedrückt werden;
+es erscheint dann ein Menü, aus dem die gewünschte Aktion ausgewählt werden kann.
+{\em Vorsicht:} Die Steuerkonsole fragt vor der Ausführung einer Aktion nicht noch einmal
+nach.
 \\ \\
 Im letzten Punkt dieser Abschnitt wollen wir die vorhandenen Tastenkürzel vorstellen.
 
diff --git a/doc/doxconf b/doc/doxconf
index e3e32a6..fefbae6 100644
--- a/doc/doxconf
+++ b/doc/doxconf
@@ -564,7 +564,7 @@ WARN_LOGFILE           = ./doxwarnlog
 # directories like "/usr/src/myproject". Separate the files or directories 
 # with spaces.
 
-INPUT                  = ../pvsClient.h ../pvsClient.cpp ../pvs.h ../pvs.cpp ../pvsDaemon.h ../pvsDaemon.cpp ../src
+INPUT                  = ../src/input
 
 # This tag can be used to specify the character encoding of the source files 
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is 
@@ -1341,7 +1341,7 @@ HIDE_UNDOC_RELATIONS   = YES
 # toolkit from AT&T and Lucent Bell Labs. The other options in this section 
 # have no effect if this option is set to NO (the default)
 
-HAVE_DOT               = NO
+HAVE_DOT               = YES
 
 # By default doxygen will write a font called FreeSans.ttf to the output 
 # directory and reference it in all dot files that doxygen generates. This