- fix queueing
[oweals/gnunet.git] / src / mesh / gnunet-service-mesh_connection.h
1 /*
2      This file is part of GNUnet.
3      (C) 2013 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  * @file mesh/gnunet-service-mesh_connection.h
23  * @brief mesh service; dealing with connections
24  * @author Bartlomiej Polot
25  *
26  * All functions in this file should use the prefix GMC (Gnunet Mesh Connection)
27  */
28
29 #ifndef GNUNET_SERVICE_MESH_CONNECTION_H
30 #define GNUNET_SERVICE_MESH_CONNECTION_H
31
32 #ifdef __cplusplus
33 extern "C"
34 {
35 #if 0                           /* keep Emacsens' auto-indent happy */
36 }
37 #endif
38 #endif
39
40 #include "gnunet_util_lib.h"
41
42
43 /**
44  * All the states a connection can be in.
45  */
46 enum MeshConnectionState
47 {
48   /**
49    * Uninitialized status, should never appear in operation.
50    */
51   MESH_CONNECTION_NEW,
52
53   /**
54    * Connection create message sent, waiting for ACK.
55    */
56   MESH_CONNECTION_SENT,
57
58   /**
59    * Connection ACK sent, waiting for ACK.
60    */
61   MESH_CONNECTION_ACK,
62
63   /**
64    * Connection confirmed, ready to carry traffic.
65    */
66   MESH_CONNECTION_READY,
67 };
68
69
70 /**
71  * Struct containing all information regarding a connection to a peer.
72  */
73 struct MeshConnection;
74
75 #include "mesh_path.h"
76 #include "gnunet-service-mesh_channel.h"
77 #include "gnunet-service-mesh_peer.h"
78
79
80
81 /**
82  * Core handler for connection creation.
83  *
84  * @param cls Closure (unused).
85  * @param peer Sender (neighbor).
86  * @param message Message.
87  *
88  * @return GNUNET_OK to keep the connection open,
89  *         GNUNET_SYSERR to close it (signal serious error)
90  */
91 int
92 GMC_handle_create (void *cls, const struct GNUNET_PeerIdentity *peer,
93                    const struct GNUNET_MessageHeader *message);
94
95 /**
96  * Core handler for path confirmations.
97  *
98  * @param cls closure
99  * @param message message
100  * @param peer peer identity this notification is about
101  *
102  * @return GNUNET_OK to keep the connection open,
103  *         GNUNET_SYSERR to close it (signal serious error)
104  */
105 int
106 GMC_handle_confirm (void *cls, const struct GNUNET_PeerIdentity *peer,
107                     const struct GNUNET_MessageHeader *message);
108
109 /**
110  * Core handler for notifications of broken paths
111  *
112  * @param cls Closure (unused).
113  * @param peer Peer identity of sending neighbor.
114  * @param message Message.
115  *
116  * @return GNUNET_OK to keep the connection open,
117  *         GNUNET_SYSERR to close it (signal serious error)
118  */
119 int
120 GMC_handle_broken (void *cls, const struct GNUNET_PeerIdentity *peer,
121                    const struct GNUNET_MessageHeader *message);
122
123 /**
124  * Core handler for tunnel destruction
125  *
126  * @param cls Closure (unused).
127  * @param peer Peer identity of sending neighbor.
128  * @param message Message.
129  *
130  * @return GNUNET_OK to keep the connection open,
131  *         GNUNET_SYSERR to close it (signal serious error)
132  */
133 int
134 GMC_handle_destroy (void *cls, const struct GNUNET_PeerIdentity *peer,
135                     const struct GNUNET_MessageHeader *message);
136
137 /**
138  * Core handler for mesh network traffic going orig->dest.
139  *
140  * @param cls Closure (unused).
141  * @param message Message received.
142  * @param peer Peer who sent the message.
143  *
144  * @return GNUNET_OK to keep the connection open,
145  *         GNUNET_SYSERR to close it (signal serious error)
146  */
147 int
148 GMC_handle_fwd (void *cls, const struct GNUNET_PeerIdentity *peer,
149                 const struct GNUNET_MessageHeader *message);
150
151
152 /**
153  * Core handler for mesh network traffic going dest->orig.
154  *
155  * @param cls Closure (unused).
156  * @param message Message received.
157  * @param peer Peer who sent the message.
158  *
159  * @return GNUNET_OK to keep the connection open,
160  *         GNUNET_SYSERR to close it (signal serious error)
161  */
162 int
163 GMC_handle_bck (void *cls, const struct GNUNET_PeerIdentity *peer,
164                 const struct GNUNET_MessageHeader *message);
165
166 /**
167  * Core handler for mesh network traffic point-to-point acks.
168  *
169  * @param cls closure
170  * @param message message
171  * @param peer peer identity this notification is about
172  *
173  * @return GNUNET_OK to keep the connection open,
174  *         GNUNET_SYSERR to close it (signal serious error)
175  */
176 int
177 GMC_handle_ack (void *cls, const struct GNUNET_PeerIdentity *peer,
178                 const struct GNUNET_MessageHeader *message);
179
180 /**
181  * Core handler for mesh network traffic point-to-point ack polls.
182  *
183  * @param cls closure
184  * @param message message
185  * @param peer peer identity this notification is about
186  *
187  * @return GNUNET_OK to keep the connection open,
188  *         GNUNET_SYSERR to close it (signal serious error)
189  */
190 int
191 GMC_handle_poll (void *cls, const struct GNUNET_PeerIdentity *peer,
192                  const struct GNUNET_MessageHeader *message);
193
194 /**
195  * Core handler for mesh keepalives.
196  *
197  * @param cls closure
198  * @param message message
199  * @param peer peer identity this notification is about
200  * @return GNUNET_OK to keep the connection open,
201  *         GNUNET_SYSERR to close it (signal serious error)
202  *
203  * TODO: Check who we got this from, to validate route.
204  */
205 int
206 GMC_handle_keepalive (void *cls, const struct GNUNET_PeerIdentity *peer,
207                       const struct GNUNET_MessageHeader *message);
208
209 /**
210  * Send an ACK on the appropriate connection/channel, depending on
211  * the direction and the position of the peer.
212  *
213  * @param c Which connection to send the hop-by-hop ACK.
214  * @param ch Channel, if any.
215  * @param fwd Is this a fwd ACK? (will go dest->root)
216  */
217 void
218 GMC_send_ack (struct MeshConnection *c, struct MeshChannel *ch, int fwd);
219
220 /**
221  * Initialize the connections subsystem
222  *
223  * @param c Configuration handle.
224  */
225 void
226 GMC_init (const struct GNUNET_CONFIGURATION_Handle *c);
227
228 /**
229  * Shut down the connections subsystem.
230  */
231 void
232 GMC_shutdown (void);
233
234 /**
235  * Create a connection.
236  *
237  * @param cid Connection ID (either created locally or imposed remotely).
238  * @param t Tunnel this connection belongs to (or NULL);
239  * @param p Path this connection has to use.
240  * @param own_pos Own position in the @c p path.
241  */
242 struct MeshConnection *
243 GMC_new (const struct GNUNET_HashCode *cid,
244          struct MeshTunnel3 *t,
245          struct MeshPeerPath *p,
246          unsigned int own_pos);
247
248 /**
249  * Connection is no longer needed: destroy it and remove from tunnel.
250  *
251  * @param c Connection to destroy.
252  */
253 void
254 GMC_destroy (struct MeshConnection *c);
255
256 /**
257  * Get the connection ID.
258  *
259  * @param c Connection to get the ID from.
260  *
261  * @return ID of the connection.
262  */
263 const struct GNUNET_HashCode *
264 GMC_get_id (const struct MeshConnection *c);
265
266 /**
267  * Get the connection path.
268  *
269  * @param c Connection to get the path from.
270  *
271  * @return path used by the connection.
272  */
273 const struct MeshPeerPath *
274 GMC_get_path (const struct MeshConnection *c);
275
276 /**
277  * Get the connection state.
278  *
279  * @param c Connection to get the state from.
280  *
281  * @return state of the connection.
282  */
283 enum MeshConnectionState
284 GMC_get_state (const struct MeshConnection *c);
285
286 /**
287  * Get the connection tunnel.
288  *
289  * @param c Connection to get the tunnel from.
290  *
291  * @return tunnel of the connection.
292  */
293 struct MeshTunnel3 *
294 GMC_get_tunnel (const struct MeshConnection *c);
295
296 /**
297  * Get free buffer space in a connection.
298  *
299  * @param c Connection.
300  * @param fwd Is query about FWD traffic?
301  *
302  * @return Free buffer space [0 - max_msgs_queue/max_connections]
303  */
304 unsigned int
305 GMC_get_buffer (struct MeshConnection *c, int fwd);
306
307 /**
308  * Get messages queued in a connection.
309  *
310  * @param c Connection.
311  * @param fwd Is query about FWD traffic?
312  *
313  * @return Number of messages queued.
314  */
315 unsigned int
316 GMC_get_qn (struct MeshConnection *c, int fwd);
317
318 /**
319  * Send FWD keepalive packets for a connection.
320  *
321  * @param cls Closure (connection for which to send the keepalive).
322  * @param tc Notification context.
323  */
324 void
325 GMC_fwd_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
326
327 /**
328  * Send BCK keepalive packets for a connection.
329  *
330  * @param cls Closure (connection for which to send the keepalive).
331  * @param tc Notification context.
332  */
333 void
334 GMC_bck_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
335
336
337 /**
338  * Change the tunnel state.
339  *
340  * @param c Connection whose state to change.
341  * @param state New state.
342  */
343 void
344 GMC_change_state (struct MeshConnection* c, enum MeshConnectionState state);
345
346 /**
347  * Notify other peers on a connection of a broken link. Mark connections
348  * to destroy after all traffic has been sent.
349  *
350  * @param c Connection on which there has been a disconnection.
351  * @param peer Peer that disconnected.
352  * @param my_full_id My ID (to send to other peers).
353  */
354 void
355 GMC_notify_broken (struct MeshConnection *c,
356                    struct MeshPeer *peer,
357                    struct GNUNET_PeerIdentity *my_full_id);
358
359 /**
360  * Is this peer the first one on the connection?
361  *
362  * @param c Connection.
363  * @param fwd Is this about fwd traffic?
364  *
365  * @return GNUNET_YES if origin, GNUNET_NO if relay/terminal.
366  */
367 int
368 GMC_is_origin (struct MeshConnection *c, int fwd);
369
370 /**
371  * Is this peer the last one on the connection?
372  *
373  * @param c Connection.
374  * @param fwd Is this about fwd traffic?
375  *            Note that the ROOT is the terminal for BCK traffic!
376  *
377  * @return GNUNET_YES if terminal, GNUNET_NO if relay/origin.
378  */
379 int
380 GMC_is_terminal (struct MeshConnection *c, int fwd);
381
382 /**
383  * See if we are allowed to send by the next hop in the given direction.
384  *
385  * @param c Connection.
386  * @param fwd Is this about fwd traffic?
387  *
388  * @return GNUNET_YES in case it's OK.
389  */
390 int
391 GMC_is_sendable (struct MeshConnection *c, int fwd);
392
393 /**
394  * Sends an already built message on a connection, properly registering
395  * all used resources.
396  *
397  * @param message Message to send. Function makes a copy of it.
398  *                If message is not hop-by-hop, decrements TTL of copy.
399  * @param c Connection on which this message is transmitted.
400  * @param ch Channel on which this message is transmitted, or NULL.
401  * @param fwd Is this a fwd message?
402  */
403 void
404 GMC_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
405                            struct MeshConnection *c,
406                            struct MeshChannel *ch,
407                            int fwd);
408
409 /**
410  * Sends a CREATE CONNECTION message for a path to a peer.
411  * Changes the connection and tunnel states if necessary.
412  *
413  * @param connection Connection to create.
414  */
415 void
416 GMC_send_create (struct MeshConnection *connection);
417
418 /**
419  * Send a message to all peers in this connection that the connection
420  * is no longer valid.
421  *
422  * If some peer should not receive the message, it should be zero'ed out
423  * before calling this function.
424  *
425  * @param c The connection whose peers to notify.
426  */
427 void
428 GMC_send_destroy (struct MeshConnection *c);
429
430 /**
431  * @brief Start a polling timer for the connection.
432  *
433  * When a neighbor does not accept more traffic on the connection it could be
434  * caused by a simple congestion or by a lost ACK. Polling enables to check
435  * for the lastest ACK status for a connection.
436  *
437  * @param c Connection.
438  * @param fwd Should we poll in the FWD direction?
439  */
440 void
441 GMC_start_poll (struct MeshConnection *c, int fwd);
442
443
444 /**
445  * @brief Stop polling a connection for ACKs.
446  *
447  * Once we have enough ACKs for future traffic, polls are no longer necessary.
448  *
449  * @param c Connection.
450  * @param fwd Should we stop the poll in the FWD direction?
451  */
452 void
453 GMC_stop_poll (struct MeshConnection *c, int fwd);
454
455 #if 0                           /* keep Emacsens' auto-indent happy */
456 {
457 #endif
458 #ifdef __cplusplus
459 }
460 #endif
461
462 /* ifndef GNUNET_SERVICE_MESH_CONNECTION_H */
463 #endif
464 /* end of gnunet-service-mesh_connection.h */