2 This file is part of GNUnet.
3 (C) 2013 Christian Grothoff (and other contributing authors)
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.
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.
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.
22 * @file mesh/gnunet-service-mesh_connection.h
23 * @brief mesh service; dealing with connections
24 * @author Bartlomiej Polot
26 * All functions in this file should use the prefix GMC (Gnunet Mesh Connection)
29 #ifndef GNUNET_SERVICE_MESH_CONNECTION_H
30 #define GNUNET_SERVICE_MESH_CONNECTION_H
35 #if 0 /* keep Emacsens' auto-indent happy */
40 #include "gnunet_util_lib.h"
44 * All the states a connection can be in.
46 enum MeshConnectionState
49 * Uninitialized status, should never appear in operation.
54 * Connection create message sent, waiting for ACK.
59 * Connection ACK sent, waiting for ACK.
64 * Connection confirmed, ready to carry traffic.
66 MESH_CONNECTION_READY,
71 * Struct containing all information regarding a connection to a peer.
73 struct MeshConnection;
76 * Handle for messages queued but not yet sent.
78 struct MeshConnectionQueue;
80 #include "mesh_path.h"
81 #include "gnunet-service-mesh_channel.h"
82 #include "gnunet-service-mesh_peer.h"
87 * Callback called when a queued message is sent.
90 * @param c Connection this message was on.
91 * @param type Type of message sent.
92 * @param fwd Was this a FWD going message?
93 * @param size Size of the message.
95 typedef void (*GMC_sent) (void *cls,
96 struct MeshConnection *c,
97 struct MeshConnectionQueue *q,
98 uint16_t type, int fwd, size_t size);
101 * Core handler for connection creation.
103 * @param cls Closure (unused).
104 * @param peer Sender (neighbor).
105 * @param message Message.
107 * @return GNUNET_OK to keep the connection open,
108 * GNUNET_SYSERR to close it (signal serious error)
111 GMC_handle_create (void *cls, const struct GNUNET_PeerIdentity *peer,
112 const struct GNUNET_MessageHeader *message);
115 * Core handler for path confirmations.
118 * @param message message
119 * @param peer peer identity this notification is about
121 * @return GNUNET_OK to keep the connection open,
122 * GNUNET_SYSERR to close it (signal serious error)
125 GMC_handle_confirm (void *cls, const struct GNUNET_PeerIdentity *peer,
126 const struct GNUNET_MessageHeader *message);
129 * Core handler for notifications of broken paths
131 * @param cls Closure (unused).
132 * @param id Peer identity of sending neighbor.
133 * @param message Message.
135 * @return GNUNET_OK to keep the connection open,
136 * GNUNET_SYSERR to close it (signal serious error)
139 GMC_handle_broken (void* cls,
140 const struct GNUNET_PeerIdentity* id,
141 const struct GNUNET_MessageHeader* message);
144 * Core handler for tunnel destruction
146 * @param cls Closure (unused).
147 * @param peer Peer identity of sending neighbor.
148 * @param message Message.
150 * @return GNUNET_OK to keep the connection open,
151 * GNUNET_SYSERR to close it (signal serious error)
154 GMC_handle_destroy (void *cls, const struct GNUNET_PeerIdentity *peer,
155 const struct GNUNET_MessageHeader *message);
158 * Core handler for encrypted mesh network traffic (channel mgmt, data).
160 * @param cls Closure (unused).
161 * @param message Message received.
162 * @param peer Peer who sent the message.
164 * @return GNUNET_OK to keep the connection open,
165 * GNUNET_SYSERR to close it (signal serious error)
168 GMC_handle_encrypted (void *cls, const struct GNUNET_PeerIdentity *peer,
169 const struct GNUNET_MessageHeader *message);
172 * Core handler for key exchange traffic (ephemeral key, ping, pong).
174 * @param cls Closure (unused).
175 * @param message Message received.
176 * @param peer Peer who sent the message.
178 * @return GNUNET_OK to keep the connection open,
179 * GNUNET_SYSERR to close it (signal serious error)
182 GMC_handle_kx (void *cls, const struct GNUNET_PeerIdentity *peer,
183 const struct GNUNET_MessageHeader *message);
186 * Core handler for mesh network traffic point-to-point acks.
189 * @param message message
190 * @param peer peer identity this notification is about
192 * @return GNUNET_OK to keep the connection open,
193 * GNUNET_SYSERR to close it (signal serious error)
196 GMC_handle_ack (void *cls, const struct GNUNET_PeerIdentity *peer,
197 const struct GNUNET_MessageHeader *message);
200 * Core handler for mesh network traffic point-to-point ack polls.
203 * @param message message
204 * @param peer peer identity this notification is about
206 * @return GNUNET_OK to keep the connection open,
207 * GNUNET_SYSERR to close it (signal serious error)
210 GMC_handle_poll (void *cls, const struct GNUNET_PeerIdentity *peer,
211 const struct GNUNET_MessageHeader *message);
214 * Core handler for mesh keepalives.
217 * @param message message
218 * @param peer peer identity this notification is about
219 * @return GNUNET_OK to keep the connection open,
220 * GNUNET_SYSERR to close it (signal serious error)
222 * TODO: Check who we got this from, to validate route.
225 GMC_handle_keepalive (void *cls, const struct GNUNET_PeerIdentity *peer,
226 const struct GNUNET_MessageHeader *message);
229 * Send an ACK on the appropriate connection/channel, depending on
230 * the direction and the position of the peer.
232 * @param c Which connection to send the hop-by-hop ACK.
233 * @param fwd Is this a fwd ACK? (will go dest->root).
234 * @param force Send the ACK even if suboptimal (e.g. requested by POLL).
237 GMC_send_ack (struct MeshConnection *c, int fwd, int force);
240 * Initialize the connections subsystem
242 * @param c Configuration handle.
245 GMC_init (const struct GNUNET_CONFIGURATION_Handle *c);
248 * Shut down the connections subsystem.
254 * Create a connection.
256 * @param cid Connection ID (either created locally or imposed remotely).
257 * @param t Tunnel this connection belongs to (or NULL);
258 * @param p Path this connection has to use.
259 * @param own_pos Own position in the @c p path.
261 * @return Newly created connection, NULL in case of error (own id not in path).
263 struct MeshConnection *
264 GMC_new (const struct GNUNET_HashCode *cid,
265 struct MeshTunnel3 *t,
266 struct MeshPeerPath *p,
267 unsigned int own_pos);
270 * Connection is no longer needed: destroy it.
272 * Cancels all pending traffic (including possible DESTROY messages), all
273 * maintenance tasks and removes the connection from neighbor peers and tunnel.
275 * @param c Connection to destroy.
278 GMC_destroy (struct MeshConnection *c);
281 * Get the connection ID.
283 * @param c Connection to get the ID from.
285 * @return ID of the connection.
287 const struct GNUNET_HashCode *
288 GMC_get_id (const struct MeshConnection *c);
291 * Get the connection path.
293 * @param c Connection to get the path from.
295 * @return path used by the connection.
297 const struct MeshPeerPath *
298 GMC_get_path (const struct MeshConnection *c);
301 * Get the connection state.
303 * @param c Connection to get the state from.
305 * @return state of the connection.
307 enum MeshConnectionState
308 GMC_get_state (const struct MeshConnection *c);
311 * Get the connection tunnel.
313 * @param c Connection to get the tunnel from.
315 * @return tunnel of the connection.
318 GMC_get_tunnel (const struct MeshConnection *c);
321 * Get free buffer space in a connection.
323 * @param c Connection.
324 * @param fwd Is query about FWD traffic?
326 * @return Free buffer space [0 - max_msgs_queue/max_connections]
329 GMC_get_buffer (struct MeshConnection *c, int fwd);
332 * Get how many messages have we allowed to send to us from a direction.
334 * @param c Connection.
335 * @param fwd Are we asking about traffic from FWD (BCK messages)?
337 * @return last_ack_sent - last_pid_recv
340 GMC_get_allowed (struct MeshConnection *c, int fwd);
343 * Get messages queued in a connection.
345 * @param c Connection.
346 * @param fwd Is query about FWD traffic?
348 * @return Number of messages queued.
351 GMC_get_qn (struct MeshConnection *c, int fwd);
354 * Allow the connection to advertise a buffer of the given size.
356 * The connection will send an @c fwd ACK message (so: in direction !fwd)
357 * allowing up to last_pid_recv + buffer.
359 * @param c Connection.
360 * @param buffer How many more messages the connection can accept.
361 * @param fwd Is this about FWD traffic? (The ack will go dest->root).
364 GMC_allow (struct MeshConnection *c, unsigned int buffer, int fwd);
367 * Send FWD keepalive packets for a connection.
369 * @param cls Closure (connection for which to send the keepalive).
370 * @param tc Notification context.
373 GMC_fwd_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
376 * Send BCK keepalive packets for a connection.
378 * @param cls Closure (connection for which to send the keepalive).
379 * @param tc Notification context.
382 GMC_bck_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
386 * Notify other peers on a connection of a broken link. Mark connections
387 * to destroy after all traffic has been sent.
389 * @param c Connection on which there has been a disconnection.
390 * @param peer Peer that disconnected.
393 GMC_notify_broken (struct MeshConnection *c,
394 struct MeshPeer *peer);
397 * Is this peer the first one on the connection?
399 * @param c Connection.
400 * @param fwd Is this about fwd traffic?
402 * @return #GNUNET_YES if origin, #GNUNET_NO if relay/terminal.
405 GMC_is_origin (struct MeshConnection *c, int fwd);
408 * Is this peer the last one on the connection?
410 * @param c Connection.
411 * @param fwd Is this about fwd traffic?
412 * Note that the ROOT is the terminal for BCK traffic!
414 * @return #GNUNET_YES if terminal, #GNUNET_NO if relay/origin.
417 GMC_is_terminal (struct MeshConnection *c, int fwd);
420 * See if we are allowed to send by the next hop in the given direction.
422 * @param c Connection.
423 * @param fwd Is this about fwd traffic?
425 * @return #GNUNET_YES in case it's OK to send.
428 GMC_is_sendable (struct MeshConnection *c, int fwd);
431 * Cancel a previously sent message while it's in the queue.
433 * ONLY can be called before the continuation given to the send function
434 * is called. Once the continuation is called, the message is no longer in the
437 * @param q Handle to the queue.
440 GMC_cancel (struct MeshConnectionQueue *q);
443 * Sends an already built message on a connection, properly registering
444 * all used resources.
446 * @param message Message to send. Function makes a copy of it.
447 * If message is not hop-by-hop, decrements TTL of copy.
448 * @param c Connection on which this message is transmitted.
449 * @param fwd Is this a fwd message?
450 * @param cont Continuation called once message is sent. Can be NULL.
451 * @param cont_cls Closure for @c cont.
453 * @return Handle to cancel the message before it's sent.
454 * NULL on error or if @c cont is NULL.
455 * Invalid on @c cont call.
457 struct MeshConnectionQueue *
458 GMC_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
459 struct MeshConnection *c, int fwd,
460 GMC_sent cont, void *cont_cls);
463 * Sends a CREATE CONNECTION message for a path to a peer.
464 * Changes the connection and tunnel states if necessary.
466 * @param connection Connection to create.
469 GMC_send_create (struct MeshConnection *connection);
472 * Send a message to all peers in this connection that the connection
473 * is no longer valid.
475 * If some peer should not receive the message, it should be zero'ed out
476 * before calling this function.
478 * @param c The connection whose peers to notify.
481 GMC_send_destroy (struct MeshConnection *c);
484 * @brief Start a polling timer for the connection.
486 * When a neighbor does not accept more traffic on the connection it could be
487 * caused by a simple congestion or by a lost ACK. Polling enables to check
488 * for the lastest ACK status for a connection.
490 * @param c Connection.
491 * @param fwd Should we poll in the FWD direction?
494 GMC_start_poll (struct MeshConnection *c, int fwd);
498 * @brief Stop polling a connection for ACKs.
500 * Once we have enough ACKs for future traffic, polls are no longer necessary.
502 * @param c Connection.
503 * @param fwd Should we stop the poll in the FWD direction?
506 GMC_stop_poll (struct MeshConnection *c, int fwd);
509 * Get a (static) string for a connection.
511 * @param c Connection.
514 GMC_2s (struct MeshConnection *c);
516 #if 0 /* keep Emacsens' auto-indent happy */
523 /* ifndef GNUNET_SERVICE_MESH_CONNECTION_H */
525 /* end of gnunet-service-mesh_connection.h */