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 cadet/gnunet-service-cadet_connection.h
23 * @brief cadet service; dealing with connections
24 * @author Bartlomiej Polot
26 * All functions in this file should use the prefix GMC (Gnunet Cadet Connection)
29 #ifndef GNUNET_SERVICE_CADET_CONNECTION_H
30 #define GNUNET_SERVICE_CADET_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 CadetConnectionState
49 * Uninitialized status, should never appear in operation.
54 * Connection create message sent, waiting for ACK.
56 CADET_CONNECTION_SENT,
59 * Connection ACK sent, waiting for ACK.
64 * Connection confirmed, ready to carry traffic.
66 CADET_CONNECTION_READY,
69 * Connection to be destroyed, just waiting to empty queues.
71 CADET_CONNECTION_DESTROYED,
76 * Struct containing all information regarding a connection to a peer.
78 struct CadetConnection;
81 * Handle for messages queued but not yet sent.
83 struct CadetConnectionQueue;
85 #include "cadet_path.h"
86 #include "gnunet-service-cadet_channel.h"
87 #include "gnunet-service-cadet_peer.h"
92 * Callback called when a queued message is sent.
95 * @param c Connection this message was on.
96 * @param type Type of message sent.
97 * @param fwd Was this a FWD going message?
98 * @param size Size of the message.
100 typedef void (*GCC_sent) (void *cls,
101 struct CadetConnection *c,
102 struct CadetConnectionQueue *q,
103 uint16_t type, int fwd, size_t size);
106 * Core handler for connection creation.
108 * @param cls Closure (unused).
109 * @param peer Sender (neighbor).
110 * @param message Message.
112 * @return GNUNET_OK to keep the connection open,
113 * GNUNET_SYSERR to close it (signal serious error)
116 GCC_handle_create (void *cls, const struct GNUNET_PeerIdentity *peer,
117 const struct GNUNET_MessageHeader *message);
120 * Core handler for path confirmations.
123 * @param message message
124 * @param peer peer identity this notification is about
126 * @return GNUNET_OK to keep the connection open,
127 * GNUNET_SYSERR to close it (signal serious error)
130 GCC_handle_confirm (void *cls, const struct GNUNET_PeerIdentity *peer,
131 const struct GNUNET_MessageHeader *message);
134 * Core handler for notifications of broken paths
136 * @param cls Closure (unused).
137 * @param id Peer identity of sending neighbor.
138 * @param message Message.
140 * @return GNUNET_OK to keep the connection open,
141 * GNUNET_SYSERR to close it (signal serious error)
144 GCC_handle_broken (void* cls,
145 const struct GNUNET_PeerIdentity* id,
146 const struct GNUNET_MessageHeader* message);
149 * Core handler for tunnel destruction
151 * @param cls Closure (unused).
152 * @param peer Peer identity of sending neighbor.
153 * @param message Message.
155 * @return GNUNET_OK to keep the connection open,
156 * GNUNET_SYSERR to close it (signal serious error)
159 GCC_handle_destroy (void *cls, const struct GNUNET_PeerIdentity *peer,
160 const struct GNUNET_MessageHeader *message);
163 * Core handler for encrypted cadet network traffic (channel mgmt, data).
165 * @param cls Closure (unused).
166 * @param message Message received.
167 * @param peer Peer who sent the message.
169 * @return GNUNET_OK to keep the connection open,
170 * GNUNET_SYSERR to close it (signal serious error)
173 GCC_handle_encrypted (void *cls, const struct GNUNET_PeerIdentity *peer,
174 const struct GNUNET_MessageHeader *message);
177 * Core handler for key exchange traffic (ephemeral key, ping, pong).
179 * @param cls Closure (unused).
180 * @param message Message received.
181 * @param peer Peer who sent the message.
183 * @return GNUNET_OK to keep the connection open,
184 * GNUNET_SYSERR to close it (signal serious error)
187 GCC_handle_kx (void *cls, const struct GNUNET_PeerIdentity *peer,
188 const struct GNUNET_MessageHeader *message);
191 * Core handler for cadet network traffic point-to-point acks.
194 * @param message message
195 * @param peer peer identity this notification is about
197 * @return GNUNET_OK to keep the connection open,
198 * GNUNET_SYSERR to close it (signal serious error)
201 GCC_handle_ack (void *cls, const struct GNUNET_PeerIdentity *peer,
202 const struct GNUNET_MessageHeader *message);
205 * Core handler for cadet network traffic point-to-point ack polls.
208 * @param message message
209 * @param peer peer identity this notification is about
211 * @return GNUNET_OK to keep the connection open,
212 * GNUNET_SYSERR to close it (signal serious error)
215 GCC_handle_poll (void *cls, const struct GNUNET_PeerIdentity *peer,
216 const struct GNUNET_MessageHeader *message);
219 * Core handler for cadet keepalives.
222 * @param message message
223 * @param peer peer identity this notification is about
224 * @return GNUNET_OK to keep the connection open,
225 * GNUNET_SYSERR to close it (signal serious error)
227 * TODO: Check who we got this from, to validate route.
230 GCC_handle_keepalive (void *cls, const struct GNUNET_PeerIdentity *peer,
231 const struct GNUNET_MessageHeader *message);
234 * Send an ACK on the appropriate connection/channel, depending on
235 * the direction and the position of the peer.
237 * @param c Which connection to send the hop-by-hop ACK.
238 * @param fwd Is this a fwd ACK? (will go dest->root).
239 * @param force Send the ACK even if suboptimal (e.g. requested by POLL).
242 GCC_send_ack (struct CadetConnection *c, int fwd, int force);
245 * Initialize the connections subsystem
247 * @param c Configuration handle.
250 GCC_init (const struct GNUNET_CONFIGURATION_Handle *c);
253 * Shut down the connections subsystem.
259 * Create a connection.
261 * @param cid Connection ID (either created locally or imposed remotely).
262 * @param t Tunnel this connection belongs to (or NULL);
263 * @param p Path this connection has to use.
264 * @param own_pos Own position in the @c p path.
266 * @return Newly created connection, NULL in case of error (own id not in path).
268 struct CadetConnection *
269 GCC_new (const struct GNUNET_CADET_Hash *cid,
270 struct CadetTunnel *t,
271 struct CadetPeerPath *p,
272 unsigned int own_pos);
275 * Connection is no longer needed: destroy it.
277 * Cancels all pending traffic (including possible DESTROY messages), all
278 * maintenance tasks and removes the connection from neighbor peers and tunnel.
280 * @param c Connection to destroy.
283 GCC_destroy (struct CadetConnection *c);
286 * Get the connection ID.
288 * @param c Connection to get the ID from.
290 * @return ID of the connection.
292 const struct GNUNET_CADET_Hash *
293 GCC_get_id (const struct CadetConnection *c);
297 * Get a hash for the connection ID.
299 * @param c Connection to get the hash.
301 * @return Hash expanded from the ID of the connection.
303 const struct GNUNET_HashCode *
304 GCC_get_h (const struct CadetConnection *c);
308 * Get the connection path.
310 * @param c Connection to get the path from.
312 * @return path used by the connection.
314 const struct CadetPeerPath *
315 GCC_get_path (const struct CadetConnection *c);
318 * Get the connection state.
320 * @param c Connection to get the state from.
322 * @return state of the connection.
324 enum CadetConnectionState
325 GCC_get_state (const struct CadetConnection *c);
328 * Get the connection tunnel.
330 * @param c Connection to get the tunnel from.
332 * @return tunnel of the connection.
335 GCC_get_tunnel (const struct CadetConnection *c);
338 * Get free buffer space in a connection.
340 * @param c Connection.
341 * @param fwd Is query about FWD traffic?
343 * @return Free buffer space [0 - max_msgs_queue/max_connections]
346 GCC_get_buffer (struct CadetConnection *c, int fwd);
349 * Get how many messages have we allowed to send to us from a direction.
351 * @param c Connection.
352 * @param fwd Are we asking about traffic from FWD (BCK messages)?
354 * @return last_ack_sent - last_pid_recv
357 GCC_get_allowed (struct CadetConnection *c, int fwd);
360 * Get messages queued in a connection.
362 * @param c Connection.
363 * @param fwd Is query about FWD traffic?
365 * @return Number of messages queued.
368 GCC_get_qn (struct CadetConnection *c, int fwd);
371 * Get next PID to use.
373 * @param c Connection.
374 * @param fwd Is query about FWD traffic?
376 * @return Last PID used + 1.
379 GCC_get_pid (struct CadetConnection *c, int fwd);
382 * Allow the connection to advertise a buffer of the given size.
384 * The connection will send an @c fwd ACK message (so: in direction !fwd)
385 * allowing up to last_pid_recv + buffer.
387 * @param c Connection.
388 * @param buffer How many more messages the connection can accept.
389 * @param fwd Is this about FWD traffic? (The ack will go dest->root).
392 GCC_allow (struct CadetConnection *c, unsigned int buffer, int fwd);
395 * Send FWD keepalive packets for a connection.
397 * @param cls Closure (connection for which to send the keepalive).
398 * @param tc Notification context.
401 GCC_fwd_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
404 * Send BCK keepalive packets for a connection.
406 * @param cls Closure (connection for which to send the keepalive).
407 * @param tc Notification context.
410 GCC_bck_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc);
414 * Notify other peers on a connection of a broken link. Mark connections
415 * to destroy after all traffic has been sent.
417 * @param c Connection on which there has been a disconnection.
418 * @param peer Peer that disconnected.
421 GCC_notify_broken (struct CadetConnection *c,
422 struct CadetPeer *peer);
425 * Is this peer the first one on the connection?
427 * @param c Connection.
428 * @param fwd Is this about fwd traffic?
430 * @return #GNUNET_YES if origin, #GNUNET_NO if relay/terminal.
433 GCC_is_origin (struct CadetConnection *c, int fwd);
436 * Is this peer the last one on the connection?
438 * @param c Connection.
439 * @param fwd Is this about fwd traffic?
440 * Note that the ROOT is the terminal for BCK traffic!
442 * @return #GNUNET_YES if terminal, #GNUNET_NO if relay/origin.
445 GCC_is_terminal (struct CadetConnection *c, int fwd);
448 * See if we are allowed to send by the next hop in the given direction.
450 * @param c Connection.
451 * @param fwd Is this about fwd traffic?
453 * @return #GNUNET_YES in case it's OK to send.
456 GCC_is_sendable (struct CadetConnection *c, int fwd);
459 * Check if this connection is a direct one (never trim a direct connection).
461 * @param c Connection.
463 * @return #GNUNET_YES in case it's a direct connection, #GNUNET_NO otherwise.
466 GCC_is_direct (struct CadetConnection *c);
469 * Cancel a previously sent message while it's in the queue.
471 * ONLY can be called before the continuation given to the send function
472 * is called. Once the continuation is called, the message is no longer in the
475 * @param q Handle to the queue.
478 GCC_cancel (struct CadetConnectionQueue *q);
481 * Sends an already built message on a connection, properly registering
482 * all used resources.
484 * @param message Message to send. Function makes a copy of it.
485 * If message is not hop-by-hop, decrements TTL of copy.
486 * @param payload_type Type of payload, in case the message is encrypted.
487 * @param c Connection on which this message is transmitted.
488 * @param fwd Is this a fwd message?
489 * @param force Force the connection to accept the message (buffer overfill).
490 * @param cont Continuation called once message is sent. Can be NULL.
491 * @param cont_cls Closure for @c cont.
493 * @return Handle to cancel the message before it's sent.
494 * NULL on error or if @c cont is NULL.
495 * Invalid on @c cont call.
497 struct CadetConnectionQueue *
498 GCC_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
499 uint16_t payload_type, uint32_t payload_id,
500 struct CadetConnection *c, int fwd, int force,
501 GCC_sent cont, void *cont_cls);
504 * Sends a CREATE CONNECTION message for a path to a peer.
505 * Changes the connection and tunnel states if necessary.
507 * @param connection Connection to create.
510 GCC_send_create (struct CadetConnection *connection);
513 * Send a message to all peers in this connection that the connection
514 * is no longer valid.
516 * If some peer should not receive the message, it should be zero'ed out
517 * before calling this function.
519 * @param c The connection whose peers to notify.
522 GCC_send_destroy (struct CadetConnection *c);
525 * @brief Start a polling timer for the connection.
527 * When a neighbor does not accept more traffic on the connection it could be
528 * caused by a simple congestion or by a lost ACK. Polling enables to check
529 * for the lastest ACK status for a connection.
531 * @param c Connection.
532 * @param fwd Should we poll in the FWD direction?
535 GCC_start_poll (struct CadetConnection *c, int fwd);
539 * @brief Stop polling a connection for ACKs.
541 * Once we have enough ACKs for future traffic, polls are no longer necessary.
543 * @param c Connection.
544 * @param fwd Should we stop the poll in the FWD direction?
547 GCC_stop_poll (struct CadetConnection *c, int fwd);
550 * Get a (static) string for a connection.
552 * @param c Connection.
555 GCC_2s (const struct CadetConnection *c);
557 #if 0 /* keep Emacsens' auto-indent happy */
564 /* ifndef GNUNET_SERVICE_CADET_CONNECTION_H */
566 /* end of gnunet-service-cadet_connection.h */