2 This file is part of GNUnet.
3 Copyright (C) 2015 GNUnet e.V.
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.
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.
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/>.
19 * @file transport/gnunet-service-transport_ats.h
20 * @brief interfacing between transport and ATS service
21 * @author Christian Grothoff
23 #ifndef GNUNET_SERVICE_TRANSPORT_ATS_H
24 #define GNUNET_SERVICE_TRANSPORT_ATS_H
26 #include "gnunet_ats_service.h"
29 * Initialize ATS subsystem.
36 * Shutdown ATS subsystem.
43 * Test if ATS knows about this @a address and @a session.
44 * Note that even if the address is expired, we return
45 * #GNUNET_YES if the respective session matches.
47 * @param address the address
48 * @param session the session
49 * @return #GNUNET_YES if @a address is known, #GNUNET_NO if not.
52 GST_ats_is_known (const struct GNUNET_HELLO_Address *address,
53 struct GNUNET_ATS_Session *session);
57 * Test if ATS knows about this @a address. Note that
58 * expired addresses do not count.
60 * @param address the address
61 * @return #GNUNET_YES if @a address is known, #GNUNET_NO if not.
64 GST_ats_is_known_no_session (const struct GNUNET_HELLO_Address *address);
68 * Temporarily block a valid address for use by ATS for address
69 * suggestions. This function should be called if an address was
70 * suggested by ATS but failed to perform (i.e. failure to establish a
71 * session or to exchange the PING/PONG).
73 * @param address the address to block
74 * @param session the session (can be NULL)
77 GST_ats_block_address (const struct GNUNET_HELLO_Address *address,
78 struct GNUNET_ATS_Session *session);
82 * Reset address blocking time. Resets the exponential
83 * back-off timer for this address to zero. Called when
84 * an address was used to create a successful connection.
86 * @param address the address to reset the blocking timer
87 * @param session the session (can be NULL)
90 GST_ats_block_reset (const struct GNUNET_HELLO_Address *address,
91 struct GNUNET_ATS_Session *session);
95 * Notify ATS about a new inbound @a address. The @a address in
96 * combination with the @a session must be new, but this function will
97 * perform a santiy check. If the @a address is indeed new, make it
100 * @param address the address
101 * @param session the session
102 * @param prop performance information
105 GST_ats_add_inbound_address (const struct GNUNET_HELLO_Address *address,
106 struct GNUNET_ATS_Session *session,
107 const struct GNUNET_ATS_Properties *prop);
111 * Notify ATS about a new address including the network this address is
112 * located in. The address must NOT be inbound and must be new to ATS.
114 * @param address the address
115 * @param prop performance information
118 GST_ats_add_address (const struct GNUNET_HELLO_Address *address,
119 const struct GNUNET_ATS_Properties *prop);
123 * Notify ATS about a new @a session now existing for the given
124 * @a address. Essentially, an outbound @a address was used
125 * to establish a @a session. It is safe to call this function
126 * repeatedly for the same @a address and @a session pair.
128 * @param address the address
129 * @param session the session
132 GST_ats_new_session (const struct GNUNET_HELLO_Address *address,
133 struct GNUNET_ATS_Session *session);
137 * Notify ATS about utilization changes to an @a address.
138 * Does nothing if the @a address is not known to us.
140 * @param address our information about the address
141 * @param bps_in new utilization inbound
142 * @param bps_out new utilization outbound
145 GST_ats_update_utilization (const struct GNUNET_HELLO_Address *address,
151 * Notify ATS about @a delay changes to properties of an @a address.
152 * Does nothing if the @a address is not known to us.
154 * @param address the address
155 * @param session the session
156 * @param delay new delay value
159 GST_ats_update_delay (const struct GNUNET_HELLO_Address *address,
160 struct GNUNET_TIME_Relative delay);
164 * Notify ATS about DV @a distance change to an @a address.
165 * Does nothing if the @a address is not known to us.
167 * @param address the address
168 * @param distance new distance value
171 GST_ats_update_distance (const struct GNUNET_HELLO_Address *address,
176 * Notify ATS that the @a session (but not the @a address) of
177 * a given @a address is no longer relevant. (The @a session
178 * went down.) This function may be called even if for the
179 * respective outbound address #GST_ats_new_session() was
180 * never called and thus the pair is unknown to ATS. In this
181 * case, the call is simply ignored.
183 * @param address the address
184 * @param session the session
187 GST_ats_del_session (const struct GNUNET_HELLO_Address *address,
188 struct GNUNET_ATS_Session *session);
192 * Notify ATS that the address has expired and thus cannot
193 * be used any longer. This function must only be called
194 * if the corresponding session is already gone.
196 * @param address the address
199 GST_ats_expire_address (const struct GNUNET_HELLO_Address *address);