src/transport/gnunet-service-transport_ats.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2015 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  * @file transport/gnunet-service-transport_ats.h
  22  * @brief interfacing between transport and ATS service
  23  * @author Christian Grothoff
  24  */
  25 #ifndef GNUNET_SERVICE_TRANSPORT_ATS_H
  26 #define GNUNET_SERVICE_TRANSPORT_ATS_H
  27
  28 #include "gnunet_ats_service.h"
  29
  30 /**
  31  * Initialize ATS subsystem.
  32  */
  33 void
  34 GST_ats_init (void);
  35
  36
  37 /**
  38  * Shutdown ATS subsystem.
  39  */
  40 void
  41 GST_ats_done (void);
  42
  43
  44 /**
  45  * Test if ATS knows about this @a address and @a session.
  46  * Note that even if the address is expired, we return
  47  * #GNUNET_YES if the respective session matches.
  48  *
  49  * @param address the address
  50  * @param session the session
  51  * @return #GNUNET_YES if @a address is known, #GNUNET_NO if not.
  52  */
  53 int
  54 GST_ats_is_known (const struct GNUNET_HELLO_Address *address,
  55                   struct GNUNET_ATS_Session *session);
  56
  57
  58 /**
  59  * Test if ATS knows about this @a address.  Note that
  60  * expired addresses do not count.
  61  *
  62  * @param address the address
  63  * @return #GNUNET_YES if @a address is known, #GNUNET_NO if not.
  64  */
  65 int
  66 GST_ats_is_known_no_session (const struct GNUNET_HELLO_Address *address);
  67
  68
  69 /**
  70  * Temporarily block a valid address for use by ATS for address
  71  * suggestions.  This function should be called if an address was
  72  * suggested by ATS but failed to perform (i.e. failure to establish a
  73  * session or to exchange the PING/PONG).
  74  *
  75  * @param address the address to block
  76  * @param session the session (can be NULL)
  77  */
  78 void
  79 GST_ats_block_address (const struct GNUNET_HELLO_Address *address,
  80                        struct GNUNET_ATS_Session *session);
  81
  82
  83 /**
  84  * Reset address blocking time.  Resets the exponential
  85  * back-off timer for this address to zero.  Called when
  86  * an address was used to create a successful connection.
  87  *
  88  * @param address the address to reset the blocking timer
  89  * @param session the session (can be NULL)
  90  */
  91 void
  92 GST_ats_block_reset (const struct GNUNET_HELLO_Address *address,
  93                      struct GNUNET_ATS_Session *session);
  94
  95
  96 /**
  97  * Notify ATS about a new inbound @a address. The @a address in
  98  * combination with the @a session must be new, but this function will
  99  * perform a santiy check.  If the @a address is indeed new, make it
 100  * available to ATS.
 101  *
 102  * @param address the address
 103  * @param session the session
 104  * @param prop performance information
 105  */
 106 void
 107 GST_ats_add_inbound_address (const struct GNUNET_HELLO_Address *address,
 108                              struct GNUNET_ATS_Session *session,
 109                              const struct GNUNET_ATS_Properties *prop);
 110
 111
 112 /**
 113  * Notify ATS about a new address including the network this address is
 114  * located in.  The address must NOT be inbound and must be new to ATS.
 115  *
 116  * @param address the address
 117  * @param prop performance information
 118  */
 119 void
 120 GST_ats_add_address (const struct GNUNET_HELLO_Address *address,
 121                      const struct GNUNET_ATS_Properties *prop);
 122
 123
 124 /**
 125  * Notify ATS about a new @a session now existing for the given
 126  * @a address.  Essentially, an outbound @a address was used
 127  * to establish a @a session.  It is safe to call this function
 128  * repeatedly for the same @a address and @a session pair.
 129  *
 130  * @param address the address
 131  * @param session the session
 132  */
 133 void
 134 GST_ats_new_session (const struct GNUNET_HELLO_Address *address,
 135                      struct GNUNET_ATS_Session *session);
 136
 137
 138 /**
 139  * Notify ATS about utilization changes to an @a address.
 140  * Does nothing if the @a address is not known to us.
 141  *
 142  * @param address our information about the address
 143  * @param bps_in new utilization inbound
 144  * @param bps_out new utilization outbound
 145  */
 146 void
 147 GST_ats_update_utilization (const struct GNUNET_HELLO_Address *address,
 148                             uint32_t bps_in,
 149                             uint32_t bps_out);
 150
 151
 152 /**
 153  * Notify ATS about @a delay changes to properties of an @a address.
 154  * Does nothing if the @a address is not known to us.
 155  *
 156  * @param address the address
 157  * @param session the session
 158  * @param delay new delay value
 159  */
 160 void
 161 GST_ats_update_delay (const struct GNUNET_HELLO_Address *address,
 162                       struct GNUNET_TIME_Relative delay);
 163
 164
 165 /**
 166  * Notify ATS about DV @a distance change to an @a address.
 167  * Does nothing if the @a address is not known to us.
 168  *
 169  * @param address the address
 170  * @param distance new distance value
 171  */
 172 void
 173 GST_ats_update_distance (const struct GNUNET_HELLO_Address *address,
 174                          uint32_t distance);
 175
 176
 177 /**
 178  * Notify ATS that the @a session (but not the @a address) of
 179  * a given @a address is no longer relevant. (The @a session
 180  * went down.) This function may be called even if for the
 181  * respective outbound address #GST_ats_new_session() was
 182  * never called and thus the pair is unknown to ATS. In this
 183  * case, the call is simply ignored.
 184  *
 185  * @param address the address
 186  * @param session the session
 187  */
 188 void
 189 GST_ats_del_session (const struct GNUNET_HELLO_Address *address,
 190                      struct GNUNET_ATS_Session *session);
 191
 192
 193 /**
 194  * Notify ATS that the address has expired and thus cannot
 195  * be used any longer.  This function must only be called
 196  * if the corresponding session is already gone.
 197  *
 198  * @param address the address
 199  */
 200 void
 201 GST_ats_expire_address (const struct GNUNET_HELLO_Address *address);
 202
 203
 204 #endif