doc/DP/DP_Network.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %%%  DP - Componente Network  %%%
   3 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   4
   5 \subsection{Classe Network} %%%%%%
   6
   7 \subsubsection*{\large{Descrizione generale}}
   8 Classe astratta. Presenta un'interfaccia semplice e di alto livello al sottosistema per la gestione della rete. L'implementazione è delegata alle sottoclassi concrete \texttt{GameClient} e \texttt{GameServer}, poiché il comportamento varia a seconda se l'applicazione funge da server oppure da client per la partita.
   9
  10 \medskip
  11
  12 \subsubsection*{\large{Attributi}}
  13 \smallskip
  14
  15 \subsubsection{\_gui}
  16 \texttt{private QWidget *\_gui}
  17 \begin{itemize}
  18         \item Puntatore alla finestra di dialogo per l'interazione con l'utente durante la fase di configurazione e avvio di una partita online.
  19         \item Costruzione: copia del puntatore a partire del parametro \texttt{gui} del costruttore della classe; la creazione del \textit{dialog} è compito del componente \textsl{GUI}.
  20         \item Distruzione: l'oggetto puntato verrà distrutto dal componente \textsl{GUI}; questa classe perciò non deve deallocare tale oggetto.
  21         \item Note: non è possibile fare alcuna assunzione sulla validità del puntatore poiché l'oggetto puntato può venire deallocato in qualsiasi momento dal componente \textsl{GUI}.
  22 \end{itemize}
  23
  24 \medskip
  25
  26 \subsubsection*{\large{Operazioni}}
  27 \smallskip
  28
  29 \subsubsection{Network}
  30 \texttt{public Network(QWidget *gui) [constructor]}
  31 \begin{itemize}
  32         \item Parametri e precondizioni: \texttt{gui} deve essere un puntatore non nullo al componente della GUI che ha il compito di interfacciarsi con l'utente nella modalità online; dovrà essere in grado di gestire opportunamente (o ignorare) i segnali emessi dallo strato di rete descritti nel seguito.
  33         \item Comportamento: assegna a \texttt{\_gui} il valore del parametro \texttt{gui}.
  34 \end{itemize}
  35 \smallskip
  36
  37 \subsubsection{\~{}Network}
  38 \texttt{public \~{}Network() [destructor, virtual]}
  39 \begin{itemize}
  40         \item Comportamento: il corpo di questo distruttore è vuoto.
  41 \end{itemize}
  42 \smallskip
  43
  44 \subsubsection{requestMove}
  45 \texttt{public Point requestMove() [abstract]}
  46 \begin{itemize}
  47         \item Valore ritornato e sua semantica: restituisce la coordinata della casella su cui il giocatore remoto ha posizionato la propria pedina. Se il \texttt{Point} restituito è nullo significa che la mossa non è ancora stata ricevuta e quindi il chiamante, se ancora interessato, deve invocare il metodo \texttt{SyncSharedCondition::waitForMove()}, attendendo che lo strato di rete gli notifichi l'avvenuta ricezione della mossa.
  48 \end{itemize}
  49 \smallskip
  50
  51 \subsubsection{setupChat}
  52 \texttt{public void setupChat(ChatWidget *widget) [abstract]}
  53 \begin{itemize}
  54         \item Parametri e precondizioni: \texttt{widget} è un puntatore valido ad un'istanza di \texttt{ChatWidget} che si occupa di interagire con l'utente, mostrandogli e ricevendo da lui i messaggi di chat.
  55         \item Comportamento: collega opportunamente i \textit{sockets} di comunicazione client-server con la parte grafica dell'applicazione tramite segnali e slots. L'esatto comportamento verrà definito nelle sottoclassi che concretizzano questo metodo.
  56 \end{itemize}
  57
  58 \medskip
  59
  60 \subsection{Classe GameClient} %%%%%%
  61
  62 \subsubsection*{\large{Descrizione generale}}
  63 Implementa \texttt{Network}.
  64
  65 \medskip
  66
  67 \subsubsection*{\large{Attributi}}
  68 \smallskip
  69
  70 \subsubsection{\_localPlayer}
  71 \texttt{private int \_localPlayer}
  72 \begin{itemize}
  73         \item Indica l'ID del \uline{giocatore umano} che sta usando quest'istanza dell'applicazione in una partita online. L'ID può essere assegnato esclusivamente dal \uline{server di gioco}. I valori possibili variano nell'intervallo $[-1, 2]$. Il valore $-1$ ha un significato speciale ed è usato quando il server non ha ancora comunicato al client il proprio ID o nel caso in cui si stia partecipando ad una partita in \uline{modalità spettatore}.
  74         \item Costruzione: è inizializzato a $-1$ dal costruttore della classe.
  75 \end{itemize}
  76 \smallskip
  77
  78 \subsubsection{\_server}
  79 \texttt{private ClientSocket *\_server}
  80 \begin{itemize}
  81         \item Rappresenta il canale di comunicazione con il \uline{server di gioco}.
  82         \item Costruzione: allocato e inizializzato dal costruttore.
  83         \item Distruzione: effettuata dal distruttore della classe.
  84 \end{itemize}
  85
  86 \medskip
  87
  88 \subsubsection*{\large{Operazioni}}
  89 \smallskip
  90
  91 \subsubsection{GameClient}
  92 \texttt{public GameClient(QWidget *gui, QString serverAddress, quint16 serverPort) [constructor]}
  93 \begin{itemize}
  94         \item Parametri e precondizioni:
  95         \begin{itemize}
  96                 \item \texttt{gui} deve essere un puntatore non nullo al componente della GUI che ha il compito di interfacciarsi con l'utente nella modalità online; dovrà essere in grado di gestire opportunamente (o ignorare) i segnali emessi da \texttt{\_server} descritti nel seguito.
  97                 \item \texttt{serverAddress} è una stringa contenente l'indirizzo del server a cui connettersi; può essere sia in forma di \textit{hostname} sia in forma di indirizzo IP. Se l'indirizzo IP non è valido o l'\textit{hostname} è inesistente, verrà segnalato un errore.
  98                 \item \texttt{serverPort} è la porta del server a cui connettersi.
  99         \end{itemize}
 100         \item Comportamento:
 101         \begin{itemize}
 102                 \item invoca il costruttore della classe base \texttt{Network(gui)};
 103                 \item inizializza \texttt{\_localPlayer} al valore $-1$;
 104                 \item alloca sullo \textit{heap} un oggetto \texttt{s} di tipo \texttt{QTcpSocket};
 105                 \item inizializza il campo dati \texttt{\_server} con un oggetto di tipo \texttt{ClientSocket}, passando \texttt{s} come parametro al costruttore;
 106                 \item connette il segnale \texttt{s::hostFound()} allo slot \texttt{gui::TODO};
 107                 \item connette il segnale \texttt{s::connected()} allo slot \texttt{gui::TODO};
 108                 \item invoca \verb!s->connectToHost(serverAddress)!;
 109                 \item invoca \verb!s->changeState(StreamSocket::Connecting)!.
 110         \end{itemize}
 111 \end{itemize}
 112 \smallskip
 113
 114 \subsubsection{\~{}GameClient}
 115 \texttt{public \~{}GameClient() [destructor, virtual]}
 116 \begin{itemize}
 117         \item Comportamento: dealloca \texttt{\_server}, il cui distruttore si occuperà di chiudere lo \textit{stream}.
 118 \end{itemize}
 119 \smallskip
 120
 121 \subsubsection{requestMove}
 122 \texttt{public Point requestMove() [virtual]}
 123 \begin{itemize}
 124         \item Comportamento: \verb!_server->changeState(StreamSocket::AwaitingMove)!.
 125         \item Valore ritornato e sua semantica: rispetta il contratto di \\\texttt{Network::requestMove()}.
 126         \item Side effects: \texttt{\_server} transita nello stato ``Awaiting Move''.
 127 \end{itemize}
 128 \smallskip
 129
 130 \subsubsection{setupChat}
 131 \texttt{public void setupChat(ChatWidget *widget) [virtual]}
 132 \begin{itemize}
 133         \item Parametri e precondizioni: \texttt{widget} è un puntatore valido ad un'istanza di \texttt{ChatWidget} che si occupa di interagire con l'utente, mostrandogli e ricevendo da lui i messaggi di chat.
 134         \item Comportamento: collega \texttt{\_server::receivedChatMessage()} a \\\texttt{widget::displayText()} e \texttt{widget::textEntered()} a \\\texttt{\_server::sendChatMessage()}.
 135 \end{itemize}
 136 \smallskip
 137
 138 \subsubsection{setLocalPlayer}
 139 \texttt{private void setLocalPlayer(int id) [slot]}
 140 \begin{itemize}
 141         \item Parametri e precondizioni:
 142         \begin{itemize}
 143                 \item \texttt{id} è un intero compreso nell'intervallo $[-1, 2]$;
 144                 \item \texttt{\_server} si trova nello stato ``Awaiting Game Start''.
 145         \end{itemize}
 146         \item Comportamento: il valore del parametro \texttt{id} viene assegnato a \texttt{\_localPlayer}.
 147         \item Note: questo metodo dovrebbe essere invocato solo come slot collegato al segnale \texttt{ClientSocket::joinAccepted()}.
 148 \end{itemize}
 149
 150 \medskip
 151
 152 \subsection{Classe GameServer} %%%%%%
 153
 154 \subsubsection*{\large{Descrizione generale}}
 155 Implementa ed estende \texttt{Network}.
 156
 157 \medskip
 158
 159 \subsubsection*{\large{Attributi}}
 160 \smallskip
 161
 162 \subsubsection{\_listener}
 163 \texttt{private QTcpServer *\_listener}
 164 \begin{itemize}
 165         \item \textit{Socket} in ascolto sull'indirizzo IPv4 ``\texttt{0.0.0.0}'' che accetta le connessioni in entrata.
 166         \item Costruzione: allocato dal costruttore della classe.
 167         \item Distruzione: effettuata dal distruttore della classe.
 168         \item Note: emette il segnale \texttt{newConnection()} ad ogni nuova connessione in entrata.
 169 \end{itemize}
 170 \smallskip
 171
 172 \subsubsection{\_pendingConnections}
 173 \texttt{private QLinkedList<ServerSocket*> \_pendingConnections}
 174 \begin{itemize}
 175         \item Lista di tutte le connessioni con client che non hanno ancora richiesto di partecipare alla partita.
 176         \item Costruzione: il costruttore della classe crea una lista vuota.
 177         \item Note: tutti i \textit{socket} di questa lista possono trovarsi esclusivamente in uno dei seguenti stati: ``Opening Stream'', ``Fully Opened'', ``Awaiting Join Request''. Quando si riceve un messaggio \texttt{<joinRequest>} valido e accettabile da uno di questi \textit{socket}, è necessario spostare tale \textit{socket} in una delle due liste descritte nel seguito in base alla modalità di gioco richiesta.
 178 \end{itemize}
 179 \smallskip
 180
 181 \subsubsection{\_remotePlayers}
 182 \texttt{private QList<ServerSocket*> \_remotePlayers}
 183 \begin{itemize}
 184         \item Lista delle connessioni con i client che partecipano alla partita come giocatori.
 185         \item Costruzione: il costruttore della classe crea una lista vuota.
 186         \item Note: tutti i \textit{socket} di questa lista possono trovarsi esclusivamente in uno dei seguenti stati: ``Awaiting Players'', ``Playing'', ``Awaiting Move''.
 187 \end{itemize}
 188 \smallskip
 189
 190 \subsubsection{\_spectators}
 191 \texttt{private QList<ServerSocket*> \_spectators}
 192 \begin{itemize}
 193         \item Lista delle connessioni con i client che assistono alla partita in corso come spettatori.
 194         \item Costruzione: il costruttore della classe crea una lista vuota.
 195         \item Note: tutti i \textit{socket} di questa lista possono trovarsi esclusivamente in uno dei seguenti stati: ``Awaiting Players'', ``Playing'', ``Awaiting Move''.
 196 \end{itemize}
 197 \smallskip
 198
 199 \subsubsection{\_gameInProgress}
 200 \texttt{private bool \_gameInProgress}
 201 \begin{itemize}
 202         \item Indica se è in corso una partita.
 203         \item Costruzione: inizializzato a \texttt{false} dal costruttore della classe.
 204         \item Note: verrà impostato a \texttt{true} quando inizia la partita.
 205 \end{itemize}
 206 \smallskip
 207
 208 \subsubsection{\_history}
 209 \texttt{private HistoryModel *\_history}
 210 \begin{itemize}
 211         \item Costruzione: copia del puntatore passato al costruttore della classe.
 212         \item Distruzione: l'oggetto puntato non deve essere distrutto poiché appartiene alla classe \texttt{MainWindow}, la quale si occuperà della sua deallocazione.
 213         \item Note: utilizzato per ottenere lo storico delle mosse da inviare agli spettatori che si connettono al server quando la partita è già iniziata.
 214 \end{itemize}
 215 \smallskip
 216
 217 \subsubsection{\_names}
 218 \texttt{private QStringList \_names}
 219 \begin{itemize}
 220         \item Contiene i nomi di tutti i giocatori e gli spettatori connessi.
 221         \item Costruzione: inizializzato alla lista vuota dal costruttore della classe.
 222         \item Note: vale la seguente relazione:
 223         \begin{itemize}
 224                 \item $\forall i$ tale che $0 \leq i < \mbox{\texttt{\_numberOfPlayers}} \Rightarrow$ \texttt{\_names[}$i$\texttt{]} è il nome del giocatore \texttt{\_remotePlayers[}$i$\texttt{]};
 225                 \item $\forall i$ tale che $i \geq \mbox{\texttt{\_numberOfPlayers}} \Rightarrow$ \texttt{\_names[}$i$\texttt{]} è il nome dello spettatore \texttt{\_spectators[}$i - \mbox{\texttt{\_numberOfPlayers}}$\texttt{]}.
 226         \end{itemize}
 227 \end{itemize}
 228 \smallskip
 229
 230 \subsubsection{\_numberOfPlayers}
 231 \texttt{private int \_numberOfPlayers}
 232 \begin{itemize}
 233         \item Indica il numero di giocatori impostato per la partita.
 234         \item Costruzione: inizializzato dal costruttore della classe a \\\verb!_settings->playersInfo().size()!.
 235 \end{itemize}
 236 \smallskip
 237
 238 \subsubsection{\_turn}
 239 \texttt{private int \_turn}
 240 \begin{itemize}
 241         \item Indica l'ID del giocatore di cui è attualmente il turno.
 242         \item Costruzione: inizializzato a $-1$ dal costruttore della classe.
 243 \end{itemize}
 244 \smallskip
 245
 246 \subsubsection{\_settings}
 247 \texttt{private ServerSettings *\_settings}
 248 \begin{itemize}
 249         \item Viene usato per caricare le opzioni impostate dall'utente in fase di configurazione del \uline{server di gioco}.
 250         \item Costruzione: allocato dal costruttore della classe.
 251         \item Distruzione: effettuata dal distruttore della classe.
 252 \end{itemize}
 253
 254 \medskip
 255
 256 \subsubsection*{\large{Operazioni}}
 257 \smallskip
 258
 259 \subsubsection{GameServer}
 260 \texttt{public GameServer(QWidget *gui, HistoryModel *history) [constructor]}
 261 \begin{itemize}
 262         \item Parametri e precondizioni:
 263         \begin{itemize}
 264                 \item \texttt{gui} deve essere un puntatore non nullo al componente della GUI che ha il compito di interfacciarsi con l'utente nella modalità online; dovrà essere in grado di gestire opportunamente (o ignorare) i segnali emessi dai \textit{socket} di tipo \texttt{ServerSocket} descritti nel seguito.
 265                 \item \texttt{history} è un puntatore non nullo a HistoryModel; la validità di questo puntatore deve essere assicurata durante tutta la vita dell'oggetto.
 266         \end{itemize}
 267         \item Comportamento:
 268         \begin{itemize}
 269                 \item invoca il costruttore della classe base \texttt{Network(gui)};
 270                 \item inizializza i campi dati come precedentemente specificato;
 271                 \item connette il segnale \texttt{\_listener::newConnection()} allo slot \\\texttt{this::handleIncomingConnection()};
 272                 \item invoca \texttt{\_listener->listen(QHostAddress::Any, \\\_settings->serverPort())}.
 273         \end{itemize}
 274 \end{itemize}
 275 \smallskip
 276
 277 \subsubsection{\~{}GameServer}
 278 \texttt{public \~{}GameServer() [destructor, virtual]}
 279 \begin{itemize}
 280         \item Comportamento: dealloca \texttt{\_listener} e \texttt{\_settings}.
 281 \end{itemize}
 282 \smallskip
 283
 284 \subsubsection{requestMove}
 285 \texttt{public Point requestMove() [virtual]}
 286 \begin{itemize}
 287         \item Comportamento: \verb!_remotePlayers[_turn]->changeState(StreamSocket::AwaitingMove)!.
 288         \item Valore ritornato e sua semantica: rispetta il contratto di \\\texttt{Network::requestMove()}.
 289         \item Side effects: il \textit{socket} \texttt{\_remotePlayers[\_turn]} transita nello stato ``Awaiting Move''.
 290 \end{itemize}
 291 \smallskip
 292
 293 \subsubsection{setupChat}
 294 \texttt{public void setupChat(ChatWidget *widget) [virtual]}
 295 \begin{itemize}
 296         \item Parametri e precondizioni: \texttt{widget} è un puntatore valido ad un'istanza di \texttt{ChatWidget} che si occupa di interagire con l'utente, mostrandogli e ricevendo da lui i messaggi di chat.
 297         \item Comportamento: per ogni \textit{socket} \texttt{s} in \texttt{\_remotePlayers} e in \texttt{\_spectators}, collega \texttt{s::receivedChatMessage()} a \texttt{widget::displayText()} e \\\texttt{widget::textEntered()} a \texttt{s::sendChatMessage()}.
 298 \end{itemize}
 299 \smallskip
 300
 301 \subsubsection{handleIncomingConnection}
 302 \texttt{private void handleIncomingConnection() [slot]}
 303 \begin{itemize}
 304         \item Comportamento:
 305         \begin{itemize}
 306                 \item alloca sullo \textit{heap} un nuovo \texttt{ServerSocket s} a partire dal \texttt{QTcpSocket} restituito da \verb!_listener->nextPendingConnection()!;
 307                 \item aggiunge \texttt{s} in coda alla lista \texttt{\_pendingConnections}.
 308         \end{itemize}
 309         \item Note: questo metodo dovrebbe essere invocato solo come slot collegato al segnale \texttt{\_listener::newConnection()}.
 310 \end{itemize}
 311 \smallskip
 312
 313 \subsubsection{handleJoinRequest}
 314 \texttt{private void handleJoinRequest(QString mode, QString name) [slot]}
 315 \begin{itemize}
 316         \item Parametri e precondizioni:
 317         \begin{itemize}
 318                 \item \texttt{mode} e \texttt{name} sono due \texttt{QString} non nulle e non vuote;
 319                 \item la richiesta proviene da un \texttt{ServerSocket} che si trova nello stato ``Awaiting Join Request''.
 320         \end{itemize}
 321         \item Comportamento: vedere diagramma in Figura~\ref{fig:handleJoinRequest}.
 322         \item Side effects: il \texttt{ServerSocket} da cui proviene la richiesta va nello stato ``Awaiting Players'' se la richiesta viene accettata, altrimenti rimane nello stato ``Awaiting Join Request''.
 323         \item Note: questo metodo dovrebbe essere invocato solo come slot collegato al segnale \texttt{s::joinRequested()} per ogni \texttt{s} in \texttt{\_pendingConnections}.
 324 \end{itemize}
 325 \smallskip
 326
 327 \subsubsection{setTurn}
 328 \texttt{private void setTurn(int playerId) [slot]}
 329 \begin{itemize}
 330         \item Parametri e precondizioni:
 331         \begin{itemize}
 332                 \item \texttt{playerId} è un intero compreso nell'intervallo $[0, 2]$;
 333                 \item \texttt{\_gameInProgress} è \texttt{true}.
 334         \end{itemize}
 335         \item Comportamento: il valore del parametro \texttt{playerId} viene assegnato a \texttt{\_turn}.
 336         \item Note: questo metodo dovrebbe essere invocato solo come slot collegato al segnale \texttt{GameLoop::turn()}.
 337 \end{itemize}
 338
 339 \medskip
 340
 341 \subsection{Classe StreamSocket} %%%%%%
 342
 343 \subsubsection*{\large{Descrizione generale}}
 344 Derivata in modo protetto da \texttt{QXmlStreamReader} e \texttt{QXmlStreamWriter}. Implementa le funzionalità di basso livello necessarie a scambiare i messaggi del protocollo comuni a client e server. Il protocollo è basato su uno \textit{stream} XML bidirezionale trasmesso su una connessione TCP. Tutte le comunicazioni con l'host remoto vengono effettuate attraverso la classe \texttt{QTcpSocket}.
 345
 346 \medskip
 347
 348 \subsubsection*{\large{Attributi}}
 349 \smallskip
 350
 351 \subsubsection{\_supportedProtocolVersion}
 352 \texttt{protected QString \_supportedProtocolVersion [const, static]}
 353 \begin{itemize}
 354         \item Indica la versione del protocollo supportata da questa classe. La versione attuale è ``$1.0$''.
 355         \item Note: le sottoclassi possono scegliere di ignorare il valore di questo attributo qualora esse implementino delle estensioni del protocollo che ne cambiano la versione.
 356 \end{itemize}
 357 \smallskip
 358
 359 \subsubsection{\_socket}
 360 \texttt{protected QTcpSocket *\_socket}
 361 \begin{itemize}
 362         \item Costruzione: ad opera del costruttore.
 363         \item Distruzione: effettuata dal distruttore della classe.
 364         \item Note: Tutte le comunicazioni con l'host remoto devono passare attraverso questa classe.
 365 \end{itemize}
 366 \smallskip
 367
 368 \subsubsection{\_buffer}
 369 \texttt{private QLinkedList<Move> \_buffer}
 370 \begin{itemize}
 371         \item \`E una coda FIFO delle mosse ricevute dai giocatori remoti ma non ancora inoltrate a \texttt{GameLoop}.
 372         \item Costruzione: il costruttore crea una lista vuota.
 373 \end{itemize}
 374 \smallskip
 375
 376 \subsubsection{\_state}
 377 \texttt{private ProtocolState \_state}
 378 \begin{itemize}
 379         \item Indica lo stato in cui si trova il \textit{socket}.
 380         \item Costruzione: inizializzato dal costruttore.
 381         \item Note: può essere modificato solo dal metodo \texttt{changeState()}.
 382 \end{itemize}
 383
 384 \medskip
 385
 386 \subsubsection*{\large{Operazioni}}
 387 \smallskip
 388
 389 \subsubsection{StreamSocket}
 390 \texttt{protected StreamSocket(QTcpSocket *socket) [constructor]}
 391 \begin{itemize}
 392         \item Parametri e precondizioni: \texttt{socket} è un puntatore non nullo ad un \texttt{QTcpSocket}.
 393         \item Comportamento:
 394         \begin{itemize}
 395                 \item assegna \texttt{socket} al campo dati \texttt{\_socket};
 396                 \item inizializza \texttt{\_state} a \texttt{Unconnected};
 397                 \item collega \texttt{\_socket::readyRead()} a \texttt{parseData()} e \texttt{\_socket::error()} a \texttt{handleError()}.
 398         \end{itemize}
 399         \item Note: questo costruttore è protetto poiché la classe \texttt{StreamSocket} non può essere usata direttamente.
 400 \end{itemize}
 401 \smallskip
 402
 403 \subsubsection{\~{}StreamSocket}
 404 \texttt{public \~{}StreamSocket() [destructor, virtual]}
 405 \begin{itemize}
 406         \item Comportamento: chiude lo \textit{stream} XML invocando \texttt{closeStream()} e successivamente dealloca \texttt{\_socket}.
 407 \end{itemize}
 408 \smallskip
 409
 410 \subsubsection{state}
 411 \texttt{public ProtocolState state() [const]}
 412 \begin{itemize}
 413         \item Comportamento: ritorna l'attuale valore di \texttt{\_state}.
 414 \end{itemize}
 415 \smallskip
 416
 417 \subsubsection{changeState}
 418 \texttt{protected void changeState(ProtocolState state)}
 419 \begin{itemize}
 420         \item Parametri e precondizioni: \texttt{state} è lo stato \textit{target} della transizione.
 421         \item Comportamento: assegna \texttt{state} a \texttt{\_state}.
 422         \item Note: questo è l'unico metodo da usare per effettuare transizioni di stato, in particolare per le sottoclassi.
 423 \end{itemize}
 424 \smallskip
 425
 426 \subsubsection{sendChatMessage}
 427 \texttt{public void sendChatMessage(QString msg) [slot, virtual]}
 428 \begin{itemize}
 429         \item Parametri e precondizioni: \texttt{msg} è una stringa non nulla e non vuota.
 430         \item Comportamento: crea e invia all'host remoto un messaggio XML di tipo \texttt{<chatMessage>} contenente \texttt{msg}.
 431 \end{itemize}
 432 \smallskip
 433
 434 \subsubsection{sendMove}
 435 \texttt{public void sendMove(Move move) [slot, virtual]}
 436 \begin{itemize}
 437         \item Comportamento: crea e invia all'host remoto un messaggio XML di tipo \texttt{<move>} contenente la forma serializzata di \texttt{move}.
 438 \end{itemize}
 439 \smallskip
 440
 441 \subsubsection{openStream}
 442 \texttt{protected void openStream() [slot, virtual]}
 443 \begin{itemize}
 444         \item Comportamento: apre l'elemento XML \texttt{<stream>} ponendo l'attributo \texttt{version} pari a \texttt{\_supportedProtocolVersion} e invoca \\\verb!changeState(StreamSocket::OpeningStream)!.
 445         \item Note: eventuali sottoclassi che vogliono estendere il protocollo cambiandone la versione devono ridefinire questo metodo per poter inviare il numero di versione corretto.
 446 \end{itemize}
 447 \smallskip
 448
 449 \subsubsection{closeStream}
 450 \texttt{protected void closeStream() [slot, virtual]}
 451 \begin{itemize}
 452         \item Comportamento:
 453         \begin{itemize}
 454                 \item chiude tutti gli elementi XML precedentemente aperti, compreso l'elemento radice;
 455                 \item invoca \verb!_socket->disconnectFromHost()!;
 456                 \item invoca \verb!this->changeState(StreamSocket::Closed)!.
 457         \end{itemize}
 458         \item Side effects: l'oggetto effettua una transizione verso lo stato ``Closed''.
 459 \end{itemize}
 460 \smallskip
 461
 462 \subsubsection{handleError}
 463 \texttt{protected void handleError(QAbstractSocket::SocketError error) [slot, virtual]}
 464 \begin{itemize}
 465         \item Comportamento: TODO.
 466         \item Note: questo metodo dovrebbe essere invocato solo come slot collegato al segnale \texttt{\_socket::error()}.
 467 \end{itemize}
 468 \smallskip
 469
 470 \subsubsection{parseData}
 471 \texttt{protected void parseData() [slot, virtual]}
 472 \begin{itemize}
 473         \item Comportamento: effettua il parsing dei messaggi provenienti dall'host remoto e si comporta come descritto in Tabella%TODO.
 474         \item Note: gestisce solo i messaggi presenti in Tabella~X. Deve essere ridefinito dalle classi derivate per estendere il protocollo o per poterne modificare il comportamento. Questo metodo dovrebbe essere invocato solo come slot collegato al segnale \texttt{\_socket::readyRead()}.
 475 \end{itemize}
 476 \smallskip
 477
 478 \subsubsection{playerJoined}
 479 \texttt{protected void playerJoined(int id, QString name, QString type) [signal]}
 480 \begin{itemize}
 481         \item Note: emesso quando un nuovo giocatore remoto si è unito alla partita. I parametri del segnale rappresentano rispettivamente il suo ID ($-1$ se è uno spettatore), il nome e il tipo (``player'' o ``spectator'').
 482 \end{itemize}
 483 \smallskip
 484
 485 \subsubsection{playerLeft}
 486 \texttt{protected void playerLeft(int id) [signal]}
 487 \begin{itemize}
 488         \item Note: emesso quando il giocatore remoto con ID uguale al parametro \texttt{id} ha abbandonato la partita o non è più raggiungibile a causa di problemi nella rete.
 489 \end{itemize}
 490 \smallskip
 491
 492 \subsubsection{receivedChatMessage}
 493 \texttt{protected void receivedChatMessage(QString msg) [signal]}
 494 \begin{itemize}
 495         \item Note: questo segnale viene emesso ogni volta che si riceve un messaggio di chat dall'host remoto.
 496 \end{itemize}
 497 \smallskip
 498
 499 \subsubsection{receivedMove}
 500 \texttt{protected void receivedMove(Move move) [signal]}
 501 \begin{itemize}
 502         \item Note: emesso quando si riceve un messaggio di tipo \texttt{<move>}. Segnala che un giocatore remoto ha effettuato la mossa indicata dal parametro \texttt{move}.
 503 \end{itemize}
 504 \smallskip
 505
 506 \subsubsection{startGame}
 507 \texttt{protected void startGame() [signal]}
 508 \begin{itemize}
 509         \item Note: emesso quando si riceve il messaggio \texttt{<startGame>} dal server. Indica che tutti i giocatori sono connessi e la partita può iniziare.
 510 \end{itemize}
 511
 512 \medskip
 513
 514 \subsection{Classe ClientSocket} %%%%%%
 515
 516 \subsubsection*{\large{Descrizione generale}}
 517 Estende \texttt{StreamSocket}.
 518
 519 \medskip
 520
 521 \subsubsection*{\large{Operazioni}}
 522 \smallskip
 523
 524 \subsubsection{ClientSocket}
 525 \texttt{public ClientSocket(QTcpSocket *socket) [constructor]}
 526 \begin{itemize}
 527         \item Parametri e precondizioni: \texttt{socket} è un puntatore non nullo ad un \texttt{QTcpSocket}.
 528         \item Comportamento:
 529         \begin{itemize}
 530                 \item invoca il costruttore della classe base passando \texttt{socket} come parametro;
 531                 \item connette il segnale \texttt{\_socket::connected()} allo slot \texttt{this::openStream()}.
 532         \end{itemize}
 533 \end{itemize}
 534 \smallskip
 535
 536 \subsubsection{joinGame}
 537 \texttt{public void joinGame(QString mode, QString name) [slot]}
 538 \begin{itemize}
 539         \item Parametri e precondizioni:
 540         \begin{itemize}
 541                 \item \verb!mode == "player"! oppure \verb!mode == "spectator"!;
 542                 \item \texttt{name} è una \texttt{QString} non nulla e non vuota;
 543                 \item \verb!this->state() == Idle!.
 544         \end{itemize}
 545         \item Comportamento:
 546         \begin{itemize}
 547                 \item invia un messaggio XML \texttt{<joinRequest>} il cui contenuto è il parametro \texttt{name} e il cui attributo \texttt{gameMode} è impostato al parametro \texttt{mode};
 548                 \item invoca \verb!this->changeState(StreamSocket::AwaitingJoinAnswer)!.
 549         \end{itemize}
 550         \item Side effects: l'oggetto effettua una transizione verso lo stato ``Awaiting Join Answer''.
 551 \end{itemize}
 552 \smallskip
 553
 554 \subsubsection{cancelJoin}
 555 \texttt{public void cancelJoin() [slot]}
 556 \begin{itemize}
 557         \item Comportamento: se l'oggetto si trova nello stato ``Awaiting Join Answer'' o ``Awaiting Game Start'':
 558         \begin{itemize}
 559                 \item invia un messaggio XML \texttt{<playerLeft>} impostandone il contenuto a $-1$;
 560                 \item invoca \verb!this->changeState(StreamSocket::Idle)!;
 561         \end{itemize}
 562         altrimenti non fa nulla.
 563         \item Side effects: se l'oggetto si trova nello stato ``Awaiting Join Answer'' o ``Awaiting Game Start'', allora viene effettuata una transizione verso lo stato ``Idle''.
 564 \end{itemize}
 565 \smallskip
 566
 567 \subsubsection{parseData}
 568 \texttt{protected void parseData() [slot, virtual]}
 569 \begin{itemize}
 570         \item Comportamento: effettua il parsing dei messaggi provenienti dall'host remoto e si comporta come descritto in Figura~\ref{fig:clientPSM}.
 571         \item Note: per i messaggi \texttt{<move>} e \texttt{<chatMessage>} viene invocato il metodo della superclasse.
 572 \end{itemize}
 573 \smallskip
 574
 575 \subsubsection{joinAccepted}
 576 \texttt{protected void joinAccepted(int id) [signal]}
 577 \begin{itemize}
 578         \item Note: emesso quando si riceve il messaggio \texttt{<joinACK>} dal server. Segnala che la richiesta è stata accettata e che l'utente può partecipare alla partita.
 579 \end{itemize}
 580 \smallskip
 581
 582 \subsubsection{joinRefused}
 583 \texttt{protected void joinRefused(int cause) [signal]}
 584 \begin{itemize}
 585         \item Note: emesso quando si riceve il messaggio \texttt{<joinNAK>} dal server. Segnala che la richiesta non è stata accettata e quindi l'utente non può partecipare alla partita. Il parametro \texttt{cause} indica il motivo del rifiuto.
 586 \end{itemize}
 587 \smallskip
 588
 589 \subsubsection{receivedGameSettings}
 590 \texttt{protected void receivedGameSettings(int d1, int d2, int num, int timer, bool playing) [signal]}
 591 \begin{itemize}
 592         \item Note: emesso quando si riceve il messaggio \texttt{<settings>} dal server. I primi quattro parametri rappresentano le impostazioni della partita, mentre \texttt{playing} indica se la partita è già iniziata o meno.
 593 \end{itemize}
 594 \smallskip
 595
 596 \subsubsection{receivedHistory}
 597 \texttt{protected void receivedHistory(QList<Move> history) [signal]}
 598 \begin{itemize}
 599         \item Note: emesso quando si riceve il messaggio \texttt{<history>} dal server. Il parametro \texttt{history} contiene la sequenza di mosse giocate fino a quel momento nella partita in corso sul server.
 600 \end{itemize}
 601
 602 \medskip
 603
 604 \subsection{Classe ServerSocket} %%%%%%
 605
 606 \subsubsection*{\large{Descrizione generale}}
 607 Estende \texttt{StreamSocket}.
 608
 609 \medskip
 610
 611 \subsubsection*{\large{Operazioni}}
 612 \smallskip
 613
 614 \subsubsection{ServerSocket}
 615 \texttt{public ServerSocket(QTcpSocket *socket) [constructor]}
 616 \begin{itemize}
 617         \item Parametri e precondizioni: \texttt{socket} è un puntatore non nullo ad un \texttt{QTcpSocket}.
 618         \item Comportamento: invoca il costruttore della classe base passando \texttt{socket} come parametro e poi invoca \verb!changeState(StreamSocket::Connected)!.
 619 \end{itemize}
 620 \smallskip
 621
 622 \subsubsection{acceptJoin}
 623 \texttt{public void acceptJoin(int id)}
 624 \begin{itemize}
 625         \item Comportamento:
 626         \begin{itemize}
 627                 \item invia un messaggio XML \texttt{<joinACK>} avente contenuto uguale al parametro \texttt{id};
 628                 \item invoca \verb!this->changeState(StreamSocket::AwaitingPlayers)!.
 629         \end{itemize}
 630         \item Side effects: l'oggetto effettua una transizione verso lo stato ``Awaiting Players''.
 631 \end{itemize}
 632 \smallskip
 633
 634 \subsubsection{refuseJoin}
 635 \texttt{public void refuseJoin(int cause)}
 636 \begin{itemize}
 637         \item Comportamento: invia un messaggio XML \texttt{<joinNAK>} avente contenuto uguale al parametro \texttt{cause}.
 638 \end{itemize}
 639 \smallskip
 640
 641 \subsubsection{sendGameSettings}
 642 \texttt{public void sendGameSettings(int d1, int d2, int num, int timer, bool playing) [slot]}
 643 \begin{itemize}
 644         \item Comportamento:
 645         \begin{itemize}
 646                 \item invia un messaggio XML \texttt{<settings>}, impostandone gli elementi interni come indicato dai parametri;
 647                 \item invoca \verb!this->changeState(StreamSocket::AwaitingJoinRequest)!.
 648         \end{itemize}
 649         \item Side effects: l'oggetto effettua una transizione verso lo stato ``Awaiting Join Request''.
 650 \end{itemize}
 651 \smallskip
 652
 653 \subsubsection{sendHistory}
 654 \texttt{public void sendHistory(QList<Move> history) [slot]}
 655 \begin{itemize}
 656         \item Comportamento: serializza la lista di mosse passata nel parametro \texttt{history} e la invia al client come messaggio XML \texttt{<history>}.
 657         \item Note: questo metodo viene utilizzato solo qualora il client abbia precedentemente richiesto di connettersi alla partita come spettatore e la partita sia già iniziata.
 658 \end{itemize}
 659 \smallskip
 660
 661 \subsubsection{sendPlayerJoined}
 662 \texttt{public void sendPlayerJoined(int id, QString name, QString type) [slot]}
 663 \begin{itemize}
 664         \item Comportamento: invia un messaggio XML \texttt{<playerJoined>} generato nel modo seguente:
 665         \begin{itemize}
 666                 \item l'attributo \texttt{id} viene posto uguale al parametro \texttt{id};
 667                 \item gli elementi \texttt{<name>} e \texttt{<type>} contengono rispettivamente il valore del parametro omonimo;
 668                 \item l'elemento \texttt{<color>} non viene generato.
 669         \end{itemize}
 670 \end{itemize}
 671 \smallskip
 672
 673 \subsubsection{sendPlayerLeft}
 674 \texttt{public void sendPlayerLeft(int id) [slot]}
 675 \begin{itemize}
 676         \item Comportamento: invia un messaggio XML \texttt{<playerLeft>} avente contenuto uguale al parametro \texttt{id}.
 677 \end{itemize}
 678 \smallskip
 679
 680 \subsubsection{sendStartGame}
 681 \texttt{public void sendStartGame() [slot]}
 682 \begin{itemize}
 683         \item Comportamento: invia un messaggio XML \texttt{<startGame>} vuoto.
 684 \end{itemize}
 685 \smallskip
 686
 687 \subsubsection{parseData}
 688 \texttt{protected void parseData() [slot, virtual]}
 689 \begin{itemize}
 690         \item Comportamento: effettua il parsing dei messaggi provenienti dall'host remoto e si comporta come descritto in Figura~\ref{fig:serverPSM}.
 691         \item Note: per i messaggi \texttt{<move>} e \texttt{<chatMessage>} viene invocato il metodo della superclasse.
 692 \end{itemize}
 693 \smallskip
 694
 695 \subsubsection{joinRequested}
 696 \texttt{protected void joinRequested(QString mode, QString name) [signal]}
 697 \begin{itemize}
 698         \item Note: emesso quando si riceve un messaggio \texttt{<joinRequest>} da un client. \texttt{mode} e \texttt{name} sono rispettivamente modalità e nome con i quali il client intende connettersi alla partita.
 699 \end{itemize}
 700
 701 \medskip
 702
 703 \subsection{Diagrammi UML} %%%%%%
 704
 705 \begin{figure}[hpbt]
 706 \centering
 707 \includegraphics[width=13cm]{GameServer_handleJoinRequest.png}
 708 \caption{Diagramma \texttt{GameServer::handleJoinRequest}}
 709 \label{fig:handleJoinRequest}
 710 \end{figure}
 711
 712 \begin{figure}[hpbt]
 713 \centering
 714 \includegraphics[width=13cm]{ClientPSM.png}
 715 \caption{Diagramma degli stati del protocollo di rete (lato client)}
 716 \label{fig:clientPSM}
 717 \end{figure}
 718
 719 \begin{figure}[hpbt]
 720 \centering
 721 \includegraphics[width=13cm]{ServerPSM.png}
 722 \caption{Diagramma degli stati del protocollo di rete (lato server)}
 723 \label{fig:serverPSM}
 724 \end{figure}