1 files changed, 221 insertions, 0 deletions
diff --git a/doc/LaTeX/devel/0300-pvs.tex b/doc/LaTeX/devel/0300-pvs.tex
index 92b36f7..4978571 100644
--- a/doc/LaTeX/devel/0300-pvs.tex
+++ b/doc/LaTeX/devel/0300-pvs.tex
@@ -175,6 +175,223 @@ erzeugt (siehe Konstruktor) und mittels der Methode \texttt{isCommand} erfährt
 Falls ja leitet der Dispatche die Nachricht an die Stelle \texttt{PVS::UpdateChatClients} sonst an die Stelle \texttt{PVS::chat\_receive}, wo die Änderungen in der Client-Liste
 vorgenommen werden oder die Gespräch-Nachricht der GUI abgegeben wird.
 
+\subsection{Multicast-Dateiversand}
+\index{Dateiversand}\index{Multicast}
+
+Der Multicast-Dateiversand geschieht über die Bibliothek \texttt{OpenPGM}\index{OpenPGM}
+(\url{http://code.google.com/p/openpgm/}), die das ,,\textit{Pragmatic General Multicast}''-Protokoll\index{Pragmatic General Multicast}
+(PGM)\index{PGM} implementiert.
+Darin enthalten ist eine Implementierung der \textit{PGMCC}-Methode zur
+Regulierung der Sendebandbreite.
+Vorteil der Verwendung einer externen Bibliothek ist, 
+dass die ,,schwierigen'' Probleme bei der Implementierung einer verlässlichen Datenstrom-orientierten
+Multicast-Übertragung bereits von Netzwerkexperten gelöst wurden.
+
+Die Bibliothek ist in das PVS-System über die interne Bibliothek \texttt{libpvsmcast}\index{libpvsmcast}
+eingebunden (der Quellcode findet sich im Verzeichnis \texttt{src/net/mcast}).
+Diese stellt mit der Klasse \texttt{McastPGMSocket}\index{Klasse!\texttt{McastPGMSocket}} einen
+objektorientierten, ereignisgetriebenen Wrapper zu OpenPGM bereit.
+Die Konfigurationsdaten, die zur Einrichtung einer PGM-Verbindung notwendig sind,
+sind in der Klasse \texttt{McastConfiguration}\index{Klasse!\texttt{McastConfiguration}} verpackt.
+
+Auf der nächsten Ebene wird der Versand einer Datei von den Klassen \texttt{McastSender}\index{Klasse!\texttt{McastSender}}
+und \texttt{McastReceiver}\index{Klasse!\texttt{McastReceiver}} übernommen.
+Diese brechen den Bytestrom der Datei in Pakete auf und formatieren diese wie in Tabelle \ref{tab:mcastpacket}
+gezeigt.
+\begin{table}
+\begin{center}
+\begin{tabular}{|l|l|l|}
+\hline
+\textbf{Format} & \textbf{Feld} & \textbf{Erläuterung} \\
+\hline
+\texttt{quint64} & \texttt{magic\_number} & = 0x0x6d60ad83825fb7f9 \\
+\hline
+\texttt{quint64} & \texttt{offset} & Position des Datenpaketes in der Datei \\
+\hline
+\texttt{QByteArray} & \texttt{data} & Daten \\
+\hline
+\texttt{quint64} & \texttt{checksum} & CRC16-CCITT der vorhergehenden Felder \\
+\hline
+\end{tabular}
+\caption{Paketformat für Multicast-Dateiversand}\label{tab:mcastpacket}\index{Multicast!Paketformat}
+\end{center}
+\end{table}
+Das Paketformat ist mit Hilfe der Qt-eigenen Klasse \texttt{QDataStream} implementiert.
+Numerische Felder werden in Netzwerk-Bytereihenfolge übertragen.
+Das Ende einer Übertragung wird markiert durch ein Paket, in dessen \texttt{offset}
+alle bits gesetzt sind und dessen \texttt{data} die MD5-Prüfsumme der übertragenen Datei
+enthält.
+
+Zur Integration dieser -- prinzipiell von PVS unabhängigen -- Funktionalität
+dienen die Klassen \texttt{PVSIncomingMulticastTransfer}\index{Klasse!\texttt{PVSIncomingMulticastTransfer}}
+und \texttt{PVSOutgoingMulticastTransfer}\index{Klasse!{PVSOutgoingMulticastTransfer}}.
+Diese sorgen hauptsächlich für die Konfiguration der Multicast-Funktionalität mit Hilfe der 
+PVS-Konfiguration und das Generieren der richtigen Signale einerseits in Bezug auf die Benutzerschnittstelle,
+sowie andererseits in Bezug zur Netzwerkkomponente des PVS-Systems.
+
+Ein Client, der eine Datei per Multicast zu versenden wünscht, wählt zufällig einen Port und 
+kündigt diesen mit der Nachricht MCASTFTANNOUNCE an.
+Falls innerhalb einer festgesetzten Zeit (30 Sekunden) keine MCASTFTRETRY-Nachricht eintrifft,
+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}
@@ -216,6 +433,10 @@ PVSCOMMAND & VNC & NO & Verbiete Zugriff \\
 PVSCOMMAND & PING &  & \\
 PVSCOMMAND & VNCREQUEST &  & \\
 PVSCOMMAND & VNCSRVRESULT & result code & Der Rückgabewert des pvs-vncsrv Skripts \\
+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)\\