Se borran los test porque estan desactualizados y ni siquiera compilan.

[z.facultad/75.42/plaqui.git] / Server / include / plaqui / server / documentacion.h

diff --git a/Server/include/plaqui/server/documentacion.h b/Server/include/plaqui/server/documentacion.h
index 06a78ba289568fcab92bea901ae2e9b0b672e365..2b268ec845ae35438303205739fef5e0ea8e0c74 100644 (file)
--- a/Server/include/plaqui/server/documentacion.h
+++ b/Server/include/plaqui/server/documentacion.h
@@ -1,9 +1,9 @@
 /** \page page_server PlaQui Server
 
 /** \page page_server PlaQui Server
 

-\section page_server_general Descripción General
+\section page_server_general Descripción General.

        El servidor está dividido en 2 módulos que provean 2 servicios diferentes.
 
        El servidor está dividido en 2 módulos que provean 2 servicios diferentes.
 

-       \subsection page_server_general_control Módulo de Control
+       \subsection page_server_general_control Módulo de Control.

                El módulo de control se basa en el protocolo TCP y se encarga de listar
                los archivos de planta disponibles en el servidor, permitiendo cambiar
                las propiedades de cada uno y conocer su estado en términos generales
                El módulo de control se basa en el protocolo TCP y se encarga de listar
                los archivos de planta disponibles en el servidor, permitiendo cambiar
                las propiedades de cada uno y conocer su estado en términos generales


@@ -23,7 +23,22 @@
                Este módulo está implementado por las clases PlaQui::Server::ControlServer
                y PlaQui::Server::ControlClient.
 
                Este módulo está implementado por las clases PlaQui::Server::ControlServer
                y PlaQui::Server::ControlClient.
 

-       \subsection page_server_general_transmision Módulo de Transmisión
+               \subsubsection page_server_general_control_http Ventajas del protocolo HTTP.
+                       Las ventajas de montar el protocolo del servidor sobre el protocolo
+                       HTTP son muchas. Las más destacables son las más obvias.
+
+                       Al usar el protocolo HTTP se puede controlar el servidor con
+                       cualquier navegador web. Al ser las respuestas archivos XML es
+                       fácil agregar hojas de estilo XSLT para convertirlas en HTML y
+                       transformar un navegador web con capacidad de procesar hojas XSLT
+                       (como Mozilla) en un cliente casi con las mismas capacidades y
+                       facilidad de uso que uno hecho especialmente para PlaQui.
+
+                       Otra ventaja importante es que muchos lugares sin acceso real a
+                       Internet tienen acceso a un proxy HTTP, por lo que la accesibilidad
+                       del servicio se vuelve muy fácil incluso en redes muy protegidas.
+
+       \subsection page_server_general_transmision Módulo de Transmisión.

                Este módulo se encarga de transmitir la simulación en tiempo real por UDP
                (como si fuera un video). Comienza luego de que el módulo de control recibe
                una petición de transmisión y continúa transmitiendo (en un principio)
                Este módulo se encarga de transmitir la simulación en tiempo real por UDP
                (como si fuera un video). Comienza luego de que el módulo de control recibe
                una petición de transmisión y continúa transmitiendo (en un principio)


@@ -43,7 +58,7 @@
                PlaQui::Server::Receiver.
 
 
                PlaQui::Server::Receiver.
 
 

-\section page_server_protocolo Comandos del Módulo de Control
+\section page_server_protocolo Comandos del Módulo de Control.

        Todos los comandos son rutas de archivos. En un principio no se van a utilizar
        los <em>query string</em> de los datos pasados por GET ni datos adicionales
        recibidos por POST. Es decir, de un <em>request</em> HTTP solo se usara la ruta
        Todos los comandos son rutas de archivos. En un principio no se van a utilizar
        los <em>query string</em> de los datos pasados por GET ni datos adicionales
        recibidos por POST. Es decir, de un <em>request</em> HTTP solo se usara la ruta


@@ -72,7 +87,7 @@
        - <tt>transmission</tt>: Comandos para las transmisiones.
        - <tt>plant</tt>: Comandos para las plantas.
                          
        - <tt>transmission</tt>: Comandos para las transmisiones.
        - <tt>plant</tt>: Comandos para las plantas.
                          

-       \subsection page_server_protocolo_general Comandos para el Servidor
+       \subsection page_server_protocolo_general Comandos para el Servidor.

                Los comandos para el servidor, como se vio previamente, comienzan con
                <tt>/server/</tt> seguido de alguna de las siguientes opciones:
                <table>
                Los comandos para el servidor, como se vio previamente, comienzan con
                <tt>/server/</tt> seguido de alguna de las siguientes opciones:
                <table>


@@ -90,7 +105,7 @@
                        </tr>
                </table>
 
                        </tr>
                </table>
 

-       \subsection page_server_protocolo_control Comandos para una Conexión de Control
+       \subsection page_server_protocolo_control Comandos para una Conexión de Control.

                Todos los comandos de transmisiones comienzan con <tt>/connection/</tt>
                y continúan con alguna de las siguientes opciones:
                <table>
                Todos los comandos de transmisiones comienzan con <tt>/connection/</tt>
                y continúan con alguna de las siguientes opciones:
                <table>


@@ -109,7 +124,7 @@
                </table>
                \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 
                </table>
                \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 

-       \subsection page_server_protocolo_transmision Comandos para una Transmisión
+       \subsection page_server_protocolo_transmision Comandos para una Transmisión.

                Todos los comandos de transmisiones comienzan con <tt>/transmission/</tt>
                y continúan con alguna de las siguientes opciones:
                <table>
                Todos los comandos de transmisiones comienzan con <tt>/transmission/</tt>
                y continúan con alguna de las siguientes opciones:
                <table>


@@ -135,7 +150,7 @@
                </table>
                \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 
                </table>
                \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 

-       \subsection page_server_protocolo_planta Comandos para una Planta
+       \subsection page_server_protocolo_planta Comandos para una Planta.

                Todos los comandos de plantas comienzan con <tt>/plant/</tt> y continúan con
                alguna de las siguientes opciones:
                <table>
                Todos los comandos de plantas comienzan con <tt>/plant/</tt> y continúan con
                alguna de las siguientes opciones:
                <table>


@@ -186,7 +201,21 @@
                </table>
                \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 
                </table>
                \note Los nombres entre <tt>[</tt> y <tt>]</tt> representan un argumento.
 

-\section page_server_uso Modo de uso
+\section page_server_respuesta Respuestas del Módulo de Control.
+       Las respuestas del servidor, como se dijo anteriormente, son respuestas HTTP, cuyo
+       cuerpo es un archivo XML. Este archivo se compone de un <em>tag</em> XML
+       <tt>plaqui-response</tt> y tiene como atributos obligatorios <tt>code</tt> (indica
+       el código de respuesta, para saber si se realizó bien el comando) y <tt>version</tt>
+       (indica la versión del formato del archivo XML, para preveer la posibilidad de que
+        cambie en futuras versiones). También tiene un atributo opcional <tt>description</tt>
+       que permite agregar una descripción sobre la respuesta, útil para observar respuestas
+       con un navegador u otro cliente no específico. El <em>tag</em>plaqui-response</em>
+       puede tener un contenido, en caso de que la respuesta necesite enviar información al
+       cliente (como al obtener una planta o una lista). El contenido es a su vez XML y en
+       el caso de la obtención de una planta tiene el mismo formato que el utilizado por el
+       Constructor.
+
+\section page_server_uso Modo de uso.

        \subsection page_server_uso_inicio Inicio del servidor
                Para iniciar el servidor es necesario disponer de un archivo XML de
                planta (por ejemplo, generado por el Constructor).
        \subsection page_server_uso_inicio Inicio del servidor
                Para iniciar el servidor es necesario disponer de un archivo XML de
                planta (por ejemplo, generado por el Constructor).


@@ -199,7 +228,7 @@
                <tt>planta.xml</tt>). El segundo, <tt>[puerto]</tt>, es el puerto en el cual
                se van a atender las peticiones al servidor (por omisión 7522).
 
                <tt>planta.xml</tt>). El segundo, <tt>[puerto]</tt>, es el puerto en el cual
                se van a atender las peticiones al servidor (por omisión 7522).
 

-       \subsection page_server_uso_estado Estado del servidor
+       \subsection page_server_uso_estado Estado del servidor.

                Mientras el servidor se ejecuta, va imprimiendo en la salida estándar su
                estado. Se imprime cada vez que llega una conexión entrante y cada vez que
                se detecta un error.
                Mientras el servidor se ejecuta, va imprimiendo en la salida estándar su
                estado. Se imprime cada vez que llega una conexión entrante y cada vez que
                se detecta un error.


@@ -211,7 +240,7 @@
                \note Los errores se imprimen en la salida de error, no en la salida
                      estándar.
 
                \note Los errores se imprimen en la salida de error, no en la salida
                      estándar.
 

-       \subsection page_server_uso_fin Finalización del servidor
+       \subsection page_server_uso_fin Finalización del servidor.

                Hay varias formas de finalizar el servidor:
                - Enviando una señal de interrupción (<tt>SIGINT</tt>), por ejemplo,
                  presionando la combinación de teclas <tt>CTRL-C</tt>.
                Hay varias formas de finalizar el servidor:
                - Enviando una señal de interrupción (<tt>SIGINT</tt>), por ejemplo,
                  presionando la combinación de teclas <tt>CTRL-C</tt>.