aboutsummaryrefslogtreecommitdiff
path: root/src/include
diff options
context:
space:
mode:
authorMartin Schanzenbach <schanzen@gnunet.org>2023-10-05 08:16:06 +0200
committerMartin Schanzenbach <schanzen@gnunet.org>2023-10-05 08:16:06 +0200
commit09f0c25760dfa32982e609e7cf4246bbeff401af (patch)
tree5e0695ceeb8ef794536905514fa72c5d432479e2 /src/include
parent614ed461b8a4c4fbf8cbdfb6b7f1a3f28a1ab8a9 (diff)
downloadgnunet-09f0c25760dfa32982e609e7cf4246bbeff401af.tar.gz
gnunet-09f0c25760dfa32982e609e7cf4246bbeff401af.zip
Remove more traces of old transport
Diffstat (limited to 'src/include')
-rw-r--r--src/include/Makefile.am2
-rw-r--r--src/include/gnunet_transport_plugin.h733
-rw-r--r--src/include/gnunet_transport_service.h722
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 */
64struct 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 */
80typedef 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 */
94typedef 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 */
123typedef 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 */
142typedef 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 */
155typedef 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 */
171typedef 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 */
194typedef 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 */
205typedef 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 */
214struct 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 */
310typedef 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 */
348typedef 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 */
371typedef 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 */
385typedef 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 */
401typedef 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 */
421typedef 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 */
441typedef 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 */
467typedef 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 */
482typedef 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 */
496typedef 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 */
513typedef 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 */
531typedef 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 */
549typedef 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 */
564typedef 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 */
576typedef 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 */
594typedef 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 */
613typedef 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 */
624struct 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
42extern "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 */
63struct 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 */
81struct GNUNET_TRANSPORT_OfferHelloHandle *
82GNUNET_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 */
93void
94GNUNET_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 */
103struct 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 */
122typedef 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 */
140struct GNUNET_TRANSPORT_AddressToStringContext *
141GNUNET_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 */
155void
156GNUNET_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 */
219enum 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 */
296const char *
297GNUNET_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 */
307int
308GNUNET_TRANSPORT_is_connected (enum GNUNET_TRANSPORT_PeerState
309 state) __attribute__((deprecated));
310
311
312/**
313 * Handle for a #GNUNET_TRANSPORT_monitor_peers operation.
314 */
315struct 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 */
336typedef 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 */
372struct GNUNET_TRANSPORT_PeerMonitoringContext *
373GNUNET_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 */
387void
388GNUNET_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 */
398struct 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 */
408typedef 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 */
428struct GNUNET_TRANSPORT_Blacklist *
429GNUNET_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 */
440void
441GNUNET_TRANSPORT_blacklist_cancel (struct
442 GNUNET_TRANSPORT_Blacklist *br) __attribute__(
443 (deprecated));
444
445
446/**
447 * Handle for a plugin session state monitor.
448 */
449struct 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 */
455struct GNUNET_TRANSPORT_PluginSession __attribute__((deprecated));
456
457
458/**
459 * Possible states of a session in a plugin.
460 */
461enum 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 */
495struct 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 */
558typedef 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 */
575struct GNUNET_TRANSPORT_PluginMonitor *
576GNUNET_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 */
588void
589GNUNET_TRANSPORT_monitor_plugins_cancel (
590 struct GNUNET_TRANSPORT_PluginMonitor *pm) __attribute__((deprecated));
591
592
593/**
594 * Opaque handle to the service.
595 */
596struct 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 */
611typedef 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 */
629typedef 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 */
652typedef 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 */
676struct GNUNET_TRANSPORT_CoreHandle *
677GNUNET_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 */
692void
693GNUNET_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 */
703struct GNUNET_MQ_Handle *
704GNUNET_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 */