diff options
Diffstat (limited to 'src/include/gnunet_transport_service.h')
-rw-r--r-- | src/include/gnunet_transport_service.h | 708 |
1 files changed, 0 insertions, 708 deletions
diff --git a/src/include/gnunet_transport_service.h b/src/include/gnunet_transport_service.h deleted file mode 100644 index 459efc506..000000000 --- a/src/include/gnunet_transport_service.h +++ /dev/null | |||
@@ -1,708 +0,0 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet. | ||
3 | Copyright (C) 2009-2016 GNUnet e.V. | ||
4 | |||
5 | GNUnet is free software: you can redistribute it and/or modify it | ||
6 | under the terms of the GNU Affero General Public License as published | ||
7 | by the Free Software Foundation, either version 3 of the License, | ||
8 | or (at your 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 | Affero General Public License for more details. | ||
14 | |||
15 | You should have received a copy of the GNU Affero General Public License | ||
16 | along with this program. If not, see <http://www.gnu.org/licenses/>. | ||
17 | |||
18 | SPDX-License-Identifier: AGPL3.0-or-later | ||
19 | */ | ||
20 | |||
21 | /** | ||
22 | * @author Christian Grothoff | ||
23 | * | ||
24 | * @file | ||
25 | * Low-level P2P IO | ||
26 | * | ||
27 | * @defgroup transport Transport service | ||
28 | * Low-level P2P IO | ||
29 | * | ||
30 | * @see [Documentation](https://gnunet.org/transport-service) | ||
31 | * | ||
32 | * @{ | ||
33 | */ | ||
34 | |||
35 | #ifndef GNUNET_TRANSPORT_SERVICE_H | ||
36 | #define GNUNET_TRANSPORT_SERVICE_H | ||
37 | |||
38 | #ifdef __cplusplus | ||
39 | extern "C" { | ||
40 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
41 | } | ||
42 | #endif | ||
43 | #endif | ||
44 | |||
45 | #include "gnunet_util_lib.h" | ||
46 | #include "gnunet_ats_service.h" | ||
47 | |||
48 | /** | ||
49 | * Version number of the transport API. | ||
50 | */ | ||
51 | #define GNUNET_TRANSPORT_VERSION 0x00000003 | ||
52 | |||
53 | |||
54 | /* *************************** HELLO *************************** */ | ||
55 | |||
56 | /** | ||
57 | * Handle for a #GNUNET_TRANSPORT_offer_hello operation | ||
58 | */ | ||
59 | struct GNUNET_TRANSPORT_OfferHelloHandle; | ||
60 | |||
61 | |||
62 | /** | ||
63 | * Offer the transport service the HELLO of another peer. Note that | ||
64 | * the transport service may just ignore this message if the HELLO is | ||
65 | * malformed or useless due to our local configuration. | ||
66 | * | ||
67 | * @param cfg configuration | ||
68 | * @param hello the hello message | ||
69 | * @param cont continuation to call when HELLO has been sent, | ||
70 | * tc reason #GNUNET_SCHEDULER_REASON_TIMEOUT for fail | ||
71 | * tc reasong #GNUNET_SCHEDULER_REASON_READ_READY for success | ||
72 | * @param cont_cls closure for @a cont | ||
73 | * @return a `struct GNUNET_TRANSPORT_OfferHelloHandle` handle or NULL on | ||
74 | * failure, in case of failure @a cont will not be called | ||
75 | * | ||
76 | */ | ||
77 | struct GNUNET_TRANSPORT_OfferHelloHandle * | ||
78 | GNUNET_TRANSPORT_offer_hello (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
79 | const struct GNUNET_MessageHeader *hello, | ||
80 | GNUNET_SCHEDULER_TaskCallback cont, | ||
81 | void *cont_cls); | ||
82 | |||
83 | |||
84 | /** | ||
85 | * Cancel the request to transport to offer the HELLO message | ||
86 | * | ||
87 | * @param ohh the `struct GNUNET_TRANSPORT_OfferHelloHandle` to cancel | ||
88 | */ | ||
89 | void | ||
90 | GNUNET_TRANSPORT_offer_hello_cancel ( | ||
91 | struct GNUNET_TRANSPORT_OfferHelloHandle *ohh); | ||
92 | |||
93 | |||
94 | /* *********************** Address to String ******************* */ | ||
95 | |||
96 | /** | ||
97 | * Handle to cancel a pending address lookup. | ||
98 | */ | ||
99 | struct GNUNET_TRANSPORT_AddressToStringContext; | ||
100 | |||
101 | |||
102 | /** | ||
103 | * Function to call with a textual representation of an address. This | ||
104 | * function will be called several times with different possible | ||
105 | * textual representations, and a last time with @a address being NULL | ||
106 | * to signal the end of the iteration. Note that @a address NULL | ||
107 | * always is the last call, regardless of the value in @a res. | ||
108 | * | ||
109 | * @param cls closure | ||
110 | * @param address NULL on end of iteration, | ||
111 | * otherwise 0-terminated printable UTF-8 string, | ||
112 | * in particular an empty string if @a res is #GNUNET_NO | ||
113 | * @param res result of the address to string conversion: | ||
114 | * if #GNUNET_OK: conversion successful | ||
115 | * if #GNUNET_NO: address was invalid (or not supported) | ||
116 | * if #GNUNET_SYSERR: communication error (IPC error) | ||
117 | */ | ||
118 | typedef void | ||
119 | (*GNUNET_TRANSPORT_AddressToStringCallback) (void *cls, | ||
120 | const char *address, | ||
121 | int res); | ||
122 | |||
123 | |||
124 | /** | ||
125 | * Convert a binary address into a human readable address. | ||
126 | * | ||
127 | * @param cfg configuration to use | ||
128 | * @param address address to convert (binary format) | ||
129 | * @param numeric should (IP) addresses be displayed in numeric form | ||
130 | * (otherwise do reverse DNS lookup) | ||
131 | * @param timeout how long is the lookup allowed to take at most | ||
132 | * @param aluc function to call with the results | ||
133 | * @param aluc_cls closure for @a aluc | ||
134 | * @return handle to cancel the operation, NULL on error | ||
135 | */ | ||
136 | struct GNUNET_TRANSPORT_AddressToStringContext * | ||
137 | GNUNET_TRANSPORT_address_to_string ( | ||
138 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
139 | const struct GNUNET_HELLO_Address *address, | ||
140 | int numeric, | ||
141 | struct GNUNET_TIME_Relative timeout, | ||
142 | GNUNET_TRANSPORT_AddressToStringCallback aluc, | ||
143 | void *aluc_cls); | ||
144 | |||
145 | |||
146 | /** | ||
147 | * Cancel request for address conversion. | ||
148 | * | ||
149 | * @param alc the context handle | ||
150 | */ | ||
151 | void | ||
152 | GNUNET_TRANSPORT_address_to_string_cancel ( | ||
153 | struct GNUNET_TRANSPORT_AddressToStringContext *alc); | ||
154 | |||
155 | |||
156 | /* *********************** Monitoring ************************** */ | ||
157 | |||
158 | |||
159 | /** | ||
160 | * Possible state of a neighbour. Initially, we are | ||
161 | * #GNUNET_TRANSPORT_PS_NOT_CONNECTED. | ||
162 | * | ||
163 | * Then, there are two main paths. If we receive a SYN message, we give | ||
164 | * the inbound address to ATS. After the check we ask ATS for a suggestion | ||
165 | * (#GNUNET_TRANSPORT_PS_CONNECT_RECV_ATS). If ATS makes a suggestion, we | ||
166 | * send our SYN_ACK and go to #GNUNET_TRANSPORT_PS_CONNECT_RECV_ACK. | ||
167 | * If we receive a ACK, we go to #GNUNET_TRANSPORT_PS_CONNECTED | ||
168 | * (and notify everyone about the new connection). If the operation times out, | ||
169 | * we go to #GNUNET_TRANSPORT_PS_DISCONNECT. | ||
170 | * | ||
171 | * The other case is where we transmit a SYN message first. We | ||
172 | * start with #GNUNET_TRANSPORT_PS_INIT_ATS. If we get an address, we send | ||
173 | * the SYN message and go to state #GNUNET_TRANSPORT_PS_CONNECT_SENT. | ||
174 | * Once we receive a SYN_ACK, we go to #GNUNET_TRANSPORT_PS_CONNECTED | ||
175 | * (and notify everyone about the new connection and send | ||
176 | * back a ACK). If the operation times out, we go to | ||
177 | * #GNUNET_TRANSPORT_PS_DISCONNECT. | ||
178 | * | ||
179 | * If the session is in trouble (i.e. transport-level disconnect or | ||
180 | * timeout), we go to #GNUNET_TRANSPORT_PS_RECONNECT_ATS where we ask ATS for a | ||
181 | * new address (we don't notify anyone about the disconnect yet). Once we have | ||
182 | * a new address, we enter #GNUNET_TRANSPORT_PS_RECONNECT_SENT and send a SYN | ||
183 | * message. If we receive a SYN_ACK, we go to #GNUNET_TRANSPORT_PS_CONNECTED | ||
184 | * and nobody noticed that we had trouble; we also send a ACK at this time just | ||
185 | * in case. If the operation times out, we go to | ||
186 | * #GNUNET_TRANSPORT_PS_DISCONNECT (and notify everyone about the lost | ||
187 | * connection). | ||
188 | * | ||
189 | * If ATS decides to switch addresses while we have a normal | ||
190 | * connection, we go to #GNUNET_TRANSPORT_PS_CONNECTED_SWITCHING_SYN_SENT | ||
191 | * and send a SESSION_CONNECT. If we get a ACK back, we switch the | ||
192 | * primary connection to the suggested alternative from ATS, go back | ||
193 | * to #GNUNET_TRANSPORT_PS_CONNECTED and send a ACK to the other peer just to be | ||
194 | * sure. If the operation times out | ||
195 | * we go to #GNUNET_TRANSPORT_PS_CONNECTED (and notify ATS that the given | ||
196 | * alternative address is "invalid"). | ||
197 | * | ||
198 | * Once a session is in #GNUNET_TRANSPORT_PS_DISCONNECT, it is cleaned up and | ||
199 | * then goes to (#GNUNET_TRANSPORT_PS_DISCONNECT_FINISHED). If we receive an | ||
200 | * explicit disconnect request, we can go from any state to | ||
201 | * #GNUNET_TRANSPORT_PS_DISCONNECT, possibly after generating disconnect | ||
202 | * notifications. | ||
203 | * | ||
204 | * Note that it is quite possible that while we are in any of these | ||
205 | * states, we could receive a 'SYN' request from the other peer. | ||
206 | * We then enter a 'weird' state where we pursue our own primary state | ||
207 | * machine (as described above), but with the 'send_connect_ack' flag | ||
208 | * set to 1. If our state machine allows us to send a 'SYN_ACK' | ||
209 | * (because we have an acceptable address), we send the 'SYN_ACK' | ||
210 | * and set the 'send_connect_ack' to 2. If we then receive a | ||
211 | * 'ACK', we go to #GNUNET_TRANSPORT_PS_CONNECTED (and reset 'send_connect_ack' | ||
212 | * to 0). | ||
213 | * | ||
214 | */ | ||
215 | enum GNUNET_TRANSPORT_PeerState | ||
216 | { | ||
217 | /** | ||
218 | * Fresh peer or completely disconnected | ||
219 | */ | ||
220 | GNUNET_TRANSPORT_PS_NOT_CONNECTED = 0, | ||
221 | |||
222 | /** | ||
223 | * Asked to initiate connection, trying to get address from ATS | ||
224 | */ | ||
225 | GNUNET_TRANSPORT_PS_INIT_ATS, | ||
226 | |||
227 | /** | ||
228 | * Sent SYN message to other peer, waiting for SYN_ACK | ||
229 | */ | ||
230 | GNUNET_TRANSPORT_PS_SYN_SENT, | ||
231 | |||
232 | /** | ||
233 | * Received a SYN, asking ATS about address suggestions. | ||
234 | */ | ||
235 | GNUNET_TRANSPORT_PS_SYN_RECV_ATS, | ||
236 | |||
237 | /** | ||
238 | * SYN request from other peer was SYN_ACK'ed, waiting for ACK. | ||
239 | */ | ||
240 | GNUNET_TRANSPORT_PS_SYN_RECV_ACK, | ||
241 | |||
242 | /** | ||
243 | * Got our SYN_ACK/ACK, connection is up. | ||
244 | */ | ||
245 | GNUNET_TRANSPORT_PS_CONNECTED, | ||
246 | |||
247 | /** | ||
248 | * Connection got into trouble, rest of the system still believes | ||
249 | * it to be up, but we're getting a new address from ATS. | ||
250 | */ | ||
251 | GNUNET_TRANSPORT_PS_RECONNECT_ATS, | ||
252 | |||
253 | /** | ||
254 | * Sent SYN over new address (either by ATS telling us to switch | ||
255 | * addresses or from RECONNECT_ATS); if this fails, we need to tell | ||
256 | * the rest of the system about a disconnect. | ||
257 | */ | ||
258 | GNUNET_TRANSPORT_PS_RECONNECT_SENT, | ||
259 | |||
260 | /** | ||
261 | * We have some primary connection, but ATS suggested we switch | ||
262 | * to some alternative; we now sent a SYN message for the | ||
263 | * alternative session to the other peer and waiting for a | ||
264 | * SYN_ACK to make this our primary connection. | ||
265 | */ | ||
266 | GNUNET_TRANSPORT_PS_SWITCH_SYN_SENT, | ||
267 | |||
268 | /** | ||
269 | * Disconnect in progress (we're sending the DISCONNECT message to the | ||
270 | * other peer; after that is finished, the state will be cleaned up). | ||
271 | */ | ||
272 | GNUNET_TRANSPORT_PS_DISCONNECT, | ||
273 | |||
274 | /** | ||
275 | * We're finished with the disconnect; and are cleaning up the state | ||
276 | * now! We put the struct into this state when we are really in the | ||
277 | * task that calls 'free' on it and are about to remove the record | ||
278 | * from the map. We should never find a 'struct NeighbourMapEntry' | ||
279 | * in this state in the map. Accessing a 'struct NeighbourMapEntry' | ||
280 | * in this state virtually always means using memory that has been | ||
281 | * freed (the exception being the cleanup code in #free_neighbour()). | ||
282 | */ | ||
283 | GNUNET_TRANSPORT_PS_DISCONNECT_FINISHED | ||
284 | }; | ||
285 | |||
286 | |||
287 | /** | ||
288 | * Convert a transport state to a human readable string. | ||
289 | * | ||
290 | * @param state the state | ||
291 | */ | ||
292 | const char * | ||
293 | GNUNET_TRANSPORT_ps2s (enum GNUNET_TRANSPORT_PeerState state); | ||
294 | |||
295 | |||
296 | /** | ||
297 | * Check if a state is defined as connected | ||
298 | * | ||
299 | * @param state the state value | ||
300 | * @return #GNUNET_YES or #GNUNET_NO | ||
301 | */ | ||
302 | int | ||
303 | GNUNET_TRANSPORT_is_connected (enum GNUNET_TRANSPORT_PeerState state); | ||
304 | |||
305 | |||
306 | /** | ||
307 | * Handle for a #GNUNET_TRANSPORT_monitor_peers operation. | ||
308 | */ | ||
309 | struct GNUNET_TRANSPORT_PeerMonitoringContext; | ||
310 | |||
311 | |||
312 | /** | ||
313 | * Function to call with information about a peer | ||
314 | * | ||
315 | * If one_shot was set to #GNUNET_YES to iterate over all peers once, | ||
316 | * a final call with NULL for peer and address will follow when done. | ||
317 | * In this case state and timeout do not contain valid values. | ||
318 | * | ||
319 | * The #GNUNET_TRANSPORT_monitor_peers_cancel() call MUST not be called from | ||
320 | * within this function! | ||
321 | * | ||
322 | * | ||
323 | * @param cls closure | ||
324 | * @param peer peer this update is about, | ||
325 | * NULL if this is the final last callback for a iteration operation | ||
326 | * @param address address, NULL if this is the final callback for iteration op | ||
327 | * @param state current state this peer is in | ||
328 | * @param state_timeout timeout for the current state of the peer | ||
329 | */ | ||
330 | typedef void | ||
331 | (*GNUNET_TRANSPORT_PeerIterateCallback) ( | ||
332 | void *cls, | ||
333 | const struct GNUNET_PeerIdentity *peer, | ||
334 | const struct GNUNET_HELLO_Address *address, | ||
335 | enum GNUNET_TRANSPORT_PeerState state, | ||
336 | struct GNUNET_TIME_Absolute state_timeout); | ||
337 | |||
338 | |||
339 | /** | ||
340 | * Return information about a specific peer or all peers currently known to | ||
341 | * transport service once or in monitoring mode. To obtain information about | ||
342 | * a specific peer, a peer identity can be passed. To obtain information about | ||
343 | * all peers currently known to transport service, NULL can be passed as peer | ||
344 | * identity. | ||
345 | * | ||
346 | * For each peer, the callback is called with information about the address used | ||
347 | * to communicate with this peer, the state this peer is currently in and the | ||
348 | * the current timeout for this state. | ||
349 | * | ||
350 | * Upon completion, the #GNUNET_TRANSPORT_PeerIterateCallback is called one | ||
351 | * more time with `NULL`. After this, the operation must no longer be | ||
352 | * explicitly canceled. | ||
353 | * | ||
354 | * The #GNUNET_TRANSPORT_monitor_peers_cancel call MUST not be called in the | ||
355 | * the peer_callback! | ||
356 | * | ||
357 | * @param cfg configuration to use | ||
358 | * @param peer a specific peer identity to obtain information for, | ||
359 | * NULL for all peers | ||
360 | * @param one_shot #GNUNET_YES to return the current state and then end (with | ||
361 | * NULL+NULL), #GNUNET_NO to monitor peers continuously | ||
362 | * @param peer_callback function to call with the results | ||
363 | * @param peer_callback_cls closure for @a peer_callback | ||
364 | */ | ||
365 | struct GNUNET_TRANSPORT_PeerMonitoringContext * | ||
366 | GNUNET_TRANSPORT_monitor_peers ( | ||
367 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
368 | const struct GNUNET_PeerIdentity *peer, | ||
369 | int one_shot, | ||
370 | GNUNET_TRANSPORT_PeerIterateCallback peer_callback, | ||
371 | void *peer_callback_cls); | ||
372 | |||
373 | |||
374 | /** | ||
375 | * Cancel request to monitor peers | ||
376 | * | ||
377 | * @param pic handle for the request to cancel | ||
378 | */ | ||
379 | void | ||
380 | GNUNET_TRANSPORT_monitor_peers_cancel ( | ||
381 | struct GNUNET_TRANSPORT_PeerMonitoringContext *pic); | ||
382 | |||
383 | |||
384 | /* *********************** Blacklisting ************************ */ | ||
385 | |||
386 | /** | ||
387 | * Handle for blacklisting peers. | ||
388 | */ | ||
389 | struct GNUNET_TRANSPORT_Blacklist; | ||
390 | |||
391 | |||
392 | /** | ||
393 | * Function that decides if a connection is acceptable or not. | ||
394 | * | ||
395 | * @param cls closure | ||
396 | * @param pid peer to approve or disapproave | ||
397 | * @return #GNUNET_OK if the connection is allowed, #GNUNET_SYSERR if not | ||
398 | */ | ||
399 | typedef int | ||
400 | (*GNUNET_TRANSPORT_BlacklistCallback) ( | ||
401 | void *cls, | ||
402 | const struct GNUNET_PeerIdentity *pid); | ||
403 | |||
404 | |||
405 | /** | ||
406 | * Install a blacklist callback. The service will be queried for all | ||
407 | * existing connections as well as any fresh connections to check if | ||
408 | * they are permitted. If the blacklisting callback is unregistered, | ||
409 | * all hosts that were denied in the past will automatically be | ||
410 | * whitelisted again. Cancelling the blacklist handle is also the | ||
411 | * only way to re-enable connections from peers that were previously | ||
412 | * blacklisted. | ||
413 | * | ||
414 | * @param cfg configuration to use | ||
415 | * @param cb callback to invoke to check if connections are allowed | ||
416 | * @param cb_cls closure for @a cb | ||
417 | * @return NULL on error, otherwise handle for cancellation | ||
418 | */ | ||
419 | struct GNUNET_TRANSPORT_Blacklist * | ||
420 | GNUNET_TRANSPORT_blacklist (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
421 | GNUNET_TRANSPORT_BlacklistCallback cb, | ||
422 | void *cb_cls); | ||
423 | |||
424 | |||
425 | /** | ||
426 | * Abort the blacklist. Note that this function is the only way for | ||
427 | * removing a peer from the blacklist. | ||
428 | * | ||
429 | * @param br handle of the request that is to be cancelled | ||
430 | */ | ||
431 | void | ||
432 | GNUNET_TRANSPORT_blacklist_cancel (struct GNUNET_TRANSPORT_Blacklist *br); | ||
433 | |||
434 | |||
435 | /** | ||
436 | * Handle for a plugin session state monitor. | ||
437 | */ | ||
438 | struct GNUNET_TRANSPORT_PluginMonitor; | ||
439 | |||
440 | /** | ||
441 | * Abstract representation of a plugin's session. | ||
442 | * Corresponds to the `struct GNUNET_ATS_Session` within the TRANSPORT service. | ||
443 | */ | ||
444 | struct GNUNET_TRANSPORT_PluginSession; | ||
445 | |||
446 | |||
447 | /** | ||
448 | * Possible states of a session in a plugin. | ||
449 | */ | ||
450 | enum GNUNET_TRANSPORT_SessionState | ||
451 | { | ||
452 | /** | ||
453 | * The session was created (first call for each session object). | ||
454 | */ | ||
455 | GNUNET_TRANSPORT_SS_INIT, | ||
456 | |||
457 | /** | ||
458 | * Initial session handshake is in progress. | ||
459 | */ | ||
460 | GNUNET_TRANSPORT_SS_HANDSHAKE, | ||
461 | |||
462 | /** | ||
463 | * Session is fully UP. | ||
464 | */ | ||
465 | GNUNET_TRANSPORT_SS_UP, | ||
466 | |||
467 | /** | ||
468 | * This is just an update about the session, | ||
469 | * the state did not change. | ||
470 | */ | ||
471 | GNUNET_TRANSPORT_SS_UPDATE, | ||
472 | |||
473 | /** | ||
474 | * Session is being torn down and about to disappear. | ||
475 | * Last call for each session object. | ||
476 | */ | ||
477 | GNUNET_TRANSPORT_SS_DONE | ||
478 | }; | ||
479 | |||
480 | |||
481 | /** | ||
482 | * Information about a plugin's session. | ||
483 | */ | ||
484 | struct GNUNET_TRANSPORT_SessionInfo | ||
485 | { | ||
486 | /** | ||
487 | * New state of the session. | ||
488 | */ | ||
489 | enum GNUNET_TRANSPORT_SessionState state; | ||
490 | |||
491 | /** | ||
492 | * #GNUNET_YES if this is an inbound connection, | ||
493 | * #GNUNET_NO if this is an outbound connection, | ||
494 | * #GNUNET_SYSERR if connections of this plugin | ||
495 | * are so fundamentally bidirectional | ||
496 | * that they have no 'initiator' | ||
497 | */ | ||
498 | int is_inbound; | ||
499 | |||
500 | /** | ||
501 | * Number of messages pending transmission for this session. | ||
502 | */ | ||
503 | uint32_t num_msg_pending; | ||
504 | |||
505 | /** | ||
506 | * Number of bytes pending transmission for this session. | ||
507 | */ | ||
508 | uint32_t num_bytes_pending; | ||
509 | |||
510 | /** | ||
511 | * Until when does this plugin refuse to receive to manage | ||
512 | * staying within the inbound quota? ZERO if receive is | ||
513 | * active. | ||
514 | */ | ||
515 | struct GNUNET_TIME_Absolute receive_delay; | ||
516 | |||
517 | /** | ||
518 | * At what time will this session timeout (unless activity | ||
519 | * happens)? | ||
520 | */ | ||
521 | struct GNUNET_TIME_Absolute session_timeout; | ||
522 | |||
523 | /** | ||
524 | * Address used by the session. Can be NULL if none is available. | ||
525 | */ | ||
526 | const struct GNUNET_HELLO_Address *address; | ||
527 | }; | ||
528 | |||
529 | |||
530 | /** | ||
531 | * Function called by the plugin with information about the | ||
532 | * current sessions managed by the plugin (for monitoring). | ||
533 | * | ||
534 | * @param cls closure | ||
535 | * @param session session handle this information is about, | ||
536 | * NULL to indicate that we are "in sync" (initial | ||
537 | * iteration complete) | ||
538 | * @param session_ctx storage location where the application | ||
539 | * can store data; will point to NULL on #GNUNET_TRANSPORT_SS_INIT, | ||
540 | * and must be reset to NULL on #GNUNET_TRANSPORT_SS_DONE | ||
541 | * @param info information about the state of the session, | ||
542 | * NULL if @a session is also NULL and we are | ||
543 | * merely signalling that the initial iteration is over; | ||
544 | * NULL with @a session being non-NULL if the monitor | ||
545 | * was being cancelled while sessions were active | ||
546 | */ | ||
547 | typedef void | ||
548 | (*GNUNET_TRANSPORT_SessionMonitorCallback) ( | ||
549 | void *cls, | ||
550 | struct GNUNET_TRANSPORT_PluginSession *session, | ||
551 | void **session_ctx, | ||
552 | const struct GNUNET_TRANSPORT_SessionInfo *info); | ||
553 | |||
554 | |||
555 | /** | ||
556 | * Install a plugin session state monitor callback. The callback | ||
557 | * will be notified whenever the session changes. | ||
558 | * | ||
559 | * @param cfg configuration to use | ||
560 | * @param cb callback to invoke on events | ||
561 | * @param cb_cls closure for @a cb | ||
562 | * @return NULL on error, otherwise handle for cancellation | ||
563 | */ | ||
564 | struct GNUNET_TRANSPORT_PluginMonitor * | ||
565 | GNUNET_TRANSPORT_monitor_plugins (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
566 | GNUNET_TRANSPORT_SessionMonitorCallback cb, | ||
567 | void *cb_cls); | ||
568 | |||
569 | |||
570 | /** | ||
571 | * Cancel monitoring the plugin session state. The callback will be | ||
572 | * called once for each session that is up with the "info" argument | ||
573 | * being NULL (this is just to enable client-side cleanup). | ||
574 | * | ||
575 | * @param pm handle of the request that is to be cancelled | ||
576 | */ | ||
577 | void | ||
578 | GNUNET_TRANSPORT_monitor_plugins_cancel ( | ||
579 | struct GNUNET_TRANSPORT_PluginMonitor *pm); | ||
580 | |||
581 | |||
582 | /** | ||
583 | * Opaque handle to the service. | ||
584 | */ | ||
585 | struct GNUNET_TRANSPORT_CoreHandle; | ||
586 | |||
587 | |||
588 | /** | ||
589 | * Function called to notify transport users that another | ||
590 | * peer connected to us. | ||
591 | * | ||
592 | * @param cls closure | ||
593 | * @param peer the identity of the peer that connected; this | ||
594 | * pointer will remain valid until the disconnect, hence | ||
595 | * applications do not necessarily have to make a copy | ||
596 | * of the value if they only need it until disconnect | ||
597 | * @param mq message queue to use to transmit to @a peer | ||
598 | * @return closure to use in MQ handlers | ||
599 | */ | ||
600 | typedef void * | ||
601 | (*GNUNET_TRANSPORT_NotifyConnect) ( | ||
602 | void *cls, | ||
603 | const struct GNUNET_PeerIdentity *peer, | ||
604 | struct GNUNET_MQ_Handle *mq); | ||
605 | |||
606 | |||
607 | /** | ||
608 | * Function called to notify transport users that another peer | ||
609 | * disconnected from us. The message queue that was given to the | ||
610 | * connect notification will be destroyed and must not be used | ||
611 | * henceforth. | ||
612 | * | ||
613 | * @param cls closure from #GNUNET_TRANSPORT_core_connect | ||
614 | * @param peer the peer that disconnected | ||
615 | * @param handlers_cls closure of the handlers, was returned from the | ||
616 | * connect notification callback | ||
617 | */ | ||
618 | typedef void | ||
619 | (*GNUNET_TRANSPORT_NotifyDisconnect) ( | ||
620 | void *cls, | ||
621 | const struct GNUNET_PeerIdentity *peer, | ||
622 | void *handler_cls); | ||
623 | |||
624 | |||
625 | /** | ||
626 | * Function called if we have "excess" bandwidth to a peer. | ||
627 | * The notification will happen the first time we have excess | ||
628 | * bandwidth, and then only again after the client has performed | ||
629 | * some transmission to the peer. | ||
630 | * | ||
631 | * Excess bandwidth is defined as being allowed (by ATS) to send | ||
632 | * more data, and us reaching the limit of the capacity build-up | ||
633 | * (which, if we go past it, means we don't use available bandwidth). | ||
634 | * See also the "max carry" in `struct GNUNET_BANDWIDTH_Tracker`. | ||
635 | * | ||
636 | * @param cls the closure | ||
637 | * @param neighbour peer that we have excess bandwidth to | ||
638 | * @param handlers_cls closure of the handlers, was returned from the | ||
639 | * connect notification callback | ||
640 | */ | ||
641 | typedef void | ||
642 | (*GNUNET_TRANSPORT_NotifyExcessBandwidth) ( | ||
643 | void *cls, | ||
644 | const struct GNUNET_PeerIdentity *neighbour, | ||
645 | void *handlers_cls); | ||
646 | |||
647 | |||
648 | /** | ||
649 | * Connect to the transport service. Note that the connection may | ||
650 | * complete (or fail) asynchronously. | ||
651 | * | ||
652 | * @param cfg configuration to use | ||
653 | * @param self our own identity (API should check that it matches | ||
654 | * the identity found by transport), or NULL (no check) | ||
655 | * @param handlers array of message handlers; note that the | ||
656 | * closures provided will be ignored and replaced | ||
657 | * with the respective return value from @a nc | ||
658 | * @param handlers array with handlers to call when we receive messages, or NULL | ||
659 | * @param cls closure for the @a nc, @a nd and @a neb callbacks | ||
660 | * @param nc function to call on connect events, or NULL | ||
661 | * @param nd function to call on disconnect events, or NULL | ||
662 | * @param neb function to call if we have excess bandwidth to a peer, or NULL | ||
663 | * @return NULL on error | ||
664 | */ | ||
665 | struct GNUNET_TRANSPORT_CoreHandle * | ||
666 | GNUNET_TRANSPORT_core_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
667 | const struct GNUNET_PeerIdentity *self, | ||
668 | const struct GNUNET_MQ_MessageHandler *handlers, | ||
669 | void *cls, | ||
670 | GNUNET_TRANSPORT_NotifyConnect nc, | ||
671 | GNUNET_TRANSPORT_NotifyDisconnect nd, | ||
672 | GNUNET_TRANSPORT_NotifyExcessBandwidth neb); | ||
673 | |||
674 | |||
675 | /** | ||
676 | * Disconnect from the transport service. | ||
677 | * | ||
678 | * @param handle handle returned from connect | ||
679 | */ | ||
680 | void | ||
681 | GNUNET_TRANSPORT_core_disconnect (struct GNUNET_TRANSPORT_CoreHandle *handle); | ||
682 | |||
683 | |||
684 | /** | ||
685 | * Checks if a given peer is connected to us and get the message queue. | ||
686 | * | ||
687 | * @param handle connection to transport service | ||
688 | * @param peer the peer to check | ||
689 | * @return NULL if disconnected, otherwise message queue for @a peer | ||
690 | */ | ||
691 | struct GNUNET_MQ_Handle * | ||
692 | GNUNET_TRANSPORT_core_get_mq (struct GNUNET_TRANSPORT_CoreHandle *handle, | ||
693 | const struct GNUNET_PeerIdentity *peer); | ||
694 | |||
695 | |||
696 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
697 | { | ||
698 | #endif | ||
699 | #ifdef __cplusplus | ||
700 | } | ||
701 | #endif | ||
702 | |||
703 | /* ifndef GNUNET_TRANSPORT_SERVICE_H */ | ||
704 | #endif | ||
705 | |||
706 | /** @} */ /* end of group */ | ||
707 | |||
708 | /* end of gnunet_transport_service.h */ | ||