diff options
author | Martin Schanzenbach <schanzen@gnunet.org> | 2023-10-05 08:16:06 +0200 |
---|---|---|
committer | Martin Schanzenbach <schanzen@gnunet.org> | 2023-10-05 08:16:06 +0200 |
commit | 09f0c25760dfa32982e609e7cf4246bbeff401af (patch) | |
tree | 5e0695ceeb8ef794536905514fa72c5d432479e2 /src/include | |
parent | 614ed461b8a4c4fbf8cbdfb6b7f1a3f28a1ab8a9 (diff) | |
download | gnunet-09f0c25760dfa32982e609e7cf4246bbeff401af.tar.gz gnunet-09f0c25760dfa32982e609e7cf4246bbeff401af.zip |
Remove more traces of old transport
Diffstat (limited to 'src/include')
-rw-r--r-- | src/include/Makefile.am | 2 | ||||
-rw-r--r-- | src/include/gnunet_transport_plugin.h | 733 | ||||
-rw-r--r-- | src/include/gnunet_transport_service.h | 722 |
3 files changed, 0 insertions, 1457 deletions
diff --git a/src/include/Makefile.am b/src/include/Makefile.am index 7c1b59b3a..03983eaa0 100644 --- a/src/include/Makefile.am +++ b/src/include/Makefile.am | |||
@@ -119,12 +119,10 @@ gnunetinclude_HEADERS = \ | |||
119 | gnunet_testing_ng_lib.h \ | 119 | gnunet_testing_ng_lib.h \ |
120 | gnunet_testing_netjail_lib.h \ | 120 | gnunet_testing_netjail_lib.h \ |
121 | gnunet_time_lib.h \ | 121 | gnunet_time_lib.h \ |
122 | gnunet_transport_service.h \ | ||
123 | gnunet_transport_application_service.h \ | 122 | gnunet_transport_application_service.h \ |
124 | gnunet_transport_communication_service.h \ | 123 | gnunet_transport_communication_service.h \ |
125 | gnunet_transport_core_service.h \ | 124 | gnunet_transport_core_service.h \ |
126 | gnunet_transport_hello_service.h \ | 125 | gnunet_transport_hello_service.h \ |
127 | gnunet_transport_plugin.h \ | ||
128 | gnunet_transport_testing_ng_lib.h \ | 126 | gnunet_transport_testing_ng_lib.h \ |
129 | gnunet_tun_lib.h \ | 127 | gnunet_tun_lib.h \ |
130 | gnunet_uri_lib.h \ | 128 | gnunet_uri_lib.h \ |
diff --git a/src/include/gnunet_transport_plugin.h b/src/include/gnunet_transport_plugin.h deleted file mode 100644 index 0ab4a995c..000000000 --- a/src/include/gnunet_transport_plugin.h +++ /dev/null | |||
@@ -1,733 +0,0 @@ | |||
1 | /* | ||
2 | This file is part of GNUnet | ||
3 | Copyright (C) 2009-2014 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 | * @addtogroup Backbone | ||
23 | * @{ | ||
24 | * | ||
25 | * @author Christian Grothoff | ||
26 | * | ||
27 | * @file | ||
28 | * Transport service plugin API | ||
29 | * | ||
30 | * @defgroup transport-plugin Transport Service plugin API | ||
31 | * | ||
32 | * Specifies the struct that is given to the plugin's entry method and the other | ||
33 | * struct that must be returned. Note that the destructors of transport plugins | ||
34 | * will be given the value returned by the constructor and is expected to return | ||
35 | * a NULL pointer. | ||
36 | * | ||
37 | * @{ | ||
38 | */ | ||
39 | #ifndef PLUGIN_TRANSPORT_H | ||
40 | #define PLUGIN_TRANSPORT_H | ||
41 | |||
42 | |||
43 | #include "gnunet_configuration_lib.h" | ||
44 | #include "gnunet_scheduler_lib.h" | ||
45 | #include "gnunet_statistics_service.h" | ||
46 | #include "gnunet_transport_service.h" | ||
47 | #include "gnunet_ats_service.h" | ||
48 | |||
49 | #define TRANSPORT_SESSION_INBOUND_STRING "<inbound>" | ||
50 | |||
51 | /** | ||
52 | * Opaque pointer that plugins can use to distinguish specific | ||
53 | * connections to a given peer. Typically used by stateful plugins to | ||
54 | * allow the service to refer to specific streams instead of a more | ||
55 | * general notion of "some connection" to the given peer. This is | ||
56 | * useful since sometimes (e.g. for inbound TCP connections) a | ||
57 | * connection may not have an address that can be used for meaningful | ||
58 | * distinction between sessions to the same peer. | ||
59 | * | ||
60 | * Each 'struct GNUNET_ATS_Session' MUST start with the 'struct GNUNET_PeerIdentity' | ||
61 | * of the peer the session is for (which will be used for some error | ||
62 | * checking by the ATS code). | ||
63 | */ | ||
64 | struct GNUNET_ATS_Session; | ||
65 | |||
66 | |||
67 | /** | ||
68 | * Function that will be called whenever the plugin internally | ||
69 | * cleans up a session pointer and hence the service needs to | ||
70 | * discard all of those sessions as well. Plugins that do not | ||
71 | * use sessions can simply omit calling this function and always | ||
72 | * use NULL wherever a session pointer is needed. This function | ||
73 | * should be called BEFORE a potential "TransmitContinuation" | ||
74 | * from the "TransmitFunction". | ||
75 | * | ||
76 | * @param cls closure | ||
77 | * @param peer which peer was the session for | ||
78 | * @param session which session is being destroyed | ||
79 | */ | ||
80 | typedef void | ||
81 | (*GNUNET_TRANSPORT_SessionEnd) (void *cls, | ||
82 | const struct GNUNET_HELLO_Address *address, | ||
83 | struct GNUNET_ATS_Session *session); | ||
84 | |||
85 | |||
86 | /** | ||
87 | * Plugin tells transport service about a new inbound session | ||
88 | * | ||
89 | * @param cls unused | ||
90 | * @param address the address | ||
91 | * @param session the new session | ||
92 | * @param net network information | ||
93 | */ | ||
94 | typedef void | ||
95 | (*GNUNET_TRANSPORT_SessionStart) (void *cls, | ||
96 | const struct GNUNET_HELLO_Address *address, | ||
97 | struct GNUNET_ATS_Session *session, | ||
98 | enum GNUNET_NetworkType net); | ||
99 | |||
100 | |||
101 | /** | ||
102 | * Function called by the transport for each received message. | ||
103 | * This function should also be called with "NULL" for the | ||
104 | * message to signal that the other peer disconnected. | ||
105 | * | ||
106 | * @param cls closure | ||
107 | * @param peer (claimed) identity of the other peer | ||
108 | * @param message the message, NULL if we only care about | ||
109 | * learning about the delay until we should receive again | ||
110 | * @param session identifier used for this session (NULL for plugins | ||
111 | * that do not offer bi-directional communication to the sender | ||
112 | * using the same "connection") | ||
113 | * @param sender_address binary address of the sender (if we established the | ||
114 | * connection or are otherwise sure of it; should be NULL | ||
115 | * for inbound TCP/UDP connections since it it not clear | ||
116 | * that we could establish ourselves a connection to that | ||
117 | * IP address and get the same system) | ||
118 | * @param sender_address_len number of bytes in @a sender_address | ||
119 | * @return how long the plugin should wait until receiving more data; | ||
120 | * returning #GNUNET_TIME_UNIT_FOREVER_REL means that the | ||
121 | * connection should be closed | ||
122 | */ | ||
123 | typedef struct GNUNET_TIME_Relative | ||
124 | (*GNUNET_TRANSPORT_PluginReceiveCallback) (void *cls, | ||
125 | const struct | ||
126 | GNUNET_HELLO_Address *address, | ||
127 | struct GNUNET_ATS_Session *session, | ||
128 | const struct | ||
129 | GNUNET_MessageHeader *message); | ||
130 | |||
131 | |||
132 | /** | ||
133 | * Function that can be called by plugins to figure if an address is | ||
134 | * an loopback, LAN or WAN address. Ultimately invokes | ||
135 | * #GNUNET_ATS_address_get_type(). | ||
136 | * | ||
137 | * @param cls closure | ||
138 | * @param addr binary address | ||
139 | * @param addrlen length of the @a addr | ||
140 | * @return type of the network the address belongs to | ||
141 | */ | ||
142 | typedef enum GNUNET_NetworkType | ||
143 | (*GNUNET_TRANSPORT_AddressToType)(void *cls, | ||
144 | const struct sockaddr *addr, | ||
145 | size_t addrlen); | ||
146 | |||
147 | |||
148 | /** | ||
149 | * Function called when distance of an address changes. | ||
150 | * | ||
151 | * @param cls closure | ||
152 | * @param peer peer | ||
153 | * @param distance new distance | ||
154 | */ | ||
155 | typedef void | ||
156 | (*GNUNET_TRANSPORT_UpdateAddressDistance) (void *cls, | ||
157 | const struct | ||
158 | GNUNET_HELLO_Address *address, | ||
159 | uint32_t distance); | ||
160 | |||
161 | |||
162 | /** | ||
163 | * Function that will be called for each address the transport | ||
164 | * is aware that it might be reachable under. | ||
165 | * | ||
166 | * @param cls closure | ||
167 | * @param add_remove should the address added (#GNUNET_YES) or removed (#GNUNET_NO) from the | ||
168 | * set of valid addresses? | ||
169 | * @param address the address to add or remove | ||
170 | */ | ||
171 | typedef void | ||
172 | (*GNUNET_TRANSPORT_AddressNotification) (void *cls, | ||
173 | int add_remove, | ||
174 | const struct | ||
175 | GNUNET_HELLO_Address *address); | ||
176 | |||
177 | |||
178 | /** | ||
179 | * Function that will be called whenever the plugin receives data over | ||
180 | * the network and wants to determine how long it should wait until | ||
181 | * the next time it reads from the given peer. Note that some plugins | ||
182 | * (such as UDP) may not be able to wait (for a particular peer), so | ||
183 | * the waiting part is optional. Plugins that can wait should call | ||
184 | * this function, sleep the given amount of time, and call it again | ||
185 | * (with zero bytes read) UNTIL it returns zero and only then read. | ||
186 | * | ||
187 | * @param cls closure | ||
188 | * @param peer which peer did we read data from | ||
189 | * @param amount_recved number of bytes read (can be zero) | ||
190 | * @return how long to wait until reading more from this peer | ||
191 | * (to enforce inbound quotas); returning #GNUNET_TIME_UNIT_FOREVER_REL | ||
192 | * means that the connection should be closed | ||
193 | */ | ||
194 | typedef struct GNUNET_TIME_Relative | ||
195 | (*GNUNET_TRANSPORT_TrafficReport) (void *cls, | ||
196 | const struct GNUNET_PeerIdentity *peer, | ||
197 | size_t amount_recved); | ||
198 | |||
199 | |||
200 | /** | ||
201 | * Function that returns a HELLO message. | ||
202 | * | ||
203 | * @return HELLO message (FIXME with what?) | ||
204 | */ | ||
205 | typedef const struct GNUNET_MessageHeader * | ||
206 | (*GNUNET_TRANSPORT_GetHelloCallback) (void); | ||
207 | |||
208 | |||
209 | /** | ||
210 | * The transport service will pass a pointer to a struct | ||
211 | * of this type as the first and only argument to the | ||
212 | * entry point of each transport plugin. | ||
213 | */ | ||
214 | struct GNUNET_TRANSPORT_PluginEnvironment | ||
215 | { | ||
216 | /** | ||
217 | * Configuration to use. | ||
218 | */ | ||
219 | const struct GNUNET_CONFIGURATION_Handle *cfg; | ||
220 | |||
221 | /** | ||
222 | * Identity of this peer. | ||
223 | */ | ||
224 | const struct GNUNET_PeerIdentity *my_identity; | ||
225 | |||
226 | /** | ||
227 | * Closure for the various callbacks. | ||
228 | */ | ||
229 | void *cls; | ||
230 | |||
231 | /** | ||
232 | * Handle for reporting statistics. | ||
233 | */ | ||
234 | struct GNUNET_STATISTICS_Handle *stats; | ||
235 | |||
236 | /** | ||
237 | * Function that should be called by the transport plugin | ||
238 | * whenever a message is received. If this field is "NULL", | ||
239 | * the plugin should load in 'stub' mode and NOT fully | ||
240 | * initialize and instead only return an API with the | ||
241 | * @e address_pretty_printer, @e address_to_string and | ||
242 | * @e string_to_address functions. | ||
243 | */ | ||
244 | GNUNET_TRANSPORT_PluginReceiveCallback receive; | ||
245 | |||
246 | /** | ||
247 | * Function that returns our HELLO. | ||
248 | */ | ||
249 | GNUNET_TRANSPORT_GetHelloCallback get_our_hello; | ||
250 | |||
251 | /** | ||
252 | * Function that must be called by each plugin to notify the | ||
253 | * transport service about the addresses under which the transport | ||
254 | * provided by the plugin can be reached. | ||
255 | */ | ||
256 | GNUNET_TRANSPORT_AddressNotification notify_address; | ||
257 | |||
258 | /** | ||
259 | * Function that must be called by the plugin when a non-NULL | ||
260 | * session handle stops being valid (is destroyed). | ||
261 | */ | ||
262 | GNUNET_TRANSPORT_SessionEnd session_end; | ||
263 | |||
264 | /** | ||
265 | * Function called by the plugin when a new (incoming) session was created | ||
266 | * not explicitly created using the the get_session function | ||
267 | */ | ||
268 | GNUNET_TRANSPORT_SessionStart session_start; | ||
269 | |||
270 | /** | ||
271 | * Function that will be called to figure if an address is an loopback, | ||
272 | * LAN, WAN etc. address | ||
273 | */ | ||
274 | GNUNET_TRANSPORT_AddressToType get_address_type; | ||
275 | |||
276 | /** | ||
277 | * Function that will be called by DV to update distance for | ||
278 | * an address. | ||
279 | */ | ||
280 | GNUNET_TRANSPORT_UpdateAddressDistance update_address_distance; | ||
281 | |||
282 | /** | ||
283 | * What is the maximum number of connections that this transport | ||
284 | * should allow? Transports that do not have sessions (such as | ||
285 | * UDP) can ignore this value. | ||
286 | */ | ||
287 | uint32_t max_connections; | ||
288 | }; | ||
289 | |||
290 | |||
291 | /** | ||
292 | * Function called by the #GNUNET_TRANSPORT_TransmitFunction | ||
293 | * upon "completion". In the case that a peer disconnects, | ||
294 | * this function must be called for each pending request | ||
295 | * (with a 'failure' indication) AFTER notifying the service | ||
296 | * about the disconnect event (so that the service won't try | ||
297 | * to transmit more messages, believing the connection still | ||
298 | * exists...). | ||
299 | * | ||
300 | * @param cls closure | ||
301 | * @param target who was the recipient of the message? | ||
302 | * @param result #GNUNET_OK on success | ||
303 | * #GNUNET_SYSERR if the target disconnected; | ||
304 | * disconnect will ALSO be signalled using | ||
305 | * the ReceiveCallback. | ||
306 | * @param size_payload bytes of payload from transport service in message | ||
307 | * @param size_on_wire bytes required on wire for transmission, | ||
308 | * 0 if result == #GNUNET_SYSERR | ||
309 | */ | ||
310 | typedef void | ||
311 | (*GNUNET_TRANSPORT_TransmitContinuation) (void *cls, | ||
312 | const struct | ||
313 | GNUNET_PeerIdentity *target, | ||
314 | int result, | ||
315 | size_t size_payload, | ||
316 | size_t size_on_wire); | ||
317 | |||
318 | |||
319 | /** | ||
320 | * The new send function with just the session and no address | ||
321 | * | ||
322 | * Function that can be used by the transport service to transmit | ||
323 | * a message using the plugin. Note that in the case of a | ||
324 | * peer disconnecting, the continuation MUST be called | ||
325 | * prior to the disconnect notification itself. This function | ||
326 | * will be called with this peer's HELLO message to initiate | ||
327 | * a fresh connection to another peer. | ||
328 | * | ||
329 | * @param cls closure | ||
330 | * @param session which session must be used | ||
331 | * @param msgbuf the message to transmit | ||
332 | * @param msgbuf_size number of bytes in @a msgbuf | ||
333 | * @param priority how important is the message (most plugins will | ||
334 | * ignore message priority and just FIFO) | ||
335 | * @param to how long to wait at most for the transmission (does not | ||
336 | * require plugins to discard the message after the timeout, | ||
337 | * just advisory for the desired delay; most plugins will ignore | ||
338 | * this as well) | ||
339 | * @param cont continuation to call once the message has | ||
340 | * been transmitted (or if the transport is ready | ||
341 | * for the next transmission call; or if the | ||
342 | * peer disconnected...); can be NULL | ||
343 | * @param cont_cls closure for @a cont | ||
344 | * @return number of bytes used (on the physical network, with overheads); | ||
345 | * -1 on hard errors (i.e. address invalid); 0 is a legal value | ||
346 | * and does NOT mean that the message was not transmitted (DV) | ||
347 | */ | ||
348 | typedef ssize_t | ||
349 | (*GNUNET_TRANSPORT_TransmitFunction) (void *cls, | ||
350 | struct GNUNET_ATS_Session *session, | ||
351 | const char *msgbuf, | ||
352 | size_t msgbuf_size, | ||
353 | unsigned int priority, | ||
354 | struct GNUNET_TIME_Relative to, | ||
355 | GNUNET_TRANSPORT_TransmitContinuation cont, | ||
356 | void *cont_cls); | ||
357 | |||
358 | |||
359 | /** | ||
360 | * Function that can be called to force a disconnect from the | ||
361 | * specified neighbour for the given session only. . This should | ||
362 | * also cancel all previously scheduled transmissions for this | ||
363 | * session. Obviously the transmission may have been partially | ||
364 | * completed already, which is OK. The plugin is supposed to close | ||
365 | * the connection (if applicable). | ||
366 | * | ||
367 | * @param cls closure with the `struct Plugin` | ||
368 | * @param session session to destroy | ||
369 | * @return #GNUNET_OK on success | ||
370 | */ | ||
371 | typedef int | ||
372 | (*GNUNET_TRANSPORT_DisconnectSessionFunction) (void *cls, | ||
373 | struct GNUNET_ATS_Session * | ||
374 | session); | ||
375 | |||
376 | |||
377 | /** | ||
378 | * Function that is called to get the keepalive factor. | ||
379 | * #GNUNET_CONSTANTS_IDLE_CONNECTION_TIMEOUT is divided by this number to | ||
380 | * calculate the interval between keepalive packets. | ||
381 | * | ||
382 | * @param cls closure with the `struct Plugin` | ||
383 | * @return keepalive factor | ||
384 | */ | ||
385 | typedef unsigned int | ||
386 | (*GNUNET_TRANSPORT_QueryKeepaliveFactorFunction) (void *cls); | ||
387 | |||
388 | |||
389 | /** | ||
390 | * Function that can be called to force a disconnect from the | ||
391 | * specified neighbour. This should also cancel all previously | ||
392 | * scheduled transmissions. Obviously the transmission may have been | ||
393 | * partially completed already, which is OK. The plugin is supposed | ||
394 | * to close the connection (if applicable) and no longer call the | ||
395 | * transmit continuation(s). | ||
396 | * | ||
397 | * @param cls closure | ||
398 | * @param target peer for which the last transmission is | ||
399 | * to be cancelled | ||
400 | */ | ||
401 | typedef void | ||
402 | (*GNUNET_TRANSPORT_DisconnectPeerFunction) (void *cls, | ||
403 | const struct | ||
404 | GNUNET_PeerIdentity *target); | ||
405 | |||
406 | |||
407 | /** | ||
408 | * Function called by the pretty printer for the resolved address for | ||
409 | * each human-readable address obtained. The callback can be called | ||
410 | * several times. The last invocation must be with a @a address of | ||
411 | * NULL and a @a res of #GNUNET_OK. Thus, to indicate conversion | ||
412 | * errors, the callback might be called first with @a address NULL and | ||
413 | * @a res being #GNUNET_SYSERR. In that case, there must still be a | ||
414 | * subsequent call later with @a address NULL and @a res #GNUNET_OK. | ||
415 | * | ||
416 | * @param cls closure | ||
417 | * @param address one of the names for the host, NULL on last callback | ||
418 | * @param res #GNUNET_OK if conversion was successful, #GNUNET_SYSERR on failure, | ||
419 | * #GNUNET_OK on last callback | ||
420 | */ | ||
421 | typedef void | ||
422 | (*GNUNET_TRANSPORT_AddressStringCallback) (void *cls, | ||
423 | const char *address, | ||
424 | int res); | ||
425 | |||
426 | |||
427 | /** | ||
428 | * Convert the transports address to a nice, human-readable | ||
429 | * format. | ||
430 | * | ||
431 | * @param cls closure | ||
432 | * @param type name of the transport that generated the address | ||
433 | * @param addr one of the addresses of the host, NULL for the last address | ||
434 | * the specific address format depends on the transport | ||
435 | * @param addrlen length of the @a addr | ||
436 | * @param numeric should (IP) addresses be displayed in numeric form? | ||
437 | * @param timeout after how long should we give up? | ||
438 | * @param asc function to call on each string | ||
439 | * @param asc_cls closure for @a asc | ||
440 | */ | ||
441 | typedef void | ||
442 | (*GNUNET_TRANSPORT_AddressPrettyPrinter) (void *cls, | ||
443 | const char *type, | ||
444 | const void *addr, | ||
445 | size_t addrlen, | ||
446 | int numeric, | ||
447 | struct GNUNET_TIME_Relative timeout, | ||
448 | GNUNET_TRANSPORT_AddressStringCallback | ||
449 | asc, | ||
450 | void *asc_cls); | ||
451 | |||
452 | |||
453 | /** | ||
454 | * Another peer has suggested an address for this peer and transport | ||
455 | * plugin. Check that this could be a valid address. This function | ||
456 | * is not expected to 'validate' the address in the sense of trying to | ||
457 | * connect to it but simply to see if the binary format is technically | ||
458 | * legal for establishing a connection to this peer (and make sure that | ||
459 | * the address really corresponds to our network connection/settings | ||
460 | * and not some potential man-in-the-middle). | ||
461 | * | ||
462 | * @param addr pointer to the address | ||
463 | * @param addrlen length of @a addr | ||
464 | * @return #GNUNET_OK if this is a plausible address for this peer | ||
465 | * and transport, #GNUNET_SYSERR if not | ||
466 | */ | ||
467 | typedef int | ||
468 | (*GNUNET_TRANSPORT_CheckAddress) (void *cls, | ||
469 | const void *addr, | ||
470 | size_t addrlen); | ||
471 | |||
472 | |||
473 | /** | ||
474 | * Create a new session to transmit data to the target | ||
475 | * This session will used to send data to this peer and the plugin will | ||
476 | * notify us by calling the env->session_end function | ||
477 | * | ||
478 | * @param cls the plugin | ||
479 | * @param address the hello address | ||
480 | * @return the session if the address is valid, NULL otherwise | ||
481 | */ | ||
482 | typedef struct GNUNET_ATS_Session * | ||
483 | (*GNUNET_TRANSPORT_CreateSession) (void *cls, | ||
484 | const struct GNUNET_HELLO_Address *address); | ||
485 | |||
486 | |||
487 | /** | ||
488 | * Function that will be called whenever the transport service wants to | ||
489 | * notify the plugin that a session is still active and in use and | ||
490 | * therefore the session timeout for this session has to be updated | ||
491 | * | ||
492 | * @param cls closure | ||
493 | * @param peer which peer was the session for | ||
494 | * @param session which session is being updated | ||
495 | */ | ||
496 | typedef void | ||
497 | (*GNUNET_TRANSPORT_UpdateSessionTimeout) (void *cls, | ||
498 | const struct | ||
499 | GNUNET_PeerIdentity *peer, | ||
500 | struct GNUNET_ATS_Session *session); | ||
501 | |||
502 | |||
503 | /** | ||
504 | * Function that will be called whenever the transport service wants to | ||
505 | * notify the plugin that the inbound quota changed and that the plugin | ||
506 | * should update it's delay for the next receive value | ||
507 | * | ||
508 | * @param cls closure | ||
509 | * @param peer which peer was the session for | ||
510 | * @param session which session is being updated | ||
511 | * @param delay new delay to use for receiving | ||
512 | */ | ||
513 | typedef void | ||
514 | (*GNUNET_TRANSPORT_UpdateInboundDelay) (void *cls, | ||
515 | const struct GNUNET_PeerIdentity *peer, | ||
516 | struct GNUNET_ATS_Session *session, | ||
517 | struct GNUNET_TIME_Relative delay); | ||
518 | |||
519 | |||
520 | /** | ||
521 | * Function called for a quick conversion of the binary address to | ||
522 | * a numeric address. Note that the caller must not free the | ||
523 | * address and that the next call to this function is allowed | ||
524 | * to override the address again. | ||
525 | * | ||
526 | * @param cls closure | ||
527 | * @param addr binary address | ||
528 | * @param addr_len length of the @a addr | ||
529 | * @return string representing the same address | ||
530 | */ | ||
531 | typedef const char * | ||
532 | (*GNUNET_TRANSPORT_AddressToString) (void *cls, | ||
533 | const void *addr, | ||
534 | size_t addrlen); | ||
535 | |||
536 | |||
537 | /** | ||
538 | * Function called to convert a string address to | ||
539 | * a binary address. | ||
540 | * | ||
541 | * @param cls closure (`struct Plugin*`) | ||
542 | * @param addr string address | ||
543 | * @param addrlen length of the @a addr including \0 termination | ||
544 | * @param buf location to store the buffer | ||
545 | * If the function returns #GNUNET_SYSERR, its contents are undefined. | ||
546 | * @param added length of created address | ||
547 | * @return #GNUNET_OK on success, #GNUNET_SYSERR on failure | ||
548 | */ | ||
549 | typedef int | ||
550 | (*GNUNET_TRANSPORT_StringToAddress) (void *cls, | ||
551 | const char *addr, | ||
552 | uint16_t addrlen, | ||
553 | void **buf, | ||
554 | size_t *added); | ||
555 | |||
556 | |||
557 | /** | ||
558 | * Function to obtain the network type for a session | ||
559 | * | ||
560 | * @param cls closure (`struct Plugin *`) | ||
561 | * @param session the session | ||
562 | * @return the network type | ||
563 | */ | ||
564 | typedef enum GNUNET_NetworkType | ||
565 | (*GNUNET_TRANSPORT_GetNetworkType)(void *cls, | ||
566 | struct GNUNET_ATS_Session *session); | ||
567 | |||
568 | |||
569 | /** | ||
570 | * Function to obtain the network type for an address. | ||
571 | * | ||
572 | * @param cls closure (`struct Plugin *`) | ||
573 | * @param address the address | ||
574 | * @return the network type | ||
575 | */ | ||
576 | typedef enum GNUNET_NetworkType | ||
577 | (*GNUNET_TRANSPORT_GetNetworkTypeForAddress)(void *cls, | ||
578 | const struct | ||
579 | GNUNET_HELLO_Address *address); | ||
580 | |||
581 | |||
582 | /** | ||
583 | * Function called by the plugin with information about the | ||
584 | * current sessions managed by the plugin (for monitoring). | ||
585 | * | ||
586 | * @param cls closure | ||
587 | * @param session session handle this information is about, | ||
588 | * NULL to indicate that we are "in sync" (initial | ||
589 | * iteration complete) | ||
590 | * @param info information about the state of the session, | ||
591 | * NULL if @a session is also NULL and we are | ||
592 | * merely signalling that the initial iteration is over | ||
593 | */ | ||
594 | typedef void | ||
595 | (*GNUNET_TRANSPORT_SessionInfoCallback) (void *cls, | ||
596 | struct GNUNET_ATS_Session *session, | ||
597 | const struct | ||
598 | GNUNET_TRANSPORT_SessionInfo *info); | ||
599 | |||
600 | |||
601 | /** | ||
602 | * Begin monitoring sessions of a plugin. There can only | ||
603 | * be one active monitor per plugin (i.e. if there are | ||
604 | * multiple monitors, the transport service needs to | ||
605 | * multiplex the generated events over all of them). | ||
606 | * | ||
607 | * @param cls closure of the plugin | ||
608 | * @param sic callback to invoke, NULL to disable monitor; | ||
609 | * plugin will being by iterating over all active | ||
610 | * sessions immediately and then enter monitor mode | ||
611 | * @param sic_cls closure for @a sic | ||
612 | */ | ||
613 | typedef void | ||
614 | (*GNUNET_TRANSPORT_SessionMonitorSetup) (void *cls, | ||
615 | GNUNET_TRANSPORT_SessionInfoCallback | ||
616 | sic, | ||
617 | void *sic_cls); | ||
618 | |||
619 | |||
620 | /** | ||
621 | * Each plugin is required to return a pointer to a struct of this | ||
622 | * type as the return value from its entry point. | ||
623 | */ | ||
624 | struct GNUNET_TRANSPORT_PluginFunctions | ||
625 | { | ||
626 | /** | ||
627 | * Closure for all of the callbacks. | ||
628 | */ | ||
629 | void *cls; | ||
630 | |||
631 | /** | ||
632 | * Function that the transport service will use to transmit data to | ||
633 | * another peer. May be NULL for plugins that only support | ||
634 | * receiving data. After this call, the plugin call the specified | ||
635 | * continuation with success or error before notifying us about the | ||
636 | * target having disconnected. | ||
637 | */ | ||
638 | GNUNET_TRANSPORT_TransmitFunction send; | ||
639 | |||
640 | /** | ||
641 | * Function that can be used to force the plugin to disconnect from | ||
642 | * the given peer and cancel all previous transmissions (and their | ||
643 | * continuations). | ||
644 | */ | ||
645 | GNUNET_TRANSPORT_DisconnectPeerFunction disconnect_peer; | ||
646 | |||
647 | /** | ||
648 | * Function that can be used to force the plugin to disconnect from | ||
649 | * the given peer and cancel all previous transmissions (and their | ||
650 | * continuations). | ||
651 | */ | ||
652 | GNUNET_TRANSPORT_DisconnectSessionFunction disconnect_session; | ||
653 | |||
654 | /** | ||
655 | * Function that will be called whenever the transport service wants to | ||
656 | * notify the plugin that a session is still active and in use and | ||
657 | * therefore the session timeout for this session has to be updated | ||
658 | */ | ||
659 | GNUNET_TRANSPORT_UpdateSessionTimeout update_session_timeout; | ||
660 | |||
661 | /** | ||
662 | * Function that will be called whenever the transport service wants to | ||
663 | * notify the plugin that the inbound quota changed and that the plugin | ||
664 | * should update it's delay for the next receive value | ||
665 | */ | ||
666 | GNUNET_TRANSPORT_UpdateInboundDelay update_inbound_delay; | ||
667 | |||
668 | /** | ||
669 | * Function that is used to query keepalive factor. | ||
670 | * #GNUNET_CONSTANTS_IDLE_CONNECTION_TIMEOUT is divided by this number to | ||
671 | * calculate the interval between keepalive packets. | ||
672 | */ | ||
673 | GNUNET_TRANSPORT_QueryKeepaliveFactorFunction query_keepalive_factor; | ||
674 | |||
675 | /** | ||
676 | * Function to pretty-print addresses. | ||
677 | */ | ||
678 | GNUNET_TRANSPORT_AddressPrettyPrinter address_pretty_printer; | ||
679 | |||
680 | /** | ||
681 | * Function that will be called to check if a binary address | ||
682 | * for this plugin is well-formed and corresponds to an | ||
683 | * address for THIS peer (as per our configuration). Naturally, | ||
684 | * if absolutely necessary, plugins can be a bit conservative in | ||
685 | * their answer, but in general plugins should make sure that the | ||
686 | * address does not redirect traffic to a 3rd party that might | ||
687 | * try to man-in-the-middle our traffic. | ||
688 | */ | ||
689 | GNUNET_TRANSPORT_CheckAddress check_address; | ||
690 | |||
691 | /** | ||
692 | * Function that will be called to convert a binary address | ||
693 | * to a string (numeric conversion only). | ||
694 | */ | ||
695 | GNUNET_TRANSPORT_AddressToString address_to_string; | ||
696 | |||
697 | /** | ||
698 | * Function that will be called to convert a string address | ||
699 | * to binary (numeric conversion only). | ||
700 | */ | ||
701 | GNUNET_TRANSPORT_StringToAddress string_to_address; | ||
702 | |||
703 | /** | ||
704 | * Function that will be called tell the plugin to create a session | ||
705 | * object. | ||
706 | */ | ||
707 | GNUNET_TRANSPORT_CreateSession get_session; | ||
708 | |||
709 | /** | ||
710 | * Function to obtain the network type for a session | ||
711 | */ | ||
712 | GNUNET_TRANSPORT_GetNetworkType get_network; | ||
713 | |||
714 | /** | ||
715 | * Function to obtain the network type for an address | ||
716 | */ | ||
717 | GNUNET_TRANSPORT_GetNetworkTypeForAddress get_network_for_address; | ||
718 | |||
719 | /** | ||
720 | * Function to monitor the sessions managed by the plugin. | ||
721 | */ | ||
722 | GNUNET_TRANSPORT_SessionMonitorSetup setup_monitor; | ||
723 | }; | ||
724 | |||
725 | |||
726 | /*#ifndef PLUGIN_TRANSPORT_H*/ | ||
727 | #endif | ||
728 | |||
729 | /** @} */ /* end of group */ | ||
730 | |||
731 | /** @} */ /* end of group addition */ | ||
732 | |||
733 | /* end of gnunet_transport_plugin.h */ | ||
diff --git a/src/include/gnunet_transport_service.h b/src/include/gnunet_transport_service.h deleted file mode 100644 index 9d784e142..000000000 --- a/src/include/gnunet_transport_service.h +++ /dev/null | |||
@@ -1,722 +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 | * @addtogroup Backbone | ||
23 | * @{ | ||
24 | * | ||
25 | * @author Christian Grothoff | ||
26 | * | ||
27 | * @file | ||
28 | * Low-level P2P IO | ||
29 | * | ||
30 | * @defgroup transport Transport service | ||
31 | * Low-level P2P IO | ||
32 | * | ||
33 | * @see [Documentation](https://gnunet.org/transport-service) | ||
34 | * | ||
35 | * @{ | ||
36 | */ | ||
37 | |||
38 | #ifndef GNUNET_TRANSPORT_SERVICE_H | ||
39 | #define GNUNET_TRANSPORT_SERVICE_H | ||
40 | |||
41 | #ifdef __cplusplus | ||
42 | extern "C" { | ||
43 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
44 | } | ||
45 | #endif | ||
46 | #endif | ||
47 | |||
48 | |||
49 | #include "gnunet_util_lib.h" | ||
50 | #include "gnunet_ats_service.h" | ||
51 | |||
52 | /** | ||
53 | * Version number of the transport API. | ||
54 | */ | ||
55 | #define GNUNET_TRANSPORT_VERSION 0x00000003 | ||
56 | |||
57 | |||
58 | /* *************************** HELLO *************************** */ | ||
59 | |||
60 | /** | ||
61 | * Handle for a #GNUNET_TRANSPORT_offer_hello operation | ||
62 | */ | ||
63 | struct GNUNET_TRANSPORT_OfferHelloHandle __attribute__((deprecated)); | ||
64 | |||
65 | |||
66 | /** | ||
67 | * Offer the transport service the HELLO of another peer. Note that | ||
68 | * the transport service may just ignore this message if the HELLO is | ||
69 | * malformed or useless due to our local configuration. | ||
70 | * | ||
71 | * @param cfg configuration | ||
72 | * @param hello the hello message | ||
73 | * @param cont continuation to call when HELLO has been sent, | ||
74 | * tc reason #GNUNET_SCHEDULER_REASON_TIMEOUT for fail | ||
75 | * tc reasong #GNUNET_SCHEDULER_REASON_READ_READY for success | ||
76 | * @param cont_cls closure for @a cont | ||
77 | * @return a `struct GNUNET_TRANSPORT_OfferHelloHandle` handle or NULL on | ||
78 | * failure, in case of failure @a cont will not be called | ||
79 | * | ||
80 | */ | ||
81 | struct GNUNET_TRANSPORT_OfferHelloHandle * | ||
82 | GNUNET_TRANSPORT_offer_hello (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
83 | const struct GNUNET_MessageHeader *hello, | ||
84 | GNUNET_SCHEDULER_TaskCallback cont, | ||
85 | void *cont_cls) __attribute__((deprecated)); | ||
86 | |||
87 | |||
88 | /** | ||
89 | * Cancel the request to transport to offer the HELLO message | ||
90 | * | ||
91 | * @param ohh the `struct GNUNET_TRANSPORT_OfferHelloHandle` to cancel | ||
92 | */ | ||
93 | void | ||
94 | GNUNET_TRANSPORT_offer_hello_cancel ( | ||
95 | struct GNUNET_TRANSPORT_OfferHelloHandle *ohh) __attribute__((deprecated)); | ||
96 | |||
97 | |||
98 | /* *********************** Address to String ******************* */ | ||
99 | |||
100 | /** | ||
101 | * Handle to cancel a pending address lookup. | ||
102 | */ | ||
103 | struct GNUNET_TRANSPORT_AddressToStringContext; | ||
104 | |||
105 | |||
106 | /** | ||
107 | * Function to call with a textual representation of an address. This | ||
108 | * function will be called several times with different possible | ||
109 | * textual representations, and a last time with @a address being NULL | ||
110 | * to signal the end of the iteration. Note that @a address NULL | ||
111 | * always is the last call, regardless of the value in @a res. | ||
112 | * | ||
113 | * @param cls closure | ||
114 | * @param address NULL on end of iteration, | ||
115 | * otherwise 0-terminated printable UTF-8 string, | ||
116 | * in particular an empty string if @a res is #GNUNET_NO | ||
117 | * @param res result of the address to string conversion: | ||
118 | * if #GNUNET_OK: conversion successful | ||
119 | * if #GNUNET_NO: address was invalid (or not supported) | ||
120 | * if #GNUNET_SYSERR: communication error (IPC error) | ||
121 | */ | ||
122 | typedef void | ||
123 | (*GNUNET_TRANSPORT_AddressToStringCallback) (void *cls, | ||
124 | const char *address, | ||
125 | int res); | ||
126 | |||
127 | |||
128 | /** | ||
129 | * Convert a binary address into a human readable address. | ||
130 | * | ||
131 | * @param cfg configuration to use | ||
132 | * @param address address to convert (binary format) | ||
133 | * @param numeric should (IP) addresses be displayed in numeric form | ||
134 | * (otherwise do reverse DNS lookup) | ||
135 | * @param timeout how long is the lookup allowed to take at most | ||
136 | * @param aluc function to call with the results | ||
137 | * @param aluc_cls closure for @a aluc | ||
138 | * @return handle to cancel the operation, NULL on error | ||
139 | */ | ||
140 | struct GNUNET_TRANSPORT_AddressToStringContext * | ||
141 | GNUNET_TRANSPORT_address_to_string ( | ||
142 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
143 | const struct GNUNET_HELLO_Address *address, | ||
144 | int numeric, | ||
145 | struct GNUNET_TIME_Relative timeout, | ||
146 | GNUNET_TRANSPORT_AddressToStringCallback aluc, | ||
147 | void *aluc_cls); | ||
148 | |||
149 | |||
150 | /** | ||
151 | * Cancel request for address conversion. | ||
152 | * | ||
153 | * @param alc the context handle | ||
154 | */ | ||
155 | void | ||
156 | GNUNET_TRANSPORT_address_to_string_cancel ( | ||
157 | struct GNUNET_TRANSPORT_AddressToStringContext *alc); | ||
158 | |||
159 | |||
160 | /* *********************** Monitoring ************************** */ | ||
161 | |||
162 | |||
163 | /** | ||
164 | * Possible state of a neighbour. Initially, we are | ||
165 | * #GNUNET_TRANSPORT_PS_NOT_CONNECTED. | ||
166 | * | ||
167 | * Then, there are two main paths. If we receive a SYN message, we give | ||
168 | * the inbound address to ATS. After the check we ask ATS for a suggestion | ||
169 | * (#GNUNET_TRANSPORT_PS_CONNECT_RECV_ATS). If ATS makes a suggestion, we | ||
170 | * send our SYN_ACK and go to #GNUNET_TRANSPORT_PS_CONNECT_RECV_ACK. | ||
171 | * If we receive a ACK, we go to #GNUNET_TRANSPORT_PS_CONNECTED | ||
172 | * (and notify everyone about the new connection). If the operation times out, | ||
173 | * we go to #GNUNET_TRANSPORT_PS_DISCONNECT. | ||
174 | * | ||
175 | * The other case is where we transmit a SYN message first. We | ||
176 | * start with #GNUNET_TRANSPORT_PS_INIT_ATS. If we get an address, we send | ||
177 | * the SYN message and go to state #GNUNET_TRANSPORT_PS_CONNECT_SENT. | ||
178 | * Once we receive a SYN_ACK, we go to #GNUNET_TRANSPORT_PS_CONNECTED | ||
179 | * (and notify everyone about the new connection and send | ||
180 | * back a ACK). If the operation times out, we go to | ||
181 | * #GNUNET_TRANSPORT_PS_DISCONNECT. | ||
182 | * | ||
183 | * If the session is in trouble (i.e. transport-level disconnect or | ||
184 | * timeout), we go to #GNUNET_TRANSPORT_PS_RECONNECT_ATS where we ask ATS for a | ||
185 | * new address (we don't notify anyone about the disconnect yet). Once we have | ||
186 | * a new address, we enter #GNUNET_TRANSPORT_PS_RECONNECT_SENT and send a SYN | ||
187 | * message. If we receive a SYN_ACK, we go to #GNUNET_TRANSPORT_PS_CONNECTED | ||
188 | * and nobody noticed that we had trouble; we also send a ACK at this time just | ||
189 | * in case. If the operation times out, we go to | ||
190 | * #GNUNET_TRANSPORT_PS_DISCONNECT (and notify everyone about the lost | ||
191 | * connection). | ||
192 | * | ||
193 | * If ATS decides to switch addresses while we have a normal | ||
194 | * connection, we go to #GNUNET_TRANSPORT_PS_CONNECTED_SWITCHING_SYN_SENT | ||
195 | * and send a SESSION_CONNECT. If we get a ACK back, we switch the | ||
196 | * primary connection to the suggested alternative from ATS, go back | ||
197 | * to #GNUNET_TRANSPORT_PS_CONNECTED and send a ACK to the other peer just to be | ||
198 | * sure. If the operation times out | ||
199 | * we go to #GNUNET_TRANSPORT_PS_CONNECTED (and notify ATS that the given | ||
200 | * alternative address is "invalid"). | ||
201 | * | ||
202 | * Once a session is in #GNUNET_TRANSPORT_PS_DISCONNECT, it is cleaned up and | ||
203 | * then goes to (#GNUNET_TRANSPORT_PS_DISCONNECT_FINISHED). If we receive an | ||
204 | * explicit disconnect request, we can go from any state to | ||
205 | * #GNUNET_TRANSPORT_PS_DISCONNECT, possibly after generating disconnect | ||
206 | * notifications. | ||
207 | * | ||
208 | * Note that it is quite possible that while we are in any of these | ||
209 | * states, we could receive a 'SYN' request from the other peer. | ||
210 | * We then enter a 'weird' state where we pursue our own primary state | ||
211 | * machine (as described above), but with the 'send_connect_ack' flag | ||
212 | * set to 1. If our state machine allows us to send a 'SYN_ACK' | ||
213 | * (because we have an acceptable address), we send the 'SYN_ACK' | ||
214 | * and set the 'send_connect_ack' to 2. If we then receive a | ||
215 | * 'ACK', we go to #GNUNET_TRANSPORT_PS_CONNECTED (and reset 'send_connect_ack' | ||
216 | * to 0). | ||
217 | * | ||
218 | */ | ||
219 | enum GNUNET_TRANSPORT_PeerState | ||
220 | { | ||
221 | /** | ||
222 | * Fresh peer or completely disconnected | ||
223 | */ | ||
224 | GNUNET_TRANSPORT_PS_NOT_CONNECTED = 0, | ||
225 | |||
226 | /** | ||
227 | * Asked to initiate connection, trying to get address from ATS | ||
228 | */ | ||
229 | GNUNET_TRANSPORT_PS_INIT_ATS, | ||
230 | |||
231 | /** | ||
232 | * Sent SYN message to other peer, waiting for SYN_ACK | ||
233 | */ | ||
234 | GNUNET_TRANSPORT_PS_SYN_SENT, | ||
235 | |||
236 | /** | ||
237 | * Received a SYN, asking ATS about address suggestions. | ||
238 | */ | ||
239 | GNUNET_TRANSPORT_PS_SYN_RECV_ATS, | ||
240 | |||
241 | /** | ||
242 | * SYN request from other peer was SYN_ACK'ed, waiting for ACK. | ||
243 | */ | ||
244 | GNUNET_TRANSPORT_PS_SYN_RECV_ACK, | ||
245 | |||
246 | /** | ||
247 | * Got our SYN_ACK/ACK, connection is up. | ||
248 | */ | ||
249 | GNUNET_TRANSPORT_PS_CONNECTED, | ||
250 | |||
251 | /** | ||
252 | * Connection got into trouble, rest of the system still believes | ||
253 | * it to be up, but we're getting a new address from ATS. | ||
254 | */ | ||
255 | GNUNET_TRANSPORT_PS_RECONNECT_ATS, | ||
256 | |||
257 | /** | ||
258 | * Sent SYN over new address (either by ATS telling us to switch | ||
259 | * addresses or from RECONNECT_ATS); if this fails, we need to tell | ||
260 | * the rest of the system about a disconnect. | ||
261 | */ | ||
262 | GNUNET_TRANSPORT_PS_RECONNECT_SENT, | ||
263 | |||
264 | /** | ||
265 | * We have some primary connection, but ATS suggested we switch | ||
266 | * to some alternative; we now sent a SYN message for the | ||
267 | * alternative session to the other peer and waiting for a | ||
268 | * SYN_ACK to make this our primary connection. | ||
269 | */ | ||
270 | GNUNET_TRANSPORT_PS_SWITCH_SYN_SENT, | ||
271 | |||
272 | /** | ||
273 | * Disconnect in progress (we're sending the DISCONNECT message to the | ||
274 | * other peer; after that is finished, the state will be cleaned up). | ||
275 | */ | ||
276 | GNUNET_TRANSPORT_PS_DISCONNECT, | ||
277 | |||
278 | /** | ||
279 | * We're finished with the disconnect; and are cleaning up the state | ||
280 | * now! We put the struct into this state when we are really in the | ||
281 | * task that calls 'free' on it and are about to remove the record | ||
282 | * from the map. We should never find a 'struct NeighbourMapEntry' | ||
283 | * in this state in the map. Accessing a 'struct NeighbourMapEntry' | ||
284 | * in this state virtually always means using memory that has been | ||
285 | * freed (the exception being the cleanup code in #free_neighbour()). | ||
286 | */ | ||
287 | GNUNET_TRANSPORT_PS_DISCONNECT_FINISHED | ||
288 | } __attribute__((deprecated)); | ||
289 | |||
290 | |||
291 | /** | ||
292 | * Convert a transport state to a human readable string. | ||
293 | * | ||
294 | * @param state the state | ||
295 | */ | ||
296 | const char * | ||
297 | GNUNET_TRANSPORT_ps2s (enum GNUNET_TRANSPORT_PeerState state) __attribute__( | ||
298 | (deprecated)); | ||
299 | |||
300 | |||
301 | /** | ||
302 | * Check if a state is defined as connected | ||
303 | * | ||
304 | * @param state the state value | ||
305 | * @return #GNUNET_YES or #GNUNET_NO | ||
306 | */ | ||
307 | int | ||
308 | GNUNET_TRANSPORT_is_connected (enum GNUNET_TRANSPORT_PeerState | ||
309 | state) __attribute__((deprecated)); | ||
310 | |||
311 | |||
312 | /** | ||
313 | * Handle for a #GNUNET_TRANSPORT_monitor_peers operation. | ||
314 | */ | ||
315 | struct GNUNET_TRANSPORT_PeerMonitoringContext __attribute__((deprecated)); | ||
316 | |||
317 | |||
318 | /** | ||
319 | * Function to call with information about a peer | ||
320 | * | ||
321 | * If one_shot was set to #GNUNET_YES to iterate over all peers once, | ||
322 | * a final call with NULL for peer and address will follow when done. | ||
323 | * In this case state and timeout do not contain valid values. | ||
324 | * | ||
325 | * The #GNUNET_TRANSPORT_monitor_peers_cancel() call MUST not be called from | ||
326 | * within this function! | ||
327 | * | ||
328 | * | ||
329 | * @param cls closure | ||
330 | * @param peer peer this update is about, | ||
331 | * NULL if this is the final last callback for a iteration operation | ||
332 | * @param address address, NULL if this is the final callback for iteration op | ||
333 | * @param state current state this peer is in | ||
334 | * @param state_timeout timeout for the current state of the peer | ||
335 | */ | ||
336 | typedef void | ||
337 | (*GNUNET_TRANSPORT_PeerIterateCallback)( | ||
338 | void *cls, | ||
339 | const struct GNUNET_PeerIdentity *peer, | ||
340 | const struct GNUNET_HELLO_Address *address, | ||
341 | enum GNUNET_TRANSPORT_PeerState state, | ||
342 | struct GNUNET_TIME_Absolute state_timeout) __attribute__((deprecated)); | ||
343 | |||
344 | |||
345 | /** | ||
346 | * Return information about a specific peer or all peers currently known to | ||
347 | * transport service once or in monitoring mode. To obtain information about | ||
348 | * a specific peer, a peer identity can be passed. To obtain information about | ||
349 | * all peers currently known to transport service, NULL can be passed as peer | ||
350 | * identity. | ||
351 | * | ||
352 | * For each peer, the callback is called with information about the address used | ||
353 | * to communicate with this peer, the state this peer is currently in and the | ||
354 | * the current timeout for this state. | ||
355 | * | ||
356 | * Upon completion, the #GNUNET_TRANSPORT_PeerIterateCallback is called one | ||
357 | * more time with `NULL`. After this, the operation must no longer be | ||
358 | * explicitly canceled. | ||
359 | * | ||
360 | * The #GNUNET_TRANSPORT_monitor_peers_cancel call MUST not be called in the | ||
361 | * the peer_callback! | ||
362 | * | ||
363 | * @param cfg configuration to use | ||
364 | * @param peer a specific peer identity to obtain information for, | ||
365 | * NULL for all peers | ||
366 | * @param one_shot #GNUNET_YES to return the current state and | ||
367 | * then end (with NULL+NULL), | ||
368 | * #GNUNET_NO to monitor peers continuously | ||
369 | * @param peer_callback function to call with the results | ||
370 | * @param peer_callback_cls closure for @a peer_callback | ||
371 | */ | ||
372 | struct GNUNET_TRANSPORT_PeerMonitoringContext * | ||
373 | GNUNET_TRANSPORT_monitor_peers ( | ||
374 | const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
375 | const struct GNUNET_PeerIdentity *peer, | ||
376 | int one_shot, | ||
377 | GNUNET_TRANSPORT_PeerIterateCallback peer_callback, | ||
378 | void *peer_callback_cls) __attribute__((deprecated)) __attribute__( | ||
379 | (deprecated)); | ||
380 | |||
381 | |||
382 | /** | ||
383 | * Cancel request to monitor peers | ||
384 | * | ||
385 | * @param pic handle for the request to cancel | ||
386 | */ | ||
387 | void | ||
388 | GNUNET_TRANSPORT_monitor_peers_cancel ( | ||
389 | struct GNUNET_TRANSPORT_PeerMonitoringContext *pic) __attribute__( | ||
390 | (deprecated)) __attribute__((deprecated)); | ||
391 | |||
392 | |||
393 | /* *********************** Blacklisting ************************ */ | ||
394 | |||
395 | /** | ||
396 | * Handle for blacklisting peers. | ||
397 | */ | ||
398 | struct GNUNET_TRANSPORT_Blacklist __attribute__((deprecated)); | ||
399 | |||
400 | |||
401 | /** | ||
402 | * Function that decides if a connection is acceptable or not. | ||
403 | * | ||
404 | * @param cls closure | ||
405 | * @param pid peer to approve or disapproave | ||
406 | * @return #GNUNET_OK if the connection is allowed, #GNUNET_SYSERR if not | ||
407 | */ | ||
408 | typedef int | ||
409 | (*GNUNET_TRANSPORT_BlacklistCallback)( | ||
410 | void *cls, | ||
411 | const struct GNUNET_PeerIdentity *pid) __attribute__((deprecated)); | ||
412 | |||
413 | |||
414 | /** | ||
415 | * Install a blacklist callback. The service will be queried for all | ||
416 | * existing connections as well as any fresh connections to check if | ||
417 | * they are permitted. If the blacklisting callback is unregistered, | ||
418 | * all hosts that were denied in the past will automatically be | ||
419 | * whitelisted again. Cancelling the blacklist handle is also the | ||
420 | * only way to re-enable connections from peers that were previously | ||
421 | * blacklisted. | ||
422 | * | ||
423 | * @param cfg configuration to use | ||
424 | * @param cb callback to invoke to check if connections are allowed | ||
425 | * @param cb_cls closure for @a cb | ||
426 | * @return NULL on error, otherwise handle for cancellation | ||
427 | */ | ||
428 | struct GNUNET_TRANSPORT_Blacklist * | ||
429 | GNUNET_TRANSPORT_blacklist (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
430 | GNUNET_TRANSPORT_BlacklistCallback cb, | ||
431 | void *cb_cls) __attribute__((deprecated)); | ||
432 | |||
433 | |||
434 | /** | ||
435 | * Abort the blacklist. Note that this function is the only way for | ||
436 | * removing a peer from the blacklist. | ||
437 | * | ||
438 | * @param br handle of the request that is to be cancelled | ||
439 | */ | ||
440 | void | ||
441 | GNUNET_TRANSPORT_blacklist_cancel (struct | ||
442 | GNUNET_TRANSPORT_Blacklist *br) __attribute__( | ||
443 | (deprecated)); | ||
444 | |||
445 | |||
446 | /** | ||
447 | * Handle for a plugin session state monitor. | ||
448 | */ | ||
449 | struct GNUNET_TRANSPORT_PluginMonitor __attribute__((deprecated)); | ||
450 | |||
451 | /** | ||
452 | * Abstract representation of a plugin's session. | ||
453 | * Corresponds to the `struct GNUNET_ATS_Session` within the TRANSPORT service. | ||
454 | */ | ||
455 | struct GNUNET_TRANSPORT_PluginSession __attribute__((deprecated)); | ||
456 | |||
457 | |||
458 | /** | ||
459 | * Possible states of a session in a plugin. | ||
460 | */ | ||
461 | enum GNUNET_TRANSPORT_SessionState | ||
462 | { | ||
463 | /** | ||
464 | * The session was created (first call for each session object). | ||
465 | */ | ||
466 | GNUNET_TRANSPORT_SS_INIT, | ||
467 | |||
468 | /** | ||
469 | * Initial session handshake is in progress. | ||
470 | */ | ||
471 | GNUNET_TRANSPORT_SS_HANDSHAKE, | ||
472 | |||
473 | /** | ||
474 | * Session is fully UP. | ||
475 | */ | ||
476 | GNUNET_TRANSPORT_SS_UP, | ||
477 | |||
478 | /** | ||
479 | * This is just an update about the session, | ||
480 | * the state did not change. | ||
481 | */ | ||
482 | GNUNET_TRANSPORT_SS_UPDATE, | ||
483 | |||
484 | /** | ||
485 | * Session is being torn down and about to disappear. | ||
486 | * Last call for each session object. | ||
487 | */ | ||
488 | GNUNET_TRANSPORT_SS_DONE | ||
489 | } __attribute__((deprecated)); | ||
490 | |||
491 | |||
492 | /** | ||
493 | * Information about a plugin's session. | ||
494 | */ | ||
495 | struct GNUNET_TRANSPORT_SessionInfo | ||
496 | { | ||
497 | /** | ||
498 | * New state of the session. | ||
499 | */ | ||
500 | enum GNUNET_TRANSPORT_SessionState state; | ||
501 | |||
502 | /** | ||
503 | * #GNUNET_YES if this is an inbound connection, | ||
504 | * #GNUNET_NO if this is an outbound connection, | ||
505 | * #GNUNET_SYSERR if connections of this plugin | ||
506 | * are so fundamentally bidirectional | ||
507 | * that they have no 'initiator' | ||
508 | */ | ||
509 | int is_inbound; | ||
510 | |||
511 | /** | ||
512 | * Number of messages pending transmission for this session. | ||
513 | */ | ||
514 | uint32_t num_msg_pending; | ||
515 | |||
516 | /** | ||
517 | * Number of bytes pending transmission for this session. | ||
518 | */ | ||
519 | uint32_t num_bytes_pending; | ||
520 | |||
521 | /** | ||
522 | * Until when does this plugin refuse to receive to manage | ||
523 | * staying within the inbound quota? ZERO if receive is | ||
524 | * active. | ||
525 | */ | ||
526 | struct GNUNET_TIME_Absolute receive_delay; | ||
527 | |||
528 | /** | ||
529 | * At what time will this session timeout (unless activity | ||
530 | * happens)? | ||
531 | */ | ||
532 | struct GNUNET_TIME_Absolute session_timeout; | ||
533 | |||
534 | /** | ||
535 | * Address used by the session. Can be NULL if none is available. | ||
536 | */ | ||
537 | const struct GNUNET_HELLO_Address *address; | ||
538 | } __attribute__((deprecated)); | ||
539 | |||
540 | |||
541 | /** | ||
542 | * Function called by the plugin with information about the | ||
543 | * current sessions managed by the plugin (for monitoring). | ||
544 | * | ||
545 | * @param cls closure | ||
546 | * @param session session handle this information is about, | ||
547 | * NULL to indicate that we are "in sync" (initial | ||
548 | * iteration complete) | ||
549 | * @param session_ctx storage location where the application | ||
550 | * can store data; will point to NULL on #GNUNET_TRANSPORT_SS_INIT, | ||
551 | * and must be reset to NULL on #GNUNET_TRANSPORT_SS_DONE | ||
552 | * @param info information about the state of the session, | ||
553 | * NULL if @a session is also NULL and we are | ||
554 | * merely signalling that the initial iteration is over; | ||
555 | * NULL with @a session being non-NULL if the monitor | ||
556 | * was being cancelled while sessions were active | ||
557 | */ | ||
558 | typedef void | ||
559 | (*GNUNET_TRANSPORT_SessionMonitorCallback)( | ||
560 | void *cls, | ||
561 | struct GNUNET_TRANSPORT_PluginSession *session, | ||
562 | void **session_ctx, | ||
563 | const struct GNUNET_TRANSPORT_SessionInfo *info) __attribute__((deprecated)); | ||
564 | |||
565 | |||
566 | /** | ||
567 | * Install a plugin session state monitor callback. The callback | ||
568 | * will be notified whenever the session changes. | ||
569 | * | ||
570 | * @param cfg configuration to use | ||
571 | * @param cb callback to invoke on events | ||
572 | * @param cb_cls closure for @a cb | ||
573 | * @return NULL on error, otherwise handle for cancellation | ||
574 | */ | ||
575 | struct GNUNET_TRANSPORT_PluginMonitor * | ||
576 | GNUNET_TRANSPORT_monitor_plugins (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
577 | GNUNET_TRANSPORT_SessionMonitorCallback cb, | ||
578 | void *cb_cls) __attribute__((deprecated)); | ||
579 | |||
580 | |||
581 | /** | ||
582 | * Cancel monitoring the plugin session state. The callback will be | ||
583 | * called once for each session that is up with the "info" argument | ||
584 | * being NULL (this is just to enable client-side cleanup). | ||
585 | * | ||
586 | * @param pm handle of the request that is to be cancelled | ||
587 | */ | ||
588 | void | ||
589 | GNUNET_TRANSPORT_monitor_plugins_cancel ( | ||
590 | struct GNUNET_TRANSPORT_PluginMonitor *pm) __attribute__((deprecated)); | ||
591 | |||
592 | |||
593 | /** | ||
594 | * Opaque handle to the service. | ||
595 | */ | ||
596 | struct GNUNET_TRANSPORT_CoreHandle; | ||
597 | |||
598 | |||
599 | /** | ||
600 | * Function called to notify transport users that another | ||
601 | * peer connected to us. | ||
602 | * | ||
603 | * @param cls closure | ||
604 | * @param peer the identity of the peer that connected; this | ||
605 | * pointer will remain valid until the disconnect, hence | ||
606 | * applications do not necessarily have to make a copy | ||
607 | * of the value if they only need it until disconnect | ||
608 | * @param mq message queue to use to transmit to @a peer | ||
609 | * @return closure to use in MQ handlers | ||
610 | */ | ||
611 | typedef void * | ||
612 | (*GNUNET_TRANSPORT_NotifyConnect) ( | ||
613 | void *cls, | ||
614 | const struct GNUNET_PeerIdentity *peer, | ||
615 | struct GNUNET_MQ_Handle *mq); | ||
616 | |||
617 | |||
618 | /** | ||
619 | * Function called to notify transport users that another peer | ||
620 | * disconnected from us. The message queue that was given to the | ||
621 | * connect notification will be destroyed and must not be used | ||
622 | * henceforth. | ||
623 | * | ||
624 | * @param cls closure from #GNUNET_TRANSPORT_core_connect | ||
625 | * @param peer the peer that disconnected | ||
626 | * @param handlers_cls closure of the handlers, was returned from the | ||
627 | * connect notification callback | ||
628 | */ | ||
629 | typedef void | ||
630 | (*GNUNET_TRANSPORT_NotifyDisconnect) ( | ||
631 | void *cls, | ||
632 | const struct GNUNET_PeerIdentity *peer, | ||
633 | void *handler_cls); | ||
634 | |||
635 | |||
636 | /** | ||
637 | * Function called if we have "excess" bandwidth to a peer. | ||
638 | * The notification will happen the first time we have excess | ||
639 | * bandwidth, and then only again after the client has performed | ||
640 | * some transmission to the peer. | ||
641 | * | ||
642 | * Excess bandwidth is defined as being allowed (by ATS) to send | ||
643 | * more data, and us reaching the limit of the capacity build-up | ||
644 | * (which, if we go past it, means we don't use available bandwidth). | ||
645 | * See also the "max carry" in `struct GNUNET_BANDWIDTH_Tracker`. | ||
646 | * | ||
647 | * @param cls the closure | ||
648 | * @param neighbour peer that we have excess bandwidth to | ||
649 | * @param handlers_cls closure of the handlers, was returned from the | ||
650 | * connect notification callback | ||
651 | */ | ||
652 | typedef void | ||
653 | (*GNUNET_TRANSPORT_NotifyExcessBandwidth)( | ||
654 | void *cls, | ||
655 | const struct GNUNET_PeerIdentity *neighbour, | ||
656 | void *handlers_cls) __attribute__((deprecated)); | ||
657 | |||
658 | |||
659 | /** | ||
660 | * Connect to the transport service. Note that the connection may | ||
661 | * complete (or fail) asynchronously. | ||
662 | * | ||
663 | * @param cfg configuration to use | ||
664 | * @param self our own identity (API should check that it matches | ||
665 | * the identity found by transport), or NULL (no check) | ||
666 | * @param handlers array of message handlers; note that the | ||
667 | * closures provided will be ignored and replaced | ||
668 | * with the respective return value from @a nc | ||
669 | * @param handlers array with handlers to call when we receive messages, or NULL | ||
670 | * @param cls closure for the @a nc, @a nd and @a neb callbacks | ||
671 | * @param nc function to call on connect events, or NULL | ||
672 | * @param nd function to call on disconnect events, or NULL | ||
673 | * @param neb function to call if we have excess bandwidth to a peer, or NULL | ||
674 | * @return NULL on error | ||
675 | */ | ||
676 | struct GNUNET_TRANSPORT_CoreHandle * | ||
677 | GNUNET_TRANSPORT_core_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, | ||
678 | const struct GNUNET_PeerIdentity *self, | ||
679 | const struct GNUNET_MQ_MessageHandler *handlers, | ||
680 | void *cls, | ||
681 | GNUNET_TRANSPORT_NotifyConnect nc, | ||
682 | GNUNET_TRANSPORT_NotifyDisconnect nd, | ||
683 | GNUNET_TRANSPORT_NotifyExcessBandwidth neb) | ||
684 | __attribute__((deprecated)); | ||
685 | |||
686 | |||
687 | /** | ||
688 | * Disconnect from the transport service. | ||
689 | * | ||
690 | * @param handle handle returned from connect | ||
691 | */ | ||
692 | void | ||
693 | GNUNET_TRANSPORT_core_disconnect (struct GNUNET_TRANSPORT_CoreHandle *handle); | ||
694 | |||
695 | |||
696 | /** | ||
697 | * Checks if a given peer is connected to us and get the message queue. | ||
698 | * | ||
699 | * @param handle connection to transport service | ||
700 | * @param peer the peer to check | ||
701 | * @return NULL if disconnected, otherwise message queue for @a peer | ||
702 | */ | ||
703 | struct GNUNET_MQ_Handle * | ||
704 | GNUNET_TRANSPORT_core_get_mq (struct GNUNET_TRANSPORT_CoreHandle *handle, | ||
705 | const struct GNUNET_PeerIdentity *peer); | ||
706 | |||
707 | |||
708 | #if 0 /* keep Emacsens' auto-indent happy */ | ||
709 | { | ||
710 | #endif | ||
711 | #ifdef __cplusplus | ||
712 | } | ||
713 | #endif | ||
714 | |||
715 | /* ifndef GNUNET_TRANSPORT_SERVICE_H */ | ||
716 | #endif | ||
717 | |||
718 | /** @} */ /* end of group */ | ||
719 | |||
720 | /** @} */ /* end of group addition */ | ||
721 | |||
722 | /* end of gnunet_transport_service.h */ | ||