diff options
Diffstat (limited to 'src/cadet/gnunet-service-cadet_connection.h')
-rw-r--r-- | src/cadet/gnunet-service-cadet_connection.h | 566 |
1 files changed, 566 insertions, 0 deletions
diff --git a/src/cadet/gnunet-service-cadet_connection.h b/src/cadet/gnunet-service-cadet_connection.h new file mode 100644 index 000000000..4e1104c2b --- /dev/null +++ b/src/cadet/gnunet-service-cadet_connection.h | |||
@@ -0,0 +1,566 @@ | |||
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 cadet/gnunet-service-cadet_connection.h | ||
23 | * @brief cadet service; dealing with connections | ||
24 | * @author Bartlomiej Polot | ||
25 | * | ||
26 | * All functions in this file should use the prefix GMC (Gnunet Cadet Connection) | ||
27 | */ | ||
28 | |||
29 | #ifndef GNUNET_SERVICE_CADET_CONNECTION_H | ||
30 | #define GNUNET_SERVICE_CADET_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 CadetConnectionState | ||
47 | { | ||
48 | /** | ||
49 | * Uninitialized status, should never appear in operation. | ||
50 | */ | ||
51 | CADET_CONNECTION_NEW, | ||
52 | |||
53 | /** | ||
54 | * Connection create message sent, waiting for ACK. | ||
55 | */ | ||
56 | CADET_CONNECTION_SENT, | ||
57 | |||
58 | /** | ||
59 | * Connection ACK sent, waiting for ACK. | ||
60 | */ | ||
61 | CADET_CONNECTION_ACK, | ||
62 | |||
63 | /** | ||
64 | * Connection confirmed, ready to carry traffic. | ||
65 | */ | ||
66 | CADET_CONNECTION_READY, | ||
67 | |||
68 | /** | ||
69 | * Connection to be destroyed, just waiting to empty queues. | ||
70 | */ | ||
71 | CADET_CONNECTION_DESTROYED, | ||
72 | }; | ||
73 | |||
74 | |||
75 | /** | ||
76 | * Struct containing all information regarding a connection to a peer. | ||
77 | */ | ||
78 | struct CadetConnection; | ||
79 | |||
80 | /** | ||
81 | * Handle for messages queued but not yet sent. | ||
82 | */ | ||
83 | struct CadetConnectionQueue; | ||
84 | |||
85 | #include "cadet_path.h" | ||
86 | #include "gnunet-service-cadet_channel.h" | ||
87 | #include "gnunet-service-cadet_peer.h" | ||
88 | |||
89 | |||
90 | |||
91 | /** | ||
92 | * Callback called when a queued message is sent. | ||
93 | * | ||
94 | * @param cls Closure. | ||
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. | ||
99 | */ | ||
100 | typedef void (*GMC_sent) (void *cls, | ||
101 | struct CadetConnection *c, | ||
102 | struct CadetConnectionQueue *q, | ||
103 | uint16_t type, int fwd, size_t size); | ||
104 | |||
105 | /** | ||
106 | * Core handler for connection creation. | ||
107 | * | ||
108 | * @param cls Closure (unused). | ||
109 | * @param peer Sender (neighbor). | ||
110 | * @param message Message. | ||
111 | * | ||
112 | * @return GNUNET_OK to keep the connection open, | ||
113 | * GNUNET_SYSERR to close it (signal serious error) | ||
114 | */ | ||
115 | int | ||
116 | GMC_handle_create (void *cls, const struct GNUNET_PeerIdentity *peer, | ||
117 | const struct GNUNET_MessageHeader *message); | ||
118 | |||
119 | /** | ||
120 | * Core handler for path confirmations. | ||
121 | * | ||
122 | * @param cls closure | ||
123 | * @param message message | ||
124 | * @param peer peer identity this notification is about | ||
125 | * | ||
126 | * @return GNUNET_OK to keep the connection open, | ||
127 | * GNUNET_SYSERR to close it (signal serious error) | ||
128 | */ | ||
129 | int | ||
130 | GMC_handle_confirm (void *cls, const struct GNUNET_PeerIdentity *peer, | ||
131 | const struct GNUNET_MessageHeader *message); | ||
132 | |||
133 | /** | ||
134 | * Core handler for notifications of broken paths | ||
135 | * | ||
136 | * @param cls Closure (unused). | ||
137 | * @param id Peer identity of sending neighbor. | ||
138 | * @param message Message. | ||
139 | * | ||
140 | * @return GNUNET_OK to keep the connection open, | ||
141 | * GNUNET_SYSERR to close it (signal serious error) | ||
142 | */ | ||
143 | int | ||
144 | GMC_handle_broken (void* cls, | ||
145 | const struct GNUNET_PeerIdentity* id, | ||
146 | const struct GNUNET_MessageHeader* message); | ||
147 | |||
148 | /** | ||
149 | * Core handler for tunnel destruction | ||
150 | * | ||
151 | * @param cls Closure (unused). | ||
152 | * @param peer Peer identity of sending neighbor. | ||
153 | * @param message Message. | ||
154 | * | ||
155 | * @return GNUNET_OK to keep the connection open, | ||
156 | * GNUNET_SYSERR to close it (signal serious error) | ||
157 | */ | ||
158 | int | ||
159 | GMC_handle_destroy (void *cls, const struct GNUNET_PeerIdentity *peer, | ||
160 | const struct GNUNET_MessageHeader *message); | ||
161 | |||
162 | /** | ||
163 | * Core handler for encrypted cadet network traffic (channel mgmt, data). | ||
164 | * | ||
165 | * @param cls Closure (unused). | ||
166 | * @param message Message received. | ||
167 | * @param peer Peer who sent the message. | ||
168 | * | ||
169 | * @return GNUNET_OK to keep the connection open, | ||
170 | * GNUNET_SYSERR to close it (signal serious error) | ||
171 | */ | ||
172 | int | ||
173 | GMC_handle_encrypted (void *cls, const struct GNUNET_PeerIdentity *peer, | ||
174 | const struct GNUNET_MessageHeader *message); | ||
175 | |||
176 | /** | ||
177 | * Core handler for key exchange traffic (ephemeral key, ping, pong). | ||
178 | * | ||
179 | * @param cls Closure (unused). | ||
180 | * @param message Message received. | ||
181 | * @param peer Peer who sent the message. | ||
182 | * | ||
183 | * @return GNUNET_OK to keep the connection open, | ||
184 | * GNUNET_SYSERR to close it (signal serious error) | ||
185 | */ | ||
186 | int | ||
187 | GMC_handle_kx (void *cls, const struct GNUNET_PeerIdentity *peer, | ||
188 | const struct GNUNET_MessageHeader *message); | ||
189 | |||
190 | /** | ||
191 | * Core handler for cadet network traffic point-to-point acks. | ||
192 | * | ||
193 | * @param cls closure | ||
194 | * @param message message | ||
195 | * @param peer peer identity this notification is about | ||
196 | * | ||
197 | * @return GNUNET_OK to keep the connection open, | ||
198 | * GNUNET_SYSERR to close it (signal serious error) | ||
199 | */ | ||
200 | int | ||
201 | GMC_handle_ack (void *cls, const struct GNUNET_PeerIdentity *peer, | ||
202 | const struct GNUNET_MessageHeader *message); | ||
203 | |||
204 | /** | ||
205 | * Core handler for cadet network traffic point-to-point ack polls. | ||
206 | * | ||
207 | * @param cls closure | ||
208 | * @param message message | ||
209 | * @param peer peer identity this notification is about | ||
210 | * | ||
211 | * @return GNUNET_OK to keep the connection open, | ||
212 | * GNUNET_SYSERR to close it (signal serious error) | ||
213 | */ | ||
214 | int | ||
215 | GMC_handle_poll (void *cls, const struct GNUNET_PeerIdentity *peer, | ||
216 | const struct GNUNET_MessageHeader *message); | ||
217 | |||
218 | /** | ||
219 | * Core handler for cadet keepalives. | ||
220 | * | ||
221 | * @param cls closure | ||
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) | ||
226 | * | ||
227 | * TODO: Check who we got this from, to validate route. | ||
228 | */ | ||
229 | int | ||
230 | GMC_handle_keepalive (void *cls, const struct GNUNET_PeerIdentity *peer, | ||
231 | const struct GNUNET_MessageHeader *message); | ||
232 | |||
233 | /** | ||
234 | * Send an ACK on the appropriate connection/channel, depending on | ||
235 | * the direction and the position of the peer. | ||
236 | * | ||
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). | ||
240 | */ | ||
241 | void | ||
242 | GMC_send_ack (struct CadetConnection *c, int fwd, int force); | ||
243 | |||
244 | /** | ||
245 | * Initialize the connections subsystem | ||
246 | * | ||
247 | * @param c Configuration handle. | ||
248 | */ | ||
249 | void | ||
250 | GMC_init (const struct GNUNET_CONFIGURATION_Handle *c); | ||
251 | |||
252 | /** | ||
253 | * Shut down the connections subsystem. | ||
254 | */ | ||
255 | void | ||
256 | GMC_shutdown (void); | ||
257 | |||
258 | /** | ||
259 | * Create a connection. | ||
260 | * | ||
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. | ||
265 | * | ||
266 | * @return Newly created connection, NULL in case of error (own id not in path). | ||
267 | */ | ||
268 | struct CadetConnection * | ||
269 | GMC_new (const struct GNUNET_CADET_Hash *cid, | ||
270 | struct CadetTunnel3 *t, | ||
271 | struct CadetPeerPath *p, | ||
272 | unsigned int own_pos); | ||
273 | |||
274 | /** | ||
275 | * Connection is no longer needed: destroy it. | ||
276 | * | ||
277 | * Cancels all pending traffic (including possible DESTROY messages), all | ||
278 | * maintenance tasks and removes the connection from neighbor peers and tunnel. | ||
279 | * | ||
280 | * @param c Connection to destroy. | ||
281 | */ | ||
282 | void | ||
283 | GMC_destroy (struct CadetConnection *c); | ||
284 | |||
285 | /** | ||
286 | * Get the connection ID. | ||
287 | * | ||
288 | * @param c Connection to get the ID from. | ||
289 | * | ||
290 | * @return ID of the connection. | ||
291 | */ | ||
292 | const struct GNUNET_CADET_Hash * | ||
293 | GMC_get_id (const struct CadetConnection *c); | ||
294 | |||
295 | |||
296 | /** | ||
297 | * Get a hash for the connection ID. | ||
298 | * | ||
299 | * @param c Connection to get the hash. | ||
300 | * | ||
301 | * @return Hash expanded from the ID of the connection. | ||
302 | */ | ||
303 | const struct GNUNET_HashCode * | ||
304 | GMC_get_h (const struct CadetConnection *c); | ||
305 | |||
306 | |||
307 | /** | ||
308 | * Get the connection path. | ||
309 | * | ||
310 | * @param c Connection to get the path from. | ||
311 | * | ||
312 | * @return path used by the connection. | ||
313 | */ | ||
314 | const struct CadetPeerPath * | ||
315 | GMC_get_path (const struct CadetConnection *c); | ||
316 | |||
317 | /** | ||
318 | * Get the connection state. | ||
319 | * | ||
320 | * @param c Connection to get the state from. | ||
321 | * | ||
322 | * @return state of the connection. | ||
323 | */ | ||
324 | enum CadetConnectionState | ||
325 | GMC_get_state (const struct CadetConnection *c); | ||
326 | |||
327 | /** | ||
328 | * Get the connection tunnel. | ||
329 | * | ||
330 | * @param c Connection to get the tunnel from. | ||
331 | * | ||
332 | * @return tunnel of the connection. | ||
333 | */ | ||
334 | struct CadetTunnel3 * | ||
335 | GMC_get_tunnel (const struct CadetConnection *c); | ||
336 | |||
337 | /** | ||
338 | * Get free buffer space in a connection. | ||
339 | * | ||
340 | * @param c Connection. | ||
341 | * @param fwd Is query about FWD traffic? | ||
342 | * | ||
343 | * @return Free buffer space [0 - max_msgs_queue/max_connections] | ||
344 | */ | ||
345 | unsigned int | ||
346 | GMC_get_buffer (struct CadetConnection *c, int fwd); | ||
347 | |||
348 | /** | ||
349 | * Get how many messages have we allowed to send to us from a direction. | ||
350 | * | ||
351 | * @param c Connection. | ||
352 | * @param fwd Are we asking about traffic from FWD (BCK messages)? | ||
353 | * | ||
354 | * @return last_ack_sent - last_pid_recv | ||
355 | */ | ||
356 | unsigned int | ||
357 | GMC_get_allowed (struct CadetConnection *c, int fwd); | ||
358 | |||
359 | /** | ||
360 | * Get messages queued in a connection. | ||
361 | * | ||
362 | * @param c Connection. | ||
363 | * @param fwd Is query about FWD traffic? | ||
364 | * | ||
365 | * @return Number of messages queued. | ||
366 | */ | ||
367 | unsigned int | ||
368 | GMC_get_qn (struct CadetConnection *c, int fwd); | ||
369 | |||
370 | /** | ||
371 | * Get next PID to use. | ||
372 | * | ||
373 | * @param c Connection. | ||
374 | * @param fwd Is query about FWD traffic? | ||
375 | * | ||
376 | * @return Last PID used + 1. | ||
377 | */ | ||
378 | unsigned int | ||
379 | GMC_get_pid (struct CadetConnection *c, int fwd); | ||
380 | |||
381 | /** | ||
382 | * Allow the connection to advertise a buffer of the given size. | ||
383 | * | ||
384 | * The connection will send an @c fwd ACK message (so: in direction !fwd) | ||
385 | * allowing up to last_pid_recv + buffer. | ||
386 | * | ||
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). | ||
390 | */ | ||
391 | void | ||
392 | GMC_allow (struct CadetConnection *c, unsigned int buffer, int fwd); | ||
393 | |||
394 | /** | ||
395 | * Send FWD keepalive packets for a connection. | ||
396 | * | ||
397 | * @param cls Closure (connection for which to send the keepalive). | ||
398 | * @param tc Notification context. | ||
399 | */ | ||
400 | void | ||
401 | GMC_fwd_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc); | ||
402 | |||
403 | /** | ||
404 | * Send BCK keepalive packets for a connection. | ||
405 | * | ||
406 | * @param cls Closure (connection for which to send the keepalive). | ||
407 | * @param tc Notification context. | ||
408 | */ | ||
409 | void | ||
410 | GMC_bck_keepalive (void *cls, const struct GNUNET_SCHEDULER_TaskContext *tc); | ||
411 | |||
412 | |||
413 | /** | ||
414 | * Notify other peers on a connection of a broken link. Mark connections | ||
415 | * to destroy after all traffic has been sent. | ||
416 | * | ||
417 | * @param c Connection on which there has been a disconnection. | ||
418 | * @param peer Peer that disconnected. | ||
419 | */ | ||
420 | void | ||
421 | GMC_notify_broken (struct CadetConnection *c, | ||
422 | struct CadetPeer *peer); | ||
423 | |||
424 | /** | ||
425 | * Is this peer the first one on the connection? | ||
426 | * | ||
427 | * @param c Connection. | ||
428 | * @param fwd Is this about fwd traffic? | ||
429 | * | ||
430 | * @return #GNUNET_YES if origin, #GNUNET_NO if relay/terminal. | ||
431 | */ | ||
432 | int | ||
433 | GMC_is_origin (struct CadetConnection *c, int fwd); | ||
434 | |||
435 | /** | ||
436 | * Is this peer the last one on the connection? | ||
437 | * | ||
438 | * @param c Connection. | ||
439 | * @param fwd Is this about fwd traffic? | ||
440 | * Note that the ROOT is the terminal for BCK traffic! | ||
441 | * | ||
442 | * @return #GNUNET_YES if terminal, #GNUNET_NO if relay/origin. | ||
443 | */ | ||
444 | int | ||
445 | GMC_is_terminal (struct CadetConnection *c, int fwd); | ||
446 | |||
447 | /** | ||
448 | * See if we are allowed to send by the next hop in the given direction. | ||
449 | * | ||
450 | * @param c Connection. | ||
451 | * @param fwd Is this about fwd traffic? | ||
452 | * | ||
453 | * @return #GNUNET_YES in case it's OK to send. | ||
454 | */ | ||
455 | int | ||
456 | GMC_is_sendable (struct CadetConnection *c, int fwd); | ||
457 | |||
458 | /** | ||
459 | * Check if this connection is a direct one (never trim a direct connection). | ||
460 | * | ||
461 | * @param c Connection. | ||
462 | * | ||
463 | * @return #GNUNET_YES in case it's a direct connection, #GNUNET_NO otherwise. | ||
464 | */ | ||
465 | int | ||
466 | GMC_is_direct (struct CadetConnection *c); | ||
467 | |||
468 | /** | ||
469 | * Cancel a previously sent message while it's in the queue. | ||
470 | * | ||
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 | ||
473 | * queue. | ||
474 | * | ||
475 | * @param q Handle to the queue. | ||
476 | */ | ||
477 | void | ||
478 | GMC_cancel (struct CadetConnectionQueue *q); | ||
479 | |||
480 | /** | ||
481 | * Sends an already built message on a connection, properly registering | ||
482 | * all used resources. | ||
483 | * | ||
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. | ||
492 | * | ||
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. | ||
496 | */ | ||
497 | struct CadetConnectionQueue * | ||
498 | GMC_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 | GMC_sent cont, void *cont_cls); | ||
502 | |||
503 | /** | ||
504 | * Sends a CREATE CONNECTION message for a path to a peer. | ||
505 | * Changes the connection and tunnel states if necessary. | ||
506 | * | ||
507 | * @param connection Connection to create. | ||
508 | */ | ||
509 | void | ||
510 | GMC_send_create (struct CadetConnection *connection); | ||
511 | |||
512 | /** | ||
513 | * Send a message to all peers in this connection that the connection | ||
514 | * is no longer valid. | ||
515 | * | ||
516 | * If some peer should not receive the message, it should be zero'ed out | ||
517 | * before calling this function. | ||
518 | * | ||
519 | * @param c The connection whose peers to notify. | ||
520 | */ | ||
521 | void | ||
522 | GMC_send_destroy (struct CadetConnection *c); | ||
523 | |||
524 | /** | ||
525 | * @brief Start a polling timer for the connection. | ||
526 | * | ||
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. | ||
530 | * | ||
531 | * @param c Connection. | ||
532 | * @param fwd Should we poll in the FWD direction? | ||
533 | */ | ||
534 | void | ||
535 | GMC_start_poll (struct CadetConnection *c, int fwd); | ||
536 | |||
537 | |||
538 | /** | ||
539 | * @brief Stop polling a connection for ACKs. | ||
540 | * | ||
541 | * Once we have enough ACKs for future traffic, polls are no longer necessary. | ||
542 | * | ||
543 | * @param c Connection. | ||
544 | * @param fwd Should we stop the poll in the FWD direction? | ||
545 | */ | ||
546 | void | ||
547 | GMC_stop_poll (struct CadetConnection *c, int fwd); | ||
548 | |||
549 | /** | ||
550 | * Get a (static) string for a connection. | ||
551 | * | ||
552 | * @param c Connection. | ||
553 | */ | ||
554 | const char * | ||
555 | GMC_2s (const struct CadetConnection *c); | ||
556 | |||
557 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
558 | { | ||
559 | #endif | ||
560 | #ifdef __cplusplus | ||
561 | } | ||
562 | #endif | ||
563 | |||
564 | /* ifndef GNUNET_SERVICE_CADET_CONNECTION_H */ | ||
565 | #endif | ||
566 | /* end of gnunet-service-cadet_connection.h */ | ||