Server/include/plaqui/server/documentacion.h

   1 /** \page page_server PlaQui Server
   2
   3 \section page_server_general Descripción General
   4         El servidor está dividido en 2 módulos que provean 2 servicios diferentes.
   5
   6         \subsection page_server_general_control Módulo de Control.
   7                 El módulo de control se basa en el protocolo TCP y se encarga de listar
   8                 los archivos de planta disponibles en el servidor, permitiendo cambiar
   9                 las propiedades de cada uno y conocer su estado en términos generales
  10                 (si se está simulando o no). Todo lo que sean comandos (abrir una
  11                 exclusa, parar una bomba, etc) se realizan a través de este módulo.
  12                 El protocolo utilizado es una implementación limitada e incompleta de
  13                 HTTP 1.1. Solo se implementan los métodos POST y GET, tomando sólo en
  14                 cuenta la ruta del archivo a obtener (se ignora el <em>query string</em> de
  15                 GET y los datos recibidos por POST). Cada comando se representa a través de
  16                 una ruta a un archivo. Si el comando recibe parámetros, estos parámetros
  17                 son también representados como componentes de dicha ruta.
  18                 A cada comando se responde con una respuesta HTTP 1.1 (también a través de
  19                 una implementación incompleta y limitada). El cuerpo de la respuesta es un
  20                 archivo XML de texto plano en formato XML que contendrá la información
  21                 requerida por el comando (ya sea una lista de archivos o una respuesta
  22                 informando el éxito o error al cambiar las propiedades de una planta).
  23                 Este módulo está implementado por las clases PlaQui::Server::ControlServer
  24                 y PlaQui::Server::ControlClient.
  25
  26         \subsection page_server_general_transmision Módulo de Transmisión.
  27                 Este módulo se encarga de transmitir la simulación en tiempo real por UDP
  28                 (como si fuera un video). Comienza luego de que el módulo de control recibe
  29                 una petición de transmisión y continúa transmitiendo (en un principio)
  30                 hasta que recibe una petición de desconexión.
  31                 Lo que se envía es un archivo XML con el estado de la planta.
  32                 El cliente debe validar lo recibido y mostrar todos los <em>frames</em>
  33                 válidos. Mientras que no se reciban <em>frames</em> válidos se debe mostrar
  34                 el último válido. Si no se recibiece durante una cantidad de tiempo
  35                 determinada ningún <em>frame</em> válido, se asume un error en la red.
  36                 Si por casualidad los datos recibidos son incorrectos pero válidos (por
  37                 ejemplo, se recibe el comienzo de un <em>frame</em> y el final del siguente),
  38                 el cliente lo mostrará igual porque no tiene forma de darse cuenta. Esto no
  39                 es problema si consideramos que en pocos milisegundos se recibirá un nuevo
  40                 <em>frame</em> válido y correcto (similar a lo que pasa en transmisiones de
  41                 audio o video en tiempo real).
  42                 Este módulo está implementado por las clases PlaQui::Server::Transmitter y
  43                 PlaQui::Server::Receiver.
  44
  45
  46 \section page_server_protocolo Comandos del Módulo de Control.
  47         Todos los comandos son rutas de archivos. En un principio no se van a utilizar
  48         los <em>query string</em> de los datos pasados por GET ni datos adicionales
  49         recibidos por POST. Es decir, de un <em>request</em> HTTP solo se usara la ruta
  50         para codificar los comandos. Por ejemplo, de:
  51         \verbatim GET /ruta/que/representa/comando?query=string HTTP/1.1 \endverbatim
  52         Sólo se utilizará \verbatim /ruta/que/representa/comando \endverbatim para
  53         codificar el comando. El <em>query string</em> y los datos que se reciban por
  54         POST serán ignorados silenciosamente (sin producir un error).
  55
  56         Todos los comandos son respondidos con una respuesta XML que <b>siempre</b>
  57         incluye un código de éxito/error. Adicionalmente puede devolver más datos en
  58         la respuesta en cuyo caso se especifica expresamente.
  59
  60         Los comandos se tiene una estructura general compuesta por 3 elementos:
  61         - Destino: A quién se le envía el comando.
  62         - Comando: El comando en sí (la acción a realizar).
  63         - Argumentos: Opciones y datos necesarios para ejecutar el comando.
  64         Esto se estructura como una ruta, por lo que todos los comandos se componen la
  65         menos de 2 <em>directorios</em>, con cero o más argumentos representados a su
  66         ves por archivos o más subdirectorios:
  67         /verbatim /[destino]/[comando]/[argumento 1]/[...]/[argumento N] /endverbatim
  68
  69         Los destinos disponibles son:
  70         - <tt>server</tt>: Comandos para el servidor en sí.
  71         - <tt>connection</tt>: Comandos para las conexiones.
  72         - <tt>transmission</tt>: Comandos para las transmisiones.
  73         - <tt>plant</tt>: Comandos para las plantas.
  74
  75         \subsection page_server_protocolo_general Comandos para el Servidor.
  76                 Los comandos para el servidor, como se vio previamente, comienzan con
  77                 <tt>/server/</tt> seguido de alguna de las siguientes opciones:
  78                 <table>
  79                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
  80                         <tr>
  81                                 <td><tt>info</tt></td>
  82                                 <td>Obtiene información sobre el servidor.</td>
  83                                 <td>Cantidad de plantas, conexiones, transmisiones, versión,
  84                                     uptime, etc.</td>
  85                         </tr>
  86                         <tr>
  87                                 <td><tt>stop</tt></td>
  88                                 <td>Detiene el servidor.</td>
  89                                 <td>Nada.</td>
  90                         </tr>
  91                 </table>
  92
  93         \subsection page_server_protocolo_control Comandos para una Conexión de Control.
  94                 Todos los comandos de transmisiones comienzan con <tt>/connection/</tt>
  95                 y continúan con alguna de las siguientes opciones:
  96                 <table>
  97                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
  98                         <tr>
  99                                 <td><tt>list</tt></td>
 100                                 <td>Obtiene una lista de las conexiones de control activas.</td>
 101                                 <td>Lista de conexiones activas (host, puerto, uptime, etc).</td>
 102                         </tr>
 103                         <tr>
 104                                 <td><tt>stop/[host]/[port]</tt></td>
 105                                 <td>Finaliza la conexión de control del host [host] en el puerto
 106                                     [port].</td>
 107                                 <td>Nada.</td>
 108                         </tr>
 109                 </table>
 110                 \note Los nombres entre <tt>[</tt> y <tt>]</tt> denotan un argumento.
 111
 112         \subsection page_server_protocolo_transmision Comandos para una Transmisión.
 113                 Todos los comandos de transmisiones comienzan con <tt>/transmission/</tt>
 114                 y continúan con alguna de las siguientes opciones:
 115                 <table>
 116                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
 117                         <tr>
 118                                 <td><tt>list</tt></td>
 119                                 <td>Obtiene una lista de las transmisiones activas.</td>
 120                                 <td>Lista de transmisiones activas (host, puerto, uptime,
 121                                     etc).</td>
 122                         </tr>
 123                         <tr>
 124                                 <td><tt>start/[pl]/[host]/[port]</tt></td>
 125                                 <td>Comienza la transmisión de la planta [pl] al [host]
 126                                     en el puerto [port].</td>
 127                                 <td>Nada.</td>
 128                         </tr>
 129                         <tr>
 130                                 <td><tt>stop/[host]/[port]</tt></td>
 131                                 <td>Finaliza la transmisión al [host] en el puerto
 132                                     [port].</td>
 133                                 <td>Nada.</td>
 134                         </tr>
 135                 </table>
 136                 \note Los nombres entre <tt>[</tt> y <tt>]</tt> denotan un argumento.
 137
 138         \subsection page_server_protocolo_planta Comandos para una Planta.
 139                 Todos los comandos de plantas comienzan con <tt>/plant/</tt> y continúan con
 140                 alguna de las siguientes opciones:
 141                 <table>
 142                         <tr><th>Comando</th><th>Descripción</th><th>Respuesta</th></tr>
 143                         <tr>
 144                                 <td><tt>list</tt></td>
 145                                 <td>Obtiene lista de plantas.</td>
 146                                 <td>Lista de plantas con info mínima de cada una (está
 147                                     corriendo o no, uptime, cantidad de elementos,etc).</td>
 148                         </tr>
 149                         <tr>
 150                                 <td><tt>get/[pl]</tt></td>
 151                                 <td>Obtiene la planta de nombre [pl].</td>
 152                                 <td>El mismo archivo que se crea en el Constructor.</td>
 153                         </tr>
 154                         <tr>
 155                                 <td><tt>set/[pl]/[el]/[pr]/[val]</tt></td>
 156                                 <td>Cambia la propiedad [pr] del elemento [el], asignándole
 157                                     el valor [val] a planta de nombre [pl].</td>
 158                                 <td>Nada.</td>
 159                         </tr>
 160                         <tr>
 161                                 <td><tt>set_frequency/[pl]/[hz]</tt></td>
 162                                 <td>Cambia la frecuencia de refresco de la simulación de la
 163                                     planta de nombre [pl] a [hz] veces por segundo. Si [hz]
 164                                     es cero ("0"), se usa la frecuencia de refresco por
 165                                     omisión del servidor.</td>
 166                                 <td>Nada.</td>
 167                         </tr>
 168                         <tr>
 169                                 <td><tt>start/[pl]</tt></td>
 170                                 <td>Reanuda (o comienza) la simulación de la planta de nombre
 171                                     [pl].</td>
 172                                 <td>Nada.</td>
 173                         </tr>
 174                         <tr>
 175                                 <td><tt>stop/[pl]</tt></td>
 176                                 <td>Pausa la simulación de la planta de nombre
 177                                     [pl].</td>
 178                                 <td>Nada.</td>
 179                         </tr>
 180                         <tr>
 181                                 <td><tt>remove/[pl]</tt></td>
 182                                 <td>Finaliza la simulación de la planta de nombre
 183                                     [pl] eliminandola del servidor.</td>
 184                                 <td>Nada.</td>
 185                         </tr>
 186                 </table>
 187                 \note Los nombres entre <tt>[</tt> y <tt>]</tt> denotan un argumento.
 188
 189 \section page_server_uso Modo de uso.
 190         Para utilizar el servidor es necesario disponer de un archivo XML de planta
 191         (por ejemplo, generado por el Constructor).
 192
 193         Invocación del servidor:
 194         \verbatim ./plaqui-server [archivo] [puerto] \endverbatim
 195
 196         Ambos argumentos son opcionales. El primero, <tt>[archivo]</tt>, es la
 197         ubicación del archivo con la descripción de la planta a simular (por omisión
 198         <tt>planta.xml</tt>). El segundo, <tt>[puerto]</tt>, es el puerto en el cual
 199         se van a atender las peticiones al servidor (por omisión 7522).
 200
 201 */