38b5e966c0262cb08fdebd441178455fe99656c8
[oweals/gnunet.git] / src / mesh / mesh.h
1 /*
2      This file is part of GNUnet.
3      (C) 2001 - 2011 Christian Grothoff (and other contributing authors)
4
5      GNUnet is free software; you can redistribute it and/or modify
6      it under the terms of the GNU General Public License as published
7      by the Free Software Foundation; either version 3, or (at your
8      option) any later version.
9
10      GNUnet is distributed in the hope that it will be useful, but
11      WITHOUT ANY WARRANTY; without even the implied warranty of
12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
13      General Public License for more details.
14
15      You should have received a copy of the GNU General Public License
16      along with GNUnet; see the file COPYING.  If not, write to the
17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
18      Boston, MA 02111-1307, USA.
19 */
20
21 /**
22  * @author Bartlomiej Polot
23  * @file mesh/mesh.h
24  */
25
26 #ifndef MESH_H_
27 #define MESH_H_
28
29 #ifdef __cplusplus
30 extern "C"
31 {
32 #if 0                           /* keep Emacsens' auto-indent happy */
33 }
34 #endif
35 #endif
36
37 #include <stdint.h>
38
39 #define MESH_DEBUG              GNUNET_YES
40
41 #include "platform.h"
42 #include "gnunet_common.h"
43 #include "gnunet_util_lib.h"
44 #include "gnunet_peer_lib.h"
45 #include "gnunet_core_service.h"
46 #include "gnunet_protocols.h"
47 #include <gnunet_mesh_service.h>
48
49 /******************************************************************************/
50 /********************        MESH LOCAL MESSAGES      *************************/
51 /******************************************************************************/
52 /*  Any API call should be documented in the folowing table under API CALL.
53  *  Also, any message type should be documented in the following table, with the
54  * associated event.
55  *
56  * API CALL (GNUNET_MESH_*)             MESSAGE USED
57  * ------------------------             ------------
58  * connect                              GNUNET_MESH_ClientConnect
59  * disconnect                           None (network level disconnect)
60  *
61  * tunnel_create                        GNUNET_MESH_TunnelMessage
62  * tunnel_destroy                       GNUNET_MESH_TunnelMessage
63  * tunnel_buffer                        GNUNET_MESH_TunnelMessage
64  *
65  * notify_transmit_ready                None (queue / GNUNET_CLIENT_ntf_tmt_rdy)
66  * notify_transmit_ready_cancel         None (clear of internal data structures)
67  *
68  * 
69  * EVENT                                MESSAGE USED
70  * -----                                ------------
71  * data                                 GNUNET_MESH_Unicast OR
72  *                                      GNUNET_MESH_Multicast OR
73  *                                      GNUNET_MESH_ToOrigin
74  * data ack                             GNUNET_MESH_LocalAck
75  * 
76  * new incoming tunnel                  GNUNET_MESH_PeerControl
77  * peer connects to a tunnel            FIXME
78  * peer disconnects from a tunnel       FIXME
79  */
80
81 /******************************************************************************/
82 /**************************       CONSTANTS      ******************************/
83 /******************************************************************************/
84
85 #define GNUNET_MESH_LOCAL_TUNNEL_ID_CLI         0x80000000
86 #define GNUNET_MESH_LOCAL_TUNNEL_ID_SERV        0xB0000000
87
88 #define HIGH_PID                                0xFFFF0000
89 #define LOW_PID                                 0x0000FFFF
90
91 #define PID_OVERFLOW(pid, max) (pid > HIGH_PID && max < LOW_PID)
92
93 /******************************************************************************/
94 /**************************        MESSAGES      ******************************/
95 /******************************************************************************/
96
97 GNUNET_NETWORK_STRUCT_BEGIN
98
99 /**
100  * Message for a client to register to the service
101  */
102 struct GNUNET_MESH_ClientConnect
103 {
104     /**
105      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_CONNECT
106      *
107      * Size: sizeof(struct GNUNET_MESH_ClientConnect) +
108      *       sizeof(MESH_ApplicationType) * applications +
109      *       sizeof(uint16_t) * types
110      */
111   struct GNUNET_MessageHeader header;
112   /* uint32_t                 list_ports[]           */
113 };
114
115
116 /**
117  * Type for tunnel numbering.
118  * - Local tunnel numbers given by the service (incoming) are >= 0xB0000000
119  * - Local tunnel numbers given by the client (created) are >= 0x80000000
120  * - Global tunnel numbers are < 0x80000000
121  */
122 typedef uint32_t MESH_TunnelNumber;
123
124
125 /**
126  * Message for a client to create and destroy tunnels.
127  */
128 struct GNUNET_MESH_TunnelMessage
129 {
130     /**
131      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_TUNNEL_[CREATE|DESTROY]
132      *
133      * Size: sizeof(struct GNUNET_MESH_TunnelMessage)
134      */
135   struct GNUNET_MessageHeader header;
136
137     /**
138      * ID of a tunnel controlled by this client.
139      */
140   MESH_TunnelNumber tunnel_id GNUNET_PACKED;
141
142     /**
143      * Tunnel's peer
144      */
145   struct GNUNET_PeerIdentity peer;
146
147     /**
148      * Port of the tunnel.
149      */
150   uint32_t port GNUNET_PACKED;
151
152     /**
153      * Options.
154      */
155   uint32_t opt GNUNET_PACKED;
156 };
157
158
159 /**
160  * Message for mesh data traffic.
161  */
162 struct GNUNET_MESH_LocalData
163 {
164     /**
165      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_DATA
166      */
167   struct GNUNET_MessageHeader header;
168
169     /**
170      * TID of the tunnel
171      */
172   uint32_t tid GNUNET_PACKED;
173
174     /**
175      * Payload follows
176      */
177 };
178
179
180 /**
181  * Message to allow the client send more data to the service
182  * (always service -> client).
183  */
184 struct GNUNET_MESH_LocalAck
185 {
186     /**
187      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_ACK
188      */
189   struct GNUNET_MessageHeader header;
190
191     /**
192      * ID of the tunnel allowed to send more data.
193      */
194   MESH_TunnelNumber tunnel_id GNUNET_PACKED;
195
196 };
197
198
199 /**
200  * Message to inform the client about tunnels in the service.
201  */
202 struct GNUNET_MESH_LocalMonitor
203 {
204   /**
205      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_MONITOR[_TUNNEL]
206    */
207   struct GNUNET_MessageHeader header;
208
209   /**
210    * ID of the tunnel allowed to send more data.
211    */
212   MESH_TunnelNumber tunnel_id GNUNET_PACKED;
213
214   /**
215    * Alignment.
216    */
217   uint32_t reserved GNUNET_PACKED;
218
219   /**
220    * ID of the owner of the tunnel (can be local peer).
221    */
222   struct GNUNET_PeerIdentity owner;
223
224   /**
225    * ID of the destination of the tunnel (can be local peer).
226    */
227   struct GNUNET_PeerIdentity destination;
228 };
229
230
231 GNUNET_NETWORK_STRUCT_END
232
233 /******************************************************************************/
234 /************************        ENUMERATIONS      ****************************/
235 /******************************************************************************/
236
237 /**
238  * All the states a tunnel can be in.
239  */
240 enum MeshTunnelState
241 {
242     /**
243      * Uninitialized status, should never appear in operation.
244      */
245   MESH_TUNNEL_NEW,
246
247     /**
248      * Path to the peer not known yet
249      */
250   MESH_TUNNEL_SEARCHING,
251
252     /**
253      * Request sent, not yet answered.
254      */
255   MESH_TUNNEL_WAITING,
256
257     /**
258      * Peer connected and ready to accept data
259      */
260   MESH_TUNNEL_READY,
261
262     /**
263      * Peer connected previosly but not responding
264      */
265   MESH_TUNNEL_RECONNECTING
266 };
267
268
269 /**
270  * Check if one pid is bigger than other, accounting for overflow.
271  *
272  * @param bigger Argument that should be bigger.
273  * @param smaller Argument that should be smaller.
274  *
275  * @return True if bigger (arg1) has a higher value than smaller (arg 2).
276  */
277 int
278 GMC_is_pid_bigger (uint32_t bigger, uint32_t smaller);
279
280
281 /**
282  * Get the higher ACK value out of two values, taking in account overflow.
283  *
284  * @param a First ACK value.
285  * @param b Second ACK value.
286  *
287  * @return Highest ACK value from the two.
288  */
289 uint32_t
290 GMC_max_pid (uint32_t a, uint32_t b);
291
292
293 /**
294  * Get the lower ACK value out of two values, taking in account overflow.
295  *
296  * @param a First ACK value.
297  * @param b Second ACK value.
298  *
299  * @return Lowest ACK value from the two.
300  */
301 uint32_t
302 GMC_min_pid (uint32_t a, uint32_t b);
303
304
305 /**
306  * Convert a message type into a string to help debug
307  * Generated with:
308  * FIND:        "#define ([^ ]+)[ ]*([0-9]+)"
309  * REPLACE:     "    case \2: return "\1"; break;"
310  * 
311  * @param m Message type.
312  * 
313  * @return Human readable string description.
314  */
315 const char *
316 GNUNET_MESH_DEBUG_M2S (uint16_t m);
317
318 #if 0                           /* keep Emacsens' auto-indent happy */
319 {
320 #endif
321 #ifdef __cplusplus
322 }
323 #endif
324
325 #endif