aboutsummaryrefslogtreecommitdiff
path: root/src/include/gnunet_transport_service.h
diff options
context:
space:
mode:
Diffstat (limited to 'src/include/gnunet_transport_service.h')
-rw-r--r--src/include/gnunet_transport_service.h284
1 files changed, 253 insertions, 31 deletions
diff --git a/src/include/gnunet_transport_service.h b/src/include/gnunet_transport_service.h
index 4b0735b10..dee8e7118 100644
--- a/src/include/gnunet_transport_service.h
+++ b/src/include/gnunet_transport_service.h
@@ -45,6 +45,170 @@ extern "C"
45 45
46 46
47/** 47/**
48 * Possible state of a neighbour. Initially, we are #S_NOT_CONNECTED.
49 *
50 * Then, there are two main paths. If we receive a CONNECT message, we
51 * first run a check against the blacklist (#S_CONNECT_RECV_BLACKLIST_INBOUND).
52 * If this check is successful, we give the inbound address to ATS.
53 * After the check we ask ATS for a suggestion (S_CONNECT_RECV_ATS).
54 * If ATS makes a suggestion, we ALSO give that suggestion to the blacklist
55 * (#S_CONNECT_RECV_BLACKLIST). Once the blacklist approves the
56 * address we got from ATS, we send our CONNECT_ACK and go to
57 * #S_CONNECT_RECV_ACK. If we receive a SESSION_ACK, we go to
58 * #S_CONNECTED (and notify everyone about the new connection). If the
59 * operation times out, we go to #S_DISCONNECT.
60 *
61 * The other case is where we transmit a CONNECT message first. We
62 * start with #S_INIT_ATS. If we get an address, we enter
63 * #S_INIT_BLACKLIST and check the blacklist. If the blacklist is OK
64 * with the connection, we actually send the CONNECT message and go to
65 * state S_CONNECT_SENT. Once we receive a CONNECT_ACK, we go to
66 * #S_CONNECTED (and notify everyone about the new connection and send
67 * back a SESSION_ACK). If the operation times out, we go to
68 * #S_DISCONNECT.
69 *
70 * If the session is in trouble (i.e. transport-level disconnect or
71 * timeout), we go to #S_RECONNECT_ATS where we ask ATS for a new
72 * address (we don't notify anyone about the disconnect yet). Once we
73 * have a new address, we go to #S_RECONNECT_BLACKLIST to check the new
74 * address against the blacklist. If the blacklist approves, we enter
75 * #S_RECONNECT_SENT and send a CONNECT message. If we receive a
76 * CONNECT_ACK, we go to #S_CONNECTED and nobody noticed that we had
77 * trouble; we also send a SESSION_ACK at this time just in case. If
78 * the operation times out, we go to S_DISCONNECT (and notify everyone
79 * about the lost connection).
80 *
81 * If ATS decides to switch addresses while we have a normal
82 * connection, we go to #S_CONNECTED_SWITCHING_BLACKLIST to check the
83 * new address against the blacklist. If the blacklist approves, we
84 * go to #S_CONNECTED_SWITCHING_CONNECT_SENT and send a
85 * SESSION_CONNECT. If we get a SESSION_ACK back, we switch the
86 * primary connection to the suggested alternative from ATS, go back
87 * to #S_CONNECTED and send a SESSION_ACK to the other peer just to be
88 * sure. If the operation times out (or the blacklist disapproves),
89 * we go to #S_CONNECTED (and notify ATS that the given alternative
90 * address is "invalid").
91 *
92 * Once a session is in #S_DISCONNECT, it is cleaned up and then goes
93 * to (#S_DISCONNECT_FINISHED). If we receive an explicit disconnect
94 * request, we can go from any state to #S_DISCONNECT, possibly after
95 * generating disconnect notifications.
96 *
97 * Note that it is quite possible that while we are in any of these
98 * states, we could receive a 'CONNECT' request from the other peer.
99 * We then enter a 'weird' state where we pursue our own primary state
100 * machine (as described above), but with the 'send_connect_ack' flag
101 * set to 1. If our state machine allows us to send a 'CONNECT_ACK'
102 * (because we have an acceptable address), we send the 'CONNECT_ACK'
103 * and set the 'send_connect_ack' to 2. If we then receive a
104 * 'SESSION_ACK', we go to #S_CONNECTED (and reset 'send_connect_ack'
105 * to 0).
106 *
107 */
108enum GNUNET_TRANSPORT_PeerState
109{
110 /**
111 * fresh peer or completely disconnected
112 */
113 S_NOT_CONNECTED = 0,
114
115 /**
116 * Asked to initiate connection, trying to get address from ATS
117 */
118 S_INIT_ATS,
119
120 /**
121 * Asked to initiate connection, trying to get address approved
122 * by blacklist.
123 */
124 S_INIT_BLACKLIST,
125
126 /**
127 * Sent CONNECT message to other peer, waiting for CONNECT_ACK
128 */
129 S_CONNECT_SENT,
130
131 /**
132 * Received a CONNECT, do a blacklist check for inbound address
133 */
134 S_CONNECT_RECV_BLACKLIST_INBOUND,
135
136 /**
137 * Received a CONNECT, asking ATS about address suggestions.
138 */
139 S_CONNECT_RECV_ATS,
140
141 /**
142 * Received CONNECT from other peer, got an address, checking with blacklist.
143 */
144 S_CONNECT_RECV_BLACKLIST,
145
146 /**
147 * CONNECT request from other peer was SESSION_ACK'ed, waiting for
148 * SESSION_ACK.
149 */
150 S_CONNECT_RECV_ACK,
151
152 /**
153 * Got our CONNECT_ACK/SESSION_ACK, connection is up.
154 */
155 S_CONNECTED,
156
157 /**
158 * Connection got into trouble, rest of the system still believes
159 * it to be up, but we're getting a new address from ATS.
160 */
161 S_RECONNECT_ATS,
162
163 /**
164 * Connection got into trouble, rest of the system still believes
165 * it to be up; we are checking the new address against the blacklist.
166 */
167 S_RECONNECT_BLACKLIST,
168
169 /**
170 * Sent CONNECT over new address (either by ATS telling us to switch
171 * addresses or from RECONNECT_ATS); if this fails, we need to tell
172 * the rest of the system about a disconnect.
173 */
174 S_RECONNECT_SENT,
175
176 /**
177 * We have some primary connection, but ATS suggested we switch
178 * to some alternative; we're now checking the alternative against
179 * the blacklist.
180 */
181 S_CONNECTED_SWITCHING_BLACKLIST,
182
183 /**
184 * We have some primary connection, but ATS suggested we switch
185 * to some alternative; we now sent a CONNECT message for the
186 * alternative session to the other peer and waiting for a
187 * CONNECT_ACK to make this our primary connection.
188 */
189 S_CONNECTED_SWITCHING_CONNECT_SENT,
190
191 /**
192 * Disconnect in progress (we're sending the DISCONNECT message to the
193 * other peer; after that is finished, the state will be cleaned up).
194 */
195 S_DISCONNECT,
196
197 /**
198 * We're finished with the disconnect; and are cleaning up the state
199 * now! We put the struct into this state when we are really in the
200 * task that calls 'free' on it and are about to remove the record
201 * from the map. We should never find a 'struct NeighbourMapEntry'
202 * in this state in the map. Accessing a 'struct NeighbourMapEntry'
203 * in this state virtually always means using memory that has been
204 * freed (the exception being the cleanup code in #free_neighbour()).
205 */
206 S_DISCONNECT_FINISHED
207};
208
209
210
211/**
48 * Function called by the transport for each received message. 212 * Function called by the transport for each received message.
49 * 213 *
50 * @param cls closure 214 * @param cls closure
@@ -119,19 +283,39 @@ typedef void (*GNUNET_TRANSPORT_AddressToStringCallback) (void *cls,
119 283
120 284
121/** 285/**
122 * Function to call with a binary format of an address 286 * Function to call with information about a peer
123 * 287 *
124 * @param cls closure 288 * @param cls closure
125 * @param peer peer this update is about (never NULL) 289 * @param peer peer this update is about,
290 * NULL if this is the final last callback for a iteration operation
126 * @param address address, NULL for disconnect notification in monitor mode 291 * @param address address, NULL for disconnect notification in monitor mode
292 * @param state current state this peer is in
293 * @param state_timeout timeout for the current state of the peer
127 */ 294 */
128typedef void (*GNUNET_TRANSPORT_PeerIterateCallback) (void *cls, 295typedef void (*GNUNET_TRANSPORT_PeerIterateCallback) (void *cls,
129 const struct 296 const struct GNUNET_PeerIdentity *peer,
130 GNUNET_PeerIdentity * 297 const struct GNUNET_HELLO_Address *address,
131 peer, 298 enum GNUNET_TRANSPORT_PeerState state,
132 const struct 299 struct GNUNET_TIME_Absolute state_timeout);
133 GNUNET_HELLO_Address * 300
134 address); 301
302/**
303 * Function to call with validation information about a peer
304 *
305 * @param cls closure
306 * @param peer peer this update is about,
307 * NULL if this is the final last callback for a iteration operation
308 * @param address address, NULL for disconnect notification in monitor mode
309 * @param valid_until when does this address expire
310 * @param next_validation time of the next validation operation
311 *
312 */
313typedef void (*GNUNET_TRANSPORT_ValidationIterateCallback) (void *cls,
314 const struct GNUNET_PeerIdentity *peer,
315 const struct GNUNET_HELLO_Address *address,
316 struct GNUNET_TIME_Absolute valid_until,
317 struct GNUNET_TIME_Absolute next_validation);
318
135 319
136 320
137/** 321/**
@@ -401,46 +585,84 @@ GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle
401void 585void
402GNUNET_TRANSPORT_address_to_string_cancel (struct 586GNUNET_TRANSPORT_address_to_string_cancel (struct
403 GNUNET_TRANSPORT_AddressToStringContext 587 GNUNET_TRANSPORT_AddressToStringContext
404 *alc); 588 *pic);
405 589
406 590
407/** 591/**
408 * Return all the known addresses for a specific peer or all peers. 592 * Return information about a specific peer or all peers currently known to
409 * Returns continuously all address if one_shot is set to GNUNET_NO 593 * transport service once or in monitoring mode. To obtain information about
594 * a specific peer, a peer identity can be passed. To obtain information about
595 * all peers currently known to transport service, NULL can be passed as peer
596 * identity.
410 * 597 *
411 * CHANGE: Returns the address(es) that we are currently using for this 598 * For each peer, the callback is called with information about the address used
412 * peer. Upon completion, the 'AddressLookUpCallback' is called one more 599 * to communicate with this peer, the state this peer is currently in and the
413 * time with 'NULL' for the address and the peer. After this, the operation must no 600 * the current timeout for this state.
414 * longer be explicitly cancelled. 601 *
602 * Upon completion, the 'GNUNET_TRANSPORT_PeerIterateCallback' is called one
603 * more time with 'NULL'. After this, the operation must no longer be
604 * explicitly canceled.
415 * 605 *
416 * @param cfg configuration to use 606 * @param cfg configuration to use
417 * @param peer peer identity to look up the addresses of, CHANGE: allow NULL for all (connected) peers 607 * @param peer a specific peer identity to obtain information for,
608 * NULL for all peers
418 * @param one_shot GNUNET_YES to return the current state and then end (with NULL+NULL), 609 * @param one_shot GNUNET_YES to return the current state and then end (with NULL+NULL),
419 * GNUNET_NO to monitor the set of addresses used (continuously, must be explicitly canceled, NOT implemented yet!) 610 * GNUNET_NO to monitor peers continuously
420 * @param timeout how long is the lookup allowed to take at most 611 * @param timeout how long is the lookup allowed to take at most
421 * @param peer_address_callback function to call with the results 612 * @param peer_address_callback function to call with the results
422 * @param peer_address_callback_cls closure for peer_address_callback 613 * @param peer_address_callback_cls closure for peer_address_callback
423 */ 614 */
424struct GNUNET_TRANSPORT_PeerIterateContext * 615struct GNUNET_TRANSPORT_PeerMonitoringContext *
425GNUNET_TRANSPORT_peer_get_active_addresses (const struct 616GNUNET_TRANSPORT_monitor_peers (const struct
426 GNUNET_CONFIGURATION_Handle *cfg, 617 GNUNET_CONFIGURATION_Handle *cfg,
427 const struct GNUNET_PeerIdentity 618 const struct GNUNET_PeerIdentity *peer,
428 *peer, int one_shot, 619 int one_shot,
429 struct GNUNET_TIME_Relative timeout, 620 struct GNUNET_TIME_Relative timeout,
430 GNUNET_TRANSPORT_PeerIterateCallback 621 GNUNET_TRANSPORT_PeerIterateCallback peer_callback,
431 peer_address_callback, 622 void *peer_callback_cls);
432 void *peer_address_callback_cls);
433 623
434 624
435/** 625/**
436 * Cancel request for peer lookup. 626 * Cancel request to monitor peers
437 * 627 *
438 * @param alc handle for the request to cancel 628 * @param pic handle for the request to cancel
439 */ 629 */
440void 630void
441GNUNET_TRANSPORT_peer_get_active_addresses_cancel (struct 631GNUNET_TRANSPORT_monitor_peers_cancel (struct GNUNET_TRANSPORT_PeerMonitoringContext *pic);
442 GNUNET_TRANSPORT_PeerIterateContext 632
443 *alc); 633
634
635/**
636 * Return information about pending address validation operations for a specific
637 * or all peers
638 *
639 * @param cfg configuration to use
640 * @param peer a specific peer identity to obtain validation entries for,
641 * NULL for all peers
642 * @param one_shot GNUNET_YES to return all entries and then end (with NULL+NULL),
643 * GNUNET_NO to monitor validation entries continuously
644 * @param timeout how long is the lookup allowed to take at most
645 * @param validation_callback function to call with the results
646 * @param validation_callback_cls closure for peer_address_callback
647 */
648struct GNUNET_TRANSPORT_ValidationMonitoringContext *
649GNUNET_TRANSPORT_monitor_validation_entries (const struct
650 GNUNET_CONFIGURATION_Handle *cfg,
651 const struct GNUNET_PeerIdentity *peer,
652 int one_shot,
653 struct GNUNET_TIME_Relative timeout,
654 GNUNET_TRANSPORT_ValidationIterateCallback validation_callback,
655 void *validation_callback_cls);
656
657
658/**
659 * Return information about all current pending validation operations
660 *
661 * @param vic handle for the request to cancel
662 */
663void
664GNUNET_TRANSPORT_monitor_validation_entries_cancel (struct GNUNET_TRANSPORT_ValidationMonitoringContext *vic);
665
444 666
445 667
446/** 668/**