]> git.llucax.com Git - z.facultad/75.42/plaqui.git/blobdiff - docs/server.txt
Se agrega sobrecarga de add_arg(unsigned) a pedido de ricky :)
[z.facultad/75.42/plaqui.git] / docs / server.txt
index c553d5458b97f968af14172b6897fc873457705c..eaee99a14f135739e8fbbf9f863db92f8942e5a7 100644 (file)
@@ -1,6 +1,6 @@
 
                          +----------------------------+
-                         | PROPUESTA DE SERVIDOR v0.2 |
+                         | PROPUESTA DE SERVIDOR v0.4 |
                          +----------------------------+
 
                  $Id$
@@ -51,8 +51,8 @@ problema si consideramos que en pocos milisegundos se recibir
 video en tiempo real).
 
 
-Lista de comandos disponibles para el módulo de control:
-========================================================
+Descripción de los comandos para el módulo de control:
+======================================================
 
 Todos los comandos son rutas de archivos. En un principio no se van a utilizar
 los 'query string' de los datos pasados por GET ni datos adicionales pasados
@@ -60,70 +60,145 @@ por POST. Es decir, de un 'request' HTTP solo se usara la ruta para codificar
 los comandos. Ejemplo: GET /ruta/que/representa/comando?query=string HTTP/1.1
                           '----------------------------'
 Este es el comando que entendera el servidor. La presencia de un 'query string'
