bug in RC
[anna.git] / include / anna / comm / Codec.hpp
1 // ANNA - Anna is Not Nothingness Anymore                                                         //
2 //                                                                                                //
3 // (c) Copyright 2005-2015 Eduardo Ramos Testillano & Francisco Ruiz Rayo                         //
4 //                                                                                                //
5 // See project site at http://redmine.teslayout.com/projects/anna-suite                           //
6 // See accompanying file LICENSE or copy at http://www.teslayout.com/projects/public/anna.LICENSE //
7
8
9 #ifndef anna_comm_Codec_hpp
10 #define anna_comm_Codec_hpp
11
12 #include <anna/comm/CompatCodec.hpp>
13
14 namespace anna {
15
16 class Second;
17 class Millisecond;
18 class Microsecond;
19 namespace comm {
20
21 /**
22    Codificador/Decodificador compatible para transporte de datos
23
24    Esta clase ofrece una forma muy eficaz para codificar estructuras de datos complejas y pretende
25    sustituir los tipicos aplanadores y desaplanadores ya que permite que cualquier proceso
26    defina facilmente la forma de transferir cierta informacion sobre un bloque de memoria
27    y viceversa.
28
29    Vamos a ver un ejemplo de uso. Primero vamos a definir la clase MensajeDemo:
30
31 * \code
32 *
33 * #include <anna.comm.Codec.h>
34 *
35 * class MensajeDemo : public Codec {
36 * public:
37 *    static const Codec::Type type = 10;
38 *
39 *    MensajeDemo () : Codec (type),
40 *       a_dataBlock (true)
41 *    {
42 *       attach ("Entero", a_entero);
43 *       attach ("Cadena",  a_cadena);
44 *       attach ("Bloque datos",  a_dataBlock);
45 *    }
46 *
47 *    // Accesores
48 *    const int obtenerEntero () const { return a_entero; }
49 *    const std::string& obtenerCadena () const { return a_cadena; }
50 *    const DataBlock& obtenerDataBlock () const { return a_dataBlock; }
51 *
52 *    // Modificadores
53 *    void establecerEntero (const int entero) { a_entero = entero; }
54 *    void establecerCadena (const std::string& cadena) { a_cadena = cadena; }
55 *    void establecerCadena (const char* cadena) { a_cadena = cadena; }
56 *    void establecerDataBlock (const DataBlock& dataBlock) { a_dataBlock = dataBlock; }
57 *
58 * private:
59 *    int a_entero;
60 *    std::string a_cadena;
61 *    DataBlock a_dataBlock;
62 * };
63 *
64 * \endcode
65 *
66    La clase que use esta clase para enviar un mensaje debe establecer los valores de cada uno de
67    los datos mediante los modificadores definidos y luego invocar al metodo #code que
68    transferiria el contenido de las variables asociadas a este mensaje a un bloque de memoria,
69    que normalmente seriausado como mensaje.
70
71    Por otra parte la clase que recibe el mensaje invocar�al metodo #decode que transfiere
72    el contenido del bloque de memoria a cada una de las variables asociadas al mensaje.
73    Posteriormente, podremos acceder al contenido de cada una de las variables asociadas al
74    mensaje atraves de los accesores definidos para el caso.
75
76    Estos codificadores nos dan la posibilidad de definir variables opcionales, de forma que
77    una determinada variable puede no ser transferida al bloque de memoria, y por tanto puede
78    no ser recibida en el otro extremo. Ver el metodo #isNull y #setNull para mas informacion.
79
80    \warning Esta clase no establece proteccion ante accesos concurrentes
81 */
82 class Codec : public CompatCodec {
83 public:
84   /**
85      Constructor.
86
87      @param type Tipo por el que sera conocido este tipo de mensaje.
88      @param scramble Indica si el mensaje debe ser codificado de forma que no se pueda ver el contenido
89      del mismo con una simple herramienta de monitorizacion de mensajes de red. Por defecto esta
90      activo ya que la codificacion realizada es muy simple y rapida y el tiempo empleado es casi
91      inapreciable.
92   */
93   explicit Codec(const Type type, const bool scramble = true) : CompatCodec(type, scramble) {;}
94
95   /**
96      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
97      estapensada principalmente para comunicar entre si procesos remotos
98      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
99      de ellos le da a un determinado `id'.
100
101      \param name Nombre logico de la variable
102      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
103      al mensaje y viceversa.
104      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
105   */
106   const Variable* attach(const char* name, std::string& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
107
108   /**
109      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
110      estapensada principalmente para comunicar entre si procesos remotos
111      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
112      de ellos le da a un determinado `id'.
113
114      \param name Nombre logico de la variable
115      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
116      al mensaje y viceversa.
117      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
118   */
119   const Variable* attach(const char* name, const char*& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
120
121   /**
122      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
123      estapensada principalmente para comunicar entre si procesos remotos.
124      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
125      de ellos le da a un determinado `id'.
126
127      \param name Nombre logico de la variable
128      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
129      al mensaje y viceversa.
130      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
131   */
132   const Variable* attach(const char* name, int& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
133
134   /**
135      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
136      estapensada principalmente para comunicar entre si procesos remotos.
137      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
138      de ellos le da a un determinado `id'.
139
140      \param name Nombre logico de la variable
141      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
142      al mensaje y viceversa.
143      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
144   */
145   const Variable* attach(const char* name, S64& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
146
147   /**
148      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
149      estapensada principalmente para comunicar entre si procesos remotos.
150      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
151      de ellos le da a un determinado `id'.
152
153      \param name Nombre logico de la variable
154      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
155      al mensaje y viceversa.
156      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
157   */
158   const Variable* attach(const char* name, bool& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
159
160   /**
161      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
162      estapensada principalmente para comunicar entre si procesos remotos.
163      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
164      de ellos le da a un determinado `id'.
165
166      \param name Nombre logico de la variable
167      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
168      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
169      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
170   */
171   const Variable* attach(const char* name, DataBlock& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
172
173   /**
174      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
175      estapensada principalmente para comunicar entre si procesos remotos.
176      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
177      de ellos le da a un determinado `id'.
178
179      \param name Nombre logico de la variable
180      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
181      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
182      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
183   */
184   const Variable* attach(const char* name, float& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
185
186   /**
187      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
188      estapensada principalmente para comunicar entre si procesos remotos.
189      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
190      de ellos le da a un determinado `id'.
191
192      \param name Nombre logico de la variable
193      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
194      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
195      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
196   */
197   const Variable* attach(const char* name, double& value) throw(RuntimeException) { return CompatCodec::attach(name, size(), value); }
198
199   /**
200      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
201      estapensada principalmente para comunicar entre si procesos remotos.
202      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
203      de ellos le da a un determinado `id'.
204
205      \param name Nombre logico de la variable
206      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
207      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
208      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
209   */
210   const Variable* attach(const char* name, Second& value) throw(RuntimeException);
211
212   /**
213      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
214      estapensada principalmente para comunicar entre si procesos remotos.
215      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
216      de ellos le da a un determinado `id'.
217
218      \param name Nombre logico de la variable
219      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
220      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
221      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
222   */
223   const Variable* attach(const char* name, Millisecond& value) throw(RuntimeException);
224
225   /**
226      Asocia el valor recibido como parametro al dato interno identificado por `id'. Esta clase
227      estapensada principalmente para comunicar entre si procesos remotos
228      La unica restriccion que se les imponen a ambos que es compartan el significado que cada uno
229      de ellos le da a un determinado `id'.
230
231      \param name Nombre logico de la variable
232      @param value Rerencia a una variable de nuestro entorno usada para transferir los datos de la memoria
233      al mensaje y viceversa. Debe tener activado el sistema de copia profunda.
234      @return Un puntero que hace referencia al nuevo dato interno que ha sido creado.
235   */
236   const Variable* attach(const char* name, Microsecond& value) throw(RuntimeException);
237 };
238
239 }
240 }
241
242 #endif