2 This file is part of GNUnet.
3 Copyright (C) 2009-2014 GNUnet e.V.
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @author Christian Grothoff
27 * @defgroup transport Transport service
30 * @see [Documentation](https://gnunet.org/transport-service)
35 #ifndef GNUNET_TRANSPORT_SERVICE_H
36 #define GNUNET_TRANSPORT_SERVICE_H
41 #if 0 /* keep Emacsens' auto-indent happy */
46 #include "gnunet_util_lib.h"
47 #include "gnunet_ats_service.h"
50 * Version number of the transport API.
52 #define GNUNET_TRANSPORT_VERSION 0x00000002
56 * Function called by the transport for each received message.
59 * @param peer (claimed) identity of the other peer
60 * @param message the message
63 (*GNUNET_TRANSPORT_ReceiveCallback) (void *cls,
64 const struct GNUNET_PeerIdentity *peer,
65 const struct GNUNET_MessageHeader *message);
69 * Opaque handle to the service.
71 struct GNUNET_TRANSPORT_Handle;
75 * Function called to notify transport users that another
76 * peer connected to us.
79 * @param peer the peer that connected
82 (*GNUNET_TRANSPORT_NotifyConnect) (void *cls,
83 const struct GNUNET_PeerIdentity *peer);
86 * Function called to notify transport users that another
87 * peer disconnected from us.
90 * @param peer the peer that disconnected
93 (*GNUNET_TRANSPORT_NotifyDisconnect) (void *cls,
94 const struct GNUNET_PeerIdentity *peer);
98 * Connect to the transport service. Note that the connection may
99 * complete (or fail) asynchronously.
101 * @param cfg configuration to use
102 * @param self our own identity (API should check that it matches
103 * the identity found by transport), or NULL (no check)
104 * @param cls closure for the callbacks
105 * @param rec receive function to call, or NULL
106 * @param nc function to call on connect events, or NULL
107 * @param nd function to call on disconnect events, or NULL
108 * @return NULL on error
110 struct GNUNET_TRANSPORT_Handle *
111 GNUNET_TRANSPORT_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
112 const struct GNUNET_PeerIdentity *self,
114 GNUNET_TRANSPORT_ReceiveCallback rec,
115 GNUNET_TRANSPORT_NotifyConnect nc,
116 GNUNET_TRANSPORT_NotifyDisconnect nd);
120 * Function called if we have "excess" bandwidth to a peer.
121 * The notification will happen the first time we have excess
122 * bandwidth, and then only again after the client has performed
123 * some transmission to the peer.
125 * Excess bandwidth is defined as being allowed (by ATS) to send
126 * more data, and us reaching the limit of the capacity build-up
127 * (which, if we go past it, means we don't use available bandwidth).
128 * See also the "max carry" in `struct GNUNET_BANDWIDTH_Tracker`.
130 * @param cls the closure
131 * @param neighbour peer that we have excess bandwidth to
134 (*GNUNET_TRANSPORT_NotifyExcessBandwidth)(void *cls,
135 const struct GNUNET_PeerIdentity *neighbour);
139 * Connect to the transport service. Note that the connection may
140 * complete (or fail) asynchronously.
142 * @param cfg configuration to use
143 * @param self our own identity (API should check that it matches
144 * the identity found by transport), or NULL (no check)
145 * @param cls closure for the callbacks
146 * @param rec receive function to call, or NULL
147 * @param nc function to call on connect events, or NULL
148 * @param nd function to call on disconnect events, or NULL
149 * @param neb function to call if we have excess bandwidth to a peer
150 * @return NULL on error
152 struct GNUNET_TRANSPORT_Handle *
153 GNUNET_TRANSPORT_connect2 (const struct GNUNET_CONFIGURATION_Handle *cfg,
154 const struct GNUNET_PeerIdentity *self,
156 GNUNET_TRANSPORT_ReceiveCallback rec,
157 GNUNET_TRANSPORT_NotifyConnect nc,
158 GNUNET_TRANSPORT_NotifyDisconnect nd,
159 GNUNET_TRANSPORT_NotifyExcessBandwidth neb);
163 * Disconnect from the transport service.
165 * @param handle handle returned from connect
168 GNUNET_TRANSPORT_disconnect (struct GNUNET_TRANSPORT_Handle *handle);
171 /* ************************* Sending *************************** */
174 * Opaque handle for a transmission-ready request.
176 struct GNUNET_TRANSPORT_TransmitHandle;
180 * Function called to notify a client about the connection begin ready
181 * to queue more data. @a buf will be NULL and @a size zero if the
182 * connection was closed for writing in the meantime.
185 * @param size number of bytes available in @a buf
186 * @param buf where the callee should write the message
187 * @return number of bytes written to @a buf
190 (*GNUNET_TRANSPORT_TransmitReadyNotify) (void *cls,
196 * Check if we could queue a message of the given size for
197 * transmission. The transport service will take both its internal
198 * buffers and bandwidth limits imposed by the other peer into
199 * consideration when answering this query.
201 * @param handle connection to transport service
202 * @param target who should receive the message
203 * @param size how big is the message we want to transmit?
204 * @param timeout after how long should we give up (and call
205 * notify with buf NULL and size 0)?
206 * @param notify function to call when we are ready to
207 * send such a message
208 * @param notify_cls closure for @a notify
209 * @return NULL if someone else is already waiting to be notified
210 * non-NULL if the notify callback was queued (can be used to cancel
211 * using #GNUNET_TRANSPORT_notify_transmit_ready_cancel())
213 struct GNUNET_TRANSPORT_TransmitHandle *
214 GNUNET_TRANSPORT_notify_transmit_ready (struct GNUNET_TRANSPORT_Handle *handle,
215 const struct GNUNET_PeerIdentity *target,
217 struct GNUNET_TIME_Relative timeout,
218 GNUNET_TRANSPORT_TransmitReadyNotify notify,
223 * Cancel the specified transmission-ready notification.
225 * @param th handle of the transmission notification request to cancel
228 GNUNET_TRANSPORT_notify_transmit_ready_cancel (struct GNUNET_TRANSPORT_TransmitHandle *th);
232 * Checks if a given peer is connected to us
234 * @param handle connection to transport service
235 * @param peer the peer to check
236 * @return #GNUNET_YES (connected) or #GNUNET_NO (disconnected)
239 GNUNET_TRANSPORT_check_peer_connected (struct GNUNET_TRANSPORT_Handle *handle,
240 const struct GNUNET_PeerIdentity *peer);
244 /* *********************** Metric manipulation ***************** */
247 * Set transport metrics for a peer and a direction
249 * @param handle transport handle
250 * @param peer the peer to set the metric for
251 * @param prop the performance metrics to set
252 * @param delay_in inbound delay to introduce
253 * @param delay_out outbound delay to introduce
255 * Note: Delay restrictions in receiving direction will be enforced
256 * with one message delay.
259 GNUNET_TRANSPORT_set_traffic_metric (struct GNUNET_TRANSPORT_Handle *handle,
260 const struct GNUNET_PeerIdentity *peer,
261 const struct GNUNET_ATS_Properties *prop,
262 struct GNUNET_TIME_Relative delay_in,
263 struct GNUNET_TIME_Relative delay_out);
266 /* *************************** HELLO *************************** */
270 * Function called whenever there is an update to the
271 * HELLO of this peer.
274 * @param hello our updated HELLO
277 (*GNUNET_TRANSPORT_HelloUpdateCallback) (void *cls,
278 const struct GNUNET_MessageHeader *hello);
282 * Handle to cancel a #GNUNET_TRANSPORT_get_hello() operation.
284 struct GNUNET_TRANSPORT_GetHelloHandle;
288 * Obtain updates on changes to the HELLO message for this peer. The callback
289 * given in this function is never called synchronously.
291 * @param handle connection to transport service
292 * @param rec function to call with the HELLO
293 * @param rec_cls closure for @a rec
294 * @return handle to cancel the operation
296 struct GNUNET_TRANSPORT_GetHelloHandle *
297 GNUNET_TRANSPORT_get_hello (struct GNUNET_TRANSPORT_Handle *handle,
298 GNUNET_TRANSPORT_HelloUpdateCallback rec,
303 * Stop receiving updates about changes to our HELLO message.
305 * @param ghh handle to cancel
308 GNUNET_TRANSPORT_get_hello_cancel (struct GNUNET_TRANSPORT_GetHelloHandle *ghh);
312 * Handle for a #GNUNET_TRANSPORT_offer_hello operation
314 struct GNUNET_TRANSPORT_OfferHelloHandle;
318 * Offer the transport service the HELLO of another peer. Note that
319 * the transport service may just ignore this message if the HELLO is
320 * malformed or useless due to our local configuration.
322 * @param handle connection to transport service
323 * @param hello the hello message
324 * @param cont continuation to call when HELLO has been sent,
325 * tc reason #GNUNET_SCHEDULER_REASON_TIMEOUT for fail
326 * tc reasong #GNUNET_SCHEDULER_REASON_READ_READY for success
327 * @param cont_cls closure for @a cont
328 * @return a GNUNET_TRANSPORT_OfferHelloHandle handle or NULL on failure,
329 * in case of failure @a cont will not be called
332 struct GNUNET_TRANSPORT_OfferHelloHandle *
333 GNUNET_TRANSPORT_offer_hello (struct GNUNET_TRANSPORT_Handle *handle,
334 const struct GNUNET_MessageHeader *hello,
335 GNUNET_SCHEDULER_TaskCallback cont,
340 * Cancel the request to transport to offer the HELLO message
342 * @param ohh the `struct GNUNET_TRANSPORT_OfferHelloHandle` to cancel
345 GNUNET_TRANSPORT_offer_hello_cancel (struct GNUNET_TRANSPORT_OfferHelloHandle *ohh);
348 /* *********************** Address to String ******************* */
351 * Handle to cancel a pending address lookup.
353 struct GNUNET_TRANSPORT_AddressToStringContext;
357 * Function to call with a textual representation of an address. This
358 * function will be called several times with different possible
359 * textual representations, and a last time with @a address being NULL
360 * to signal the end of the iteration. Note that @a address NULL
361 * always is the last call, regardless of the value in @a res.
364 * @param address NULL on end of iteration,
365 * otherwise 0-terminated printable UTF-8 string,
366 * in particular an empty string if @a res is #GNUNET_NO
367 * @param res result of the address to string conversion:
368 * if #GNUNET_OK: conversion successful
369 * if #GNUNET_NO: address was invalid (or not supported)
370 * if #GNUNET_SYSERR: communication error (IPC error)
373 (*GNUNET_TRANSPORT_AddressToStringCallback) (void *cls,
379 * Convert a binary address into a human readable address.
381 * @param cfg configuration to use
382 * @param address address to convert (binary format)
383 * @param numeric should (IP) addresses be displayed in numeric form
384 * (otherwise do reverse DNS lookup)
385 * @param timeout how long is the lookup allowed to take at most
386 * @param aluc function to call with the results
387 * @param aluc_cls closure for @a aluc
388 * @return handle to cancel the operation, NULL on error
390 struct GNUNET_TRANSPORT_AddressToStringContext *
391 GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle *cfg,
392 const struct GNUNET_HELLO_Address *address,
394 struct GNUNET_TIME_Relative timeout,
395 GNUNET_TRANSPORT_AddressToStringCallback aluc,
400 * Cancel request for address conversion.
402 * @param pic the context handle
405 GNUNET_TRANSPORT_address_to_string_cancel (struct GNUNET_TRANSPORT_AddressToStringContext *pic);
408 /* *********************** Monitoring ************************** */
412 * Possible state of a neighbour. Initially, we are #GNUNET_TRANSPORT_PS_NOT_CONNECTED.
414 * Then, there are two main paths. If we receive a SYN message, we give
415 * the inbound address to ATS. After the check we ask ATS for a suggestion
416 * (#GNUNET_TRANSPORT_PS_CONNECT_RECV_ATS). If ATS makes a suggestion, we
417 * send our SYN_ACK and go to #GNUNET_TRANSPORT_PS_CONNECT_RECV_ACK.
418 * If we receive a ACK, we go to #GNUNET_TRANSPORT_PS_CONNECTED
419 * (and notify everyone about the new connection). If the operation times out,
420 * we go to #GNUNET_TRANSPORT_PS_DISCONNECT.
422 * The other case is where we transmit a SYN message first. We
423 * start with #GNUNET_TRANSPORT_PS_INIT_ATS. If we get an address, we send
424 * the SYN message and go to state #GNUNET_TRANSPORT_PS_CONNECT_SENT.
425 * Once we receive a SYN_ACK, we go to #GNUNET_TRANSPORT_PS_CONNECTED
426 * (and notify everyone about the new connection and send
427 * back a ACK). If the operation times out, we go to
428 * #GNUNET_TRANSPORT_PS_DISCONNECT.
430 * If the session is in trouble (i.e. transport-level disconnect or
431 * timeout), we go to #GNUNET_TRANSPORT_PS_RECONNECT_ATS where we ask ATS for a new
432 * address (we don't notify anyone about the disconnect yet). Once we
433 * have a new address, we enter #GNUNET_TRANSPORT_PS_RECONNECT_SENT and send a
434 * SYN message. If we receive a
435 * SYN_ACK, we go to #GNUNET_TRANSPORT_PS_CONNECTED and nobody noticed that we had
436 * trouble; we also send a ACK at this time just in case. If
437 * the operation times out, we go to #GNUNET_TRANSPORT_PS_DISCONNECT (and notify everyone
438 * about the lost connection).
440 * If ATS decides to switch addresses while we have a normal
441 * connection, we go to #GNUNET_TRANSPORT_PS_CONNECTED_SWITCHING_SYN_SENT
442 * and send a SESSION_CONNECT. If we get a ACK back, we switch the
443 * primary connection to the suggested alternative from ATS, go back
444 * to #GNUNET_TRANSPORT_PS_CONNECTED and send a ACK to the other peer just to be
445 * sure. If the operation times out
446 * we go to #GNUNET_TRANSPORT_PS_CONNECTED (and notify ATS that the given alternative
447 * address is "invalid").
449 * Once a session is in #GNUNET_TRANSPORT_PS_DISCONNECT, it is cleaned up and then goes
450 * to (#GNUNET_TRANSPORT_PS_DISCONNECT_FINISHED). If we receive an explicit disconnect
451 * request, we can go from any state to #GNUNET_TRANSPORT_PS_DISCONNECT, possibly after
452 * generating disconnect notifications.
454 * Note that it is quite possible that while we are in any of these
455 * states, we could receive a 'SYN' request from the other peer.
456 * We then enter a 'weird' state where we pursue our own primary state
457 * machine (as described above), but with the 'send_connect_ack' flag
458 * set to 1. If our state machine allows us to send a 'SYN_ACK'
459 * (because we have an acceptable address), we send the 'SYN_ACK'
460 * and set the 'send_connect_ack' to 2. If we then receive a
461 * 'ACK', we go to #GNUNET_TRANSPORT_PS_CONNECTED (and reset 'send_connect_ack'
465 enum GNUNET_TRANSPORT_PeerState
468 * Fresh peer or completely disconnected
470 GNUNET_TRANSPORT_PS_NOT_CONNECTED = 0,
473 * Asked to initiate connection, trying to get address from ATS
475 GNUNET_TRANSPORT_PS_INIT_ATS,
478 * Sent SYN message to other peer, waiting for SYN_ACK
480 GNUNET_TRANSPORT_PS_SYN_SENT,
483 * Received a SYN, asking ATS about address suggestions.
485 GNUNET_TRANSPORT_PS_SYN_RECV_ATS,
488 * SYN request from other peer was SYN_ACK'ed, waiting for ACK.
490 GNUNET_TRANSPORT_PS_SYN_RECV_ACK,
493 * Got our SYN_ACK/ACK, connection is up.
495 GNUNET_TRANSPORT_PS_CONNECTED,
498 * Connection got into trouble, rest of the system still believes
499 * it to be up, but we're getting a new address from ATS.
501 GNUNET_TRANSPORT_PS_RECONNECT_ATS,
504 * Sent SYN over new address (either by ATS telling us to switch
505 * addresses or from RECONNECT_ATS); if this fails, we need to tell
506 * the rest of the system about a disconnect.
508 GNUNET_TRANSPORT_PS_RECONNECT_SENT,
511 * We have some primary connection, but ATS suggested we switch
512 * to some alternative; we now sent a SYN message for the
513 * alternative session to the other peer and waiting for a
514 * SYN_ACK to make this our primary connection.
516 GNUNET_TRANSPORT_PS_SWITCH_SYN_SENT,
519 * Disconnect in progress (we're sending the DISCONNECT message to the
520 * other peer; after that is finished, the state will be cleaned up).
522 GNUNET_TRANSPORT_PS_DISCONNECT,
525 * We're finished with the disconnect; and are cleaning up the state
526 * now! We put the struct into this state when we are really in the
527 * task that calls 'free' on it and are about to remove the record
528 * from the map. We should never find a 'struct NeighbourMapEntry'
529 * in this state in the map. Accessing a 'struct NeighbourMapEntry'
530 * in this state virtually always means using memory that has been
531 * freed (the exception being the cleanup code in #free_neighbour()).
533 GNUNET_TRANSPORT_PS_DISCONNECT_FINISHED
538 * Convert a transport state to a human readable string.
540 * @param state the state
543 GNUNET_TRANSPORT_ps2s (enum GNUNET_TRANSPORT_PeerState state);
547 * Check if a state is defined as connected
549 * @param state the state value
550 * @return #GNUNET_YES or #GNUNET_NO
553 GNUNET_TRANSPORT_is_connected (enum GNUNET_TRANSPORT_PeerState state);
557 * Handle for a #GNUNET_TRANSPORT_monitor_peers operation.
559 struct GNUNET_TRANSPORT_PeerMonitoringContext;
563 * Function to call with information about a peer
565 * If one_shot was set to #GNUNET_YES to iterate over all peers once,
566 * a final call with NULL for peer and address will follow when done.
567 * In this case state and timeout do not contain valid values.
569 * The #GNUNET_TRANSPORT_monitor_peers_cancel() call MUST not be called from
570 * within this function!
574 * @param peer peer this update is about,
575 * NULL if this is the final last callback for a iteration operation
576 * @param address address, NULL if this is the final callback for iteration op
577 * @param state current state this peer is in
578 * @param state_timeout timeout for the current state of the peer
581 (*GNUNET_TRANSPORT_PeerIterateCallback) (void *cls,
582 const struct GNUNET_PeerIdentity *peer,
583 const struct GNUNET_HELLO_Address *address,
584 enum GNUNET_TRANSPORT_PeerState state,
585 struct GNUNET_TIME_Absolute state_timeout);
589 * Return information about a specific peer or all peers currently known to
590 * transport service once or in monitoring mode. To obtain information about
591 * a specific peer, a peer identity can be passed. To obtain information about
592 * all peers currently known to transport service, NULL can be passed as peer
595 * For each peer, the callback is called with information about the address used
596 * to communicate with this peer, the state this peer is currently in and the
597 * the current timeout for this state.
599 * Upon completion, the #GNUNET_TRANSPORT_PeerIterateCallback is called one
600 * more time with `NULL`. After this, the operation must no longer be
601 * explicitly canceled.
603 * The #GNUNET_TRANSPORT_monitor_peers_cancel call MUST not be called in the
606 * @param cfg configuration to use
607 * @param peer a specific peer identity to obtain information for,
609 * @param one_shot #GNUNET_YES to return the current state and then end (with NULL+NULL),
610 * #GNUNET_NO to monitor peers continuously
611 * @param timeout how long is the lookup allowed to take at most
612 * @param peer_callback function to call with the results
613 * @param peer_callback_cls closure for @a peer_callback
615 struct GNUNET_TRANSPORT_PeerMonitoringContext *
616 GNUNET_TRANSPORT_monitor_peers (const struct GNUNET_CONFIGURATION_Handle *cfg,
617 const struct GNUNET_PeerIdentity *peer,
619 struct GNUNET_TIME_Relative timeout,
620 GNUNET_TRANSPORT_PeerIterateCallback peer_callback,
621 void *peer_callback_cls);
625 * Cancel request to monitor peers
627 * @param pic handle for the request to cancel
630 GNUNET_TRANSPORT_monitor_peers_cancel (struct GNUNET_TRANSPORT_PeerMonitoringContext *pic);
634 * Handle for a #GNUNET_TRANSPORT_monitor_validation_entries() operation.
636 struct GNUNET_TRANSPORT_ValidationMonitoringContext;
640 * Current state of a validation process.
642 * FIXME: what state is used to indicate that a validation
643 * was successful? If that is clarified/determined, "UGH" in
644 * ~gnunet-peerinfo-gtk.c:1103 should be resolved.
646 enum GNUNET_TRANSPORT_ValidationState
651 * Used for final callback indicating operation done
653 GNUNET_TRANSPORT_VS_NONE,
656 * Fresh validation entry
658 * Entry was just created, no validation process was executed
660 GNUNET_TRANSPORT_VS_NEW,
663 * Updated validation entry
665 * This is an update for an existing validation entry
667 GNUNET_TRANSPORT_VS_UPDATE,
670 * Timeout for validation entry
672 * A timeout occured during the validation process
674 GNUNET_TRANSPORT_VS_TIMEOUT,
677 * Validation entry is removed
679 * The validation entry is getting removed due to a failed validation
681 GNUNET_TRANSPORT_VS_REMOVE
686 * Function to call with validation information about a peer
688 * This function is called by the transport validation monitoring api to
689 * indicate a change to a validation entry. The information included represent
690 * the current state of the validation entry,
692 * If the monitoring was called with `one_shot==GNUNET_YES`, a final callback
693 * with `address==NULL` is executed.
696 * @param address address this update is about,
697 * NULL if this is the final last callback for a iteration operation
698 * @param last_validation when was this address last validated
699 * @param valid_until when does this address expire
700 * @param next_validation time of the next validation operation
701 * @param state state in the validation state machine
704 (*GNUNET_TRANSPORT_ValidationIterateCallback) (void *cls,
705 const struct GNUNET_HELLO_Address *address,
706 struct GNUNET_TIME_Absolute last_validation,
707 struct GNUNET_TIME_Absolute valid_until,
708 struct GNUNET_TIME_Absolute next_validation,
709 enum GNUNET_TRANSPORT_ValidationState state);
713 * Convert validation state to human-readable string.
715 * @param state the state value
716 * @return corresponding string
719 GNUNET_TRANSPORT_vs2s (enum GNUNET_TRANSPORT_ValidationState state);
723 * Return information about pending address validation operations for a specific
726 * @param cfg configuration to use
727 * @param peer a specific peer identity to obtain validation entries for,
729 * @param one_shot #GNUNET_YES to return all entries and then end (with NULL+NULL),
730 * #GNUNET_NO to monitor validation entries continuously
731 * @param timeout how long is the lookup allowed to take at most
732 * @param validation_callback function to call with the results
733 * @param validation_callback_cls closure for @a validation_callback
735 struct GNUNET_TRANSPORT_ValidationMonitoringContext *
736 GNUNET_TRANSPORT_monitor_validation_entries (const struct GNUNET_CONFIGURATION_Handle *cfg,
737 const struct GNUNET_PeerIdentity *peer,
739 struct GNUNET_TIME_Relative timeout,
740 GNUNET_TRANSPORT_ValidationIterateCallback validation_callback,
741 void *validation_callback_cls);
745 * Return information about all current pending validation operations
747 * @param vic handle for the request to cancel
750 GNUNET_TRANSPORT_monitor_validation_entries_cancel (struct GNUNET_TRANSPORT_ValidationMonitoringContext *vic);
753 /* *********************** Blacklisting ************************ */
756 * Handle for blacklisting peers.
758 struct GNUNET_TRANSPORT_Blacklist;
762 * Function that decides if a connection is acceptable or not.
765 * @param pid peer to approve or disapproave
766 * @return #GNUNET_OK if the connection is allowed, #GNUNET_SYSERR if not
769 (*GNUNET_TRANSPORT_BlacklistCallback) (void *cls,
770 const struct GNUNET_PeerIdentity *pid);
774 * Install a blacklist callback. The service will be queried for all
775 * existing connections as well as any fresh connections to check if
776 * they are permitted. If the blacklisting callback is unregistered,
777 * all hosts that were denied in the past will automatically be
778 * whitelisted again. Cancelling the blacklist handle is also the
779 * only way to re-enable connections from peers that were previously
782 * @param cfg configuration to use
783 * @param cb callback to invoke to check if connections are allowed
784 * @param cb_cls closure for @a cb
785 * @return NULL on error, otherwise handle for cancellation
787 struct GNUNET_TRANSPORT_Blacklist *
788 GNUNET_TRANSPORT_blacklist (const struct GNUNET_CONFIGURATION_Handle *cfg,
789 GNUNET_TRANSPORT_BlacklistCallback cb,
794 * Abort the blacklist. Note that this function is the only way for
795 * removing a peer from the blacklist.
797 * @param br handle of the request that is to be cancelled
800 GNUNET_TRANSPORT_blacklist_cancel (struct GNUNET_TRANSPORT_Blacklist *br);
804 * Handle for a plugin session state monitor.
806 struct GNUNET_TRANSPORT_PluginMonitor;
809 * Abstract representation of a plugin's session.
810 * Corresponds to the `struct GNUNET_ATS_Session` within the TRANSPORT service.
812 struct GNUNET_TRANSPORT_PluginSession;
816 * Possible states of a session in a plugin.
818 enum GNUNET_TRANSPORT_SessionState
822 * The session was created (first call for each session object).
824 GNUNET_TRANSPORT_SS_INIT,
827 * Initial session handshake is in progress.
829 GNUNET_TRANSPORT_SS_HANDSHAKE,
832 * Session is fully UP.
834 GNUNET_TRANSPORT_SS_UP,
837 * This is just an update about the session,
838 * the state did not change.
840 GNUNET_TRANSPORT_SS_UPDATE,
843 * Session is being torn down and about to disappear.
844 * Last call for each session object.
846 GNUNET_TRANSPORT_SS_DONE
852 * Information about a plugin's session.
854 struct GNUNET_TRANSPORT_SessionInfo
858 * New state of the session.
860 enum GNUNET_TRANSPORT_SessionState state;
863 * #GNUNET_YES if this is an inbound connection,
864 * #GNUNET_NO if this is an outbound connection,
865 * #GNUNET_SYSERR if connections of this plugin
866 * are so fundamentally bidirectional
867 * that they have no 'initiator'
872 * Number of messages pending transmission for this session.
874 uint32_t num_msg_pending;
877 * Number of bytes pending transmission for this session.
879 uint32_t num_bytes_pending;
882 * Until when does this plugin refuse to receive to manage
883 * staying within the inbound quota? ZERO if receive is
886 struct GNUNET_TIME_Absolute receive_delay;
889 * At what time will this session timeout (unless activity
892 struct GNUNET_TIME_Absolute session_timeout;
895 * Address used by the session. Can be NULL if none is available.
897 const struct GNUNET_HELLO_Address *address;
902 * Function called by the plugin with information about the
903 * current sessions managed by the plugin (for monitoring).
906 * @param session session handle this information is about,
907 * NULL to indicate that we are "in sync" (initial
908 * iteration complete)
909 * @param session_ctx storage location where the application
910 * can store data; will point to NULL on #GNUNET_TRANSPORT_SS_INIT,
911 * and must be reset to NULL on #GNUNET_TRANSPORT_SS_DONE
912 * @param info information about the state of the session,
913 * NULL if @a session is also NULL and we are
914 * merely signalling that the initial iteration is over;
915 * NULL with @a session being non-NULL if the monitor
916 * was being cancelled while sessions were active
919 (*GNUNET_TRANSPORT_SessionMonitorCallback) (void *cls,
920 struct GNUNET_TRANSPORT_PluginSession *session,
922 const struct GNUNET_TRANSPORT_SessionInfo *info);
926 * Install a plugin session state monitor callback. The callback
927 * will be notified whenever the session changes.
929 * @param cfg configuration to use
930 * @param cb callback to invoke on events
931 * @param cb_cls closure for @a cb
932 * @return NULL on error, otherwise handle for cancellation
934 struct GNUNET_TRANSPORT_PluginMonitor *
935 GNUNET_TRANSPORT_monitor_plugins (const struct GNUNET_CONFIGURATION_Handle *cfg,
936 GNUNET_TRANSPORT_SessionMonitorCallback cb,
941 * Cancel monitoring the plugin session state. The callback will be
942 * called once for each session that is up with the "info" argument
943 * being NULL (this is just to enable client-side cleanup).
945 * @param pm handle of the request that is to be cancelled
948 GNUNET_TRANSPORT_monitor_plugins_cancel (struct GNUNET_TRANSPORT_PluginMonitor *pm);
952 #if 0 /* keep Emacsens' auto-indent happy */
959 /* ifndef GNUNET_TRANSPORT_SERVICE_H */
962 /** @} */ /* end of group */
964 /* end of gnunet_transport_service.h */