- fixes
[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 state.
268  *
269  * @param c Connection to get the state from.
270  *
271  * @return state of the connection.
272  */
273 enum MeshConnectionState
274 GMC_get_state (const struct MeshConnection *c);
275
276 /**
277  * Get the connection tunnel.
278  *
279  * @param c Connection to get the tunnel from.
280  *
281  * @return tunnel of the connection.
282  */
283 struct MeshTunnel3 *
284 GMC_get_tunnel (const struct MeshConnection *c);
285
286 /**
287  * Get free buffer space in a connection.
288  *
289  * @param c Connection.
290  * @param fwd Is query about FWD traffic?
291  *
292  * @return Free buffer space [0 - max_msgs_queue/max_connections]
293  */
294 unsigned int
295 GMC_get_buffer (struct MeshConnection *c, int fwd);
296
297 /**
298  * Get messages queued in a connection.
299  *
300  * @param c Connection.
301  * @param fwd Is query about FWD traffic?
302  *
303  * @return Number of messages queued.
304  */
305 unsigned int
306 GMC_get_qn (struct MeshConnection *c, int fwd);
307
308 /**
309  * Send FWD keepalive packets for a connection.
310  *
311  * @param cls Closure (connection for which to send the keepalive).
312  * @param tc Notification context.
313  */
314 void
315 GMC_fwd_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
316
317 /**
318  * Send BCK keepalive packets for a connection.
319  *
320  * @param cls Closure (connection for which to send the keepalive).
321  * @param tc Notification context.
322  */
323 void
324 GMC_bck_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
325
326
327 /**
328  * Change the tunnel state.
329  *
330  * @param c Connection whose state to change.
331  * @param state New state.
332  */
333 void
334 GMC_change_state (struct MeshConnection* c, enum MeshConnectionState state);
335
336 /**
337  * Notify other peers on a connection of a broken link. Mark connections
338  * to destroy after all traffic has been sent.
339  *
340  * @param c Connection on which there has been a disconnection.
341  * @param peer Peer that disconnected.
342  * @param my_full_id My ID (to send to other peers).
343  */
344 void
345 GMC_notify_broken (struct MeshConnection *c,
346                    struct MeshPeer *peer,
347                    struct GNUNET_PeerIdentity *my_full_id);
348
349 /**
350  * Is this peer the first one on the connection?
351  *
352  * @param c Connection.
353  * @param fwd Is this about fwd traffic?
354  *
355  * @return GNUNET_YES if origin, GNUNET_NO if relay/terminal.
356  */
357 int
358 GMC_is_origin (struct MeshConnection *c, int fwd);
359
360 /**
361  * Is this peer the last one on the connection?
362  *
363  * @param c Connection.
364  * @param fwd Is this about fwd traffic?
365  *            Note that the ROOT is the terminal for BCK traffic!
366  *
367  * @return GNUNET_YES if terminal, GNUNET_NO if relay/origin.
368  */
369 int
370 GMC_is_terminal (struct MeshConnection *c, int fwd);
371
372 /**
373  * See if we are allowed to send by the next hop in the given direction.
374  *
375  * @param c Connection.
376  * @param fwd Is this about fwd traffic?
377  *
378  * @return GNUNET_YES in case it's OK.
379  */
380 int
381 GMC_is_sendable (struct MeshConnection *c, int fwd);
382
383 /**
384  * Sends an already built message on a connection, properly registering
385  * all used resources.
386  *
387  * @param message Message to send. Function makes a copy of it.
388  *                If message is not hop-by-hop, decrements TTL of copy.
389  * @param c Connection on which this message is transmitted.
390  * @param ch Channel on which this message is transmitted, or NULL.
391  * @param fwd Is this a fwd message?
392  */
393 void
394 GMC_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
395                            struct MeshConnection *c,
396                            struct MeshChannel *ch,
397                            int fwd);
398
399 /**
400  * Send a message to all peers in this connection that the connection
401  * is no longer valid.
402  *
403  * If some peer should not receive the message, it should be zero'ed out
404  * before calling this function.
405  *
406  * @param c The connection whose peers to notify.
407  */
408 void
409 GMC_send_destroy (struct MeshConnection *c);
410
411 #if 0                           /* keep Emacsens' auto-indent happy */
412 {
413 #endif
414 #ifdef __cplusplus
415 }
416 #endif
417
418 /* ifndef GNUNET_SERVICE_MESH_CONNECTION_H */
419 #endif
420 /* end of gnunet-service-mesh_connection.h */