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 /**
  19  * @file transport/gnunet-service-transport_ats.h
  20  * @brief interfacing between transport and ATS service
  21  * @author Christian Grothoff
  22  */
  23 #ifndef GNUNET_SERVICE_TRANSPORT_ATS_H
  24 #define GNUNET_SERVICE_TRANSPORT_ATS_H
  25
  26 #include "gnunet_ats_service.h"
  27
  28 /**
  29  * Initialize ATS subsystem.
  30  */
  31 void
  32 GST_ats_init (void);
  33
  34
  35 /**
  36  * Shutdown ATS subsystem.
  37  */
  38 void
  39 GST_ats_done (void);
  40
  41
  42 /**
  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.
  46  *
  47  * @param address the address
  48  * @param session the session
  49  * @return #GNUNET_YES if @a address is known, #GNUNET_NO if not.
  50  */
  51 int
  52 GST_ats_is_known (const struct GNUNET_HELLO_Address *address,
  53                   struct GNUNET_ATS_Session *session);
  54
  55
  56 /**
  57  * Test if ATS knows about this @a address.  Note that
  58  * expired addresses do not count.
  59  *
  60  * @param address the address
  61  * @return #GNUNET_YES if @a address is known, #GNUNET_NO if not.
  62  */
  63 int
  64 GST_ats_is_known_no_session (const struct GNUNET_HELLO_Address *address);
  65
  66
  67 /**
  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).
  72  *
  73  * @param address the address to block
  74  * @param session the session (can be NULL)
  75  */
  76 void
  77 GST_ats_block_address (const struct GNUNET_HELLO_Address *address,
  78                        struct GNUNET_ATS_Session *session);
  79
  80
  81 /**
  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.
  85  *
  86  * @param address the address to reset the blocking timer
  87  * @param session the session (can be NULL)
  88  */
  89 void
  90 GST_ats_block_reset (const struct GNUNET_HELLO_Address *address,
  91                      struct GNUNET_ATS_Session *session);
  92
  93
  94 /**
  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
  98  * available to ATS.
  99  *
 100  * @param address the address
 101  * @param session the session
 102  * @param prop performance information
 103  */
 104 void
 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);
 108
 109
 110 /**
 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.
 113  *
 114  * @param address the address
 115  * @param prop performance information
 116  */
 117 void
 118 GST_ats_add_address (const struct GNUNET_HELLO_Address *address,
 119                      const struct GNUNET_ATS_Properties *prop);
 120
 121
 122 /**
 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.
 127  *
 128  * @param address the address
 129  * @param session the session
 130  */
 131 void
 132 GST_ats_new_session (const struct GNUNET_HELLO_Address *address,
 133                      struct GNUNET_ATS_Session *session);
 134
 135
 136 /**
 137  * Notify ATS about utilization changes to an @a address.
 138  * Does nothing if the @a address is not known to us.
 139  *
 140  * @param address our information about the address
 141  * @param bps_in new utilization inbound
 142  * @param bps_out new utilization outbound
 143  */
 144 void
 145 GST_ats_update_utilization (const struct GNUNET_HELLO_Address *address,
 146                             uint32_t bps_in,
 147                             uint32_t bps_out);
 148
 149
 150 /**
 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.
 153  *
 154  * @param address the address
 155  * @param session the session
 156  * @param delay new delay value
 157  */
 158 void
 159 GST_ats_update_delay (const struct GNUNET_HELLO_Address *address,
 160                       struct GNUNET_TIME_Relative delay);
 161
 162
 163 /**
 164  * Notify ATS about DV @a distance change to an @a address.
 165  * Does nothing if the @a address is not known to us.
 166  *
 167  * @param address the address
 168  * @param distance new distance value
 169  */
 170 void
 171 GST_ats_update_distance (const struct GNUNET_HELLO_Address *address,
 172                          uint32_t distance);
 173
 174
 175 /**
 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.
 182  *
 183  * @param address the address
 184  * @param session the session
 185  */
 186 void
 187 GST_ats_del_session (const struct GNUNET_HELLO_Address *address,
 188                      struct GNUNET_ATS_Session *session);
 189
 190
 191 /**
 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.
 195  *
 196  * @param address the address
 197  */
 198 void
 199 GST_ats_expire_address (const struct GNUNET_HELLO_Address *address);
 200
 201
 202 #endif