-sera ignorada, al igual que datos enviados por POST, silenciosamente (sin
+será ignorada, al igual que datos enviados por POST, silenciosamente (sin
 producir un error).
 
 Todos los comandos son respondidos con una respuesta XML que *siempre* incluye
 un código de éxito/error. Adicionalmente puede devolver más datos en la
 respuesta en cuyo caso se especifica expresamente.
 
-Comandos Generales:
--------------------
-Los nombres entre "<" y ">" denotan un argumento.
-
-Comando                      |Descripción           |Respuesta
-----------------------+----------------------+----------------------------------
-/                     |Obtiene estado general|Cantidad de plantas,
-                      |del servidor.         |conexiones, transmisiones,
-                      |                      |versión, uptime, etc.
-----------------------+----------------------+----------------------------------
-/plants               |Obtiene lista de      |Lista de plantas con info mínima
-                      |plantas.              |de cada una (está corriendo o no,
-                      |                      |uptime, cantidad de elementos,etc)
-----------------------+----------------------+----------------------------------
-/plants/<nombre>      |Obtiene la planta de  |El mismo archivo que se crea en el
-                      |nombre <nombre>.      |Constructor.
-----------------------+----------------------+----------------------------------
-/transmissions        |Obtiene una lista de  |Lista de transmisiones activas
-                      |las transmisiones     |(host, puerto, uptime, etc).
-                      |activas.              |
+Comandos en general:
+--------------------
+Los comandos se tiene una estructura general compuesta por 3 elementos:
+- Destino: A quien se le envía el comando.
+- Comando: El comando en sí (la acción a realizar).
+- Argumentos: Opciones y datos necesarios para ejecutar el comando.
+Esto se estructura como una ruta, por lo que todos los comandos se componen la
+menos de 2 'directorios' anidados, con cero o más argumentos representados a su
+ves por archivos o más subdirectorios:
+/<destino>/<comando>/<argumento 1>/<argumento 2>/<...>/<argumento N>
+
+Los destinos disponibles serán:
+- server: Comandos para el servidor en sí.
+- plant: Comandos para las plantas.
+- transmission: Comandos para las transmisiones (el módulo de transmisión).
+
+Comandos para el servidor:
+--------------------------
+Los comandos para el servidor, como se vio previamente, comienzan con /server/
+seguido de alguna de las siguientes opciones.
+
+Comando         | Descripción            | Respuesta                                   
+---------+------------------------+---------------------------------------------
+status   | Obtiene estado general | Cantidad de plantas, conexiones,
+         | del servidor.          | transmisiones, versión, uptime, etc.
+---------+------------------------+---------------------------------------------
+stop     | Detiene el servidor.   | Nada.
 
 Comandos para una Planta:
 -------------------------
-Todos los comandos de plantas comienzan con /plants/ y reciben un argumento que
-es el nombre de la planta, <nombre>, a la cual enviar el comando.
-Los comandos a continuación comienzan todos con '/plants/<nombre>'.
-
-Comando                      |Descripción           |Respuesta
-----------------------+----------------------+----------------------------------
-/start                |Comienza la simulación|Nada.
-                      |de la planta de nombre|
-                      |<planta>.             |
-----------------------+----------------------+----------------------------------
-/stop                 |Finaliza la simulación|Nada.
-                      |de la planta de nombre|
-                      |<planta>.             |
-----------------------+----------------------+----------------------------------
-/set/<elem>/<prop>/<v>|Cambia la propiedad   |Nada (a ver si no retorna el valor
-                      |<prop> del elemento   |realmente aceptado).
-                      |<elem>, asignándole   |
-                      |el valor <v>.         |
+Todos los comandos de plantas comienzan con /plant/ y continúan con alguna de
+las siguientes opciones:
+
+Comando               |Descripción                  |Respuesta
+---------------+-----------------------------+----------------------------------
+list           |Obtiene lista de plantas.    |Lista de plantas con info mínima
+               |                             |de cada una (está corriendo o no,
+               |                             |uptime, cantidad de elementos,etc)
+---------------+-----------------------------+----------------------------------
+get/<planta>   |Obtiene la planta de         |El mismo archivo que se crea en el
+               |nombre <planta>.             |Constructor.
+---------------+-----------------------------+----------------------------------
+start/<planta> |Comienza la simulación de la |Nada.
+               |planta de nombre <planta>.   |
+---------------+-----------------------------+----------------------------------
+stop/<planta>  |Finaliza la simulación de la |Nada.
+               |planta de nombre <planta>.   |
+---------------+-----------------------------+----------------------------------
+set/<planta>   |Cambia la propiedad <prop>   |Nada (a ver si no retorna el valor
+ /<elem>       |del elemento <elem>,         |realmente aceptado).
+ /<prop>       |asignándole el valor <val> a |
+ /<val>        |planta de nombre <planta>.   |
+
+NOTA: Los nombres entre "<" y ">" denotan un argumento.
 
 Comandos para una Transmisión:
 ------------------------------
-Todos los comandos de transmisiones comienzan con /transmissions.
-Los comandos a continuación comienzan todos con '/transmissions'.
-Los argumentos entre "[" y "]" son opcionales. De omitirse se usan valores por
-predefinidos.
-
-Comando                        |Descripción                                 |Respuesta
-------------------------+--------------------------------------------+----------
-/start/<host>/[<port>]  |Comienza la transmisión al <host> en el     |Nada.
-                        |puerto al <host> en el puerto <port>.       |
-------------------------+--------------------------------------------+----------
-/stop/[<host>]/[<port>] |Finaliza la transmisiónal <host> en el      |Nada.
-                        |puerto <port>. Si se omite el <host>, se    |
-                        |finalizan todas las transmisiones.          |
+Todos los comandos de transmisiones comienzan con /transmission/ y continúan con
+alguna de las siguientes opciones:
+
+Comando                   |Descripción                              |Respuesta
+-------------------+-----------------------------------------+------------------
+list               |Obtiene una lista de las transmisiones   |Lista de transmi-
+                   |activas.                                 |siones activas 
+                   |                                         |(host, puerto, 
+                   |                                         |uptime, etc).
+-------------------+-----------------------------------------+------------------
+start/<plant>      |Comienza la transmisión de la planta     |Nada.
+ /<host>/<port>    |<plant> al <host> en elpuerto al <host>  |
+                   |en el puerto <port>.                     |
+-------------------+-----------------------------------------+------------------
+stop/<host>/<port> |Finaliza la transmisión al <host> en el  |Nada.
+                   |puerto <port>. Si se omite el <port>, se |
+                   |finalizan todas las transmisiones al     |
+                   |<host>. Si se omite el <host>, se        |
+                   |finalizan todas las transmisiones.       |
+
+Comandos para una Conexión de Control:
+--------------------------------------
+Todos los comandos de transmisiones comienzan con /transmission/ y continúan con
+alguna de las siguientes opciones:
+
+Comando                   |Descripción                              |Respuesta
+-------------------+-----------------------------------------+------------------
+list               |Obtiene una lista de las conexiones de   |Lista de conexio-
+                   |control activas.                         |nes activas (host,
+                   |                                         |puerto, uptime,
+                   |                                         |etc).
+-------------------+-----------------------------------------+------------------
+stop/<host>/<port> |Finaliza la conexión de control del host |Nada.
+                   |<host> en el puerto <port>. Si se omite  |
+                   |el <port> se finalizan todas las         |
+                   |conexiones al <host>. Si se omite también|
+                   |el <host>, se finalizan todas las        |
+                   |conexiones de control.                   |
+
+NOTA: Los nombres entre "<" y ">" denotan un argumento.
+
+
+Descripción de los comandos para el módulo de control:
+======================================================
+
+Todas las respuestas consisten de un archivo XML con esta forma (falta hacer la
+DTD):
+<plaqui version="0.1">
+       <response code="[código]" />
+</plaqui>
+El código es obligatorio e informará si el comando se realizó con éxito y en
+caso de no hacerlo, indicará la razón (los códigos faltan definirlos, pero usar
+un esquema similar a los códigos de HTTP sería un buen comienzo).
+La respuesta también puede tener otros contenidos (listado de plantas,
+conexiónes, transmisiones, descripción de una planta completa, etc). Dichos
+contenidos irán contenidos en el tag response:
+<plaqui version="0.1">
+    <response code= "[código]">
+        <list type="plants">
+            <item id="[id1]">
+                <prop name="[nombre1]" value="[valor1]" />
+                <prop name="[nombre2]" value="[valor2]" />
+                <!-- ... más ... -->
+            </item>
+            <item id="[id2]">
+                <prop name="[nombre1]" value="[valor3]" />
+                <prop name="[nombre2]" value="[valor4]" />
+                <!-- ... más ... -->
+            </item>
+        </list>
+    </response>
+</plaqui>
+
+TODO: Ver si la lista va dentro o fuera del tag <response>, ver si el tag
+      <plaqui> está bien, es útil y correcto.
 
 
 Características adicionales (a desarrollar si el tiempo lo permite):
@@ -158,5 +233,15 @@ Es posible hacer que el comando /transmissions/start sin argumentos comience una
 transmisión por 'broadcast' de la planta para todo aquel que quiera monitorearla
 desde la red en la que se haga el 'broadcast'.
 
+Atajos de comandos:
+-------------------
+Se trata de 'alias' de comandos. Por ejemplo que '/' de un estado del server
+(/sever/status), que /plant de una lista de plantas, etc.
+
+Valores por defecto:
+--------------------
+Para los comandos que requieren argumentos se podría asumir valores por defecto
+en caso de faltar alguno.
+
 
 vim: set et ts=4 sw=4 tw=80: