src/transport/gnunet-service-transport_ats.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2015 Christian Grothoff (and other contributing authors)
   4
   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.
   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      General Public License for more details.
  14
  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., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  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 address.
  46  *
  47  * @param address the address
  48  * @param session the session
  49  * @return #GNUNET_YES if address is known, #GNUNET_NO if not.
  50  */
  51 int
  52 GST_ats_is_known (const struct GNUNET_HELLO_Address *address,
  53                   struct Session *session);
  54
  55
  56 /**
  57  * Temporarily block a valid address for use by ATS for address
  58  * suggestions.  This function should be called if an address was
  59  * suggested by ATS but failed to perform (i.e. failure to establish a
  60  * session or to exchange the PING/PONG).
  61  *
  62  * @param address the address to block
  63  * @param session the session (can be NULL)
  64  */
  65 void
  66 GST_ats_block_address (const struct GNUNET_HELLO_Address *address,
  67                        struct Session *session);
  68
  69
  70 /**
  71  * Reset address blocking time.  Resets the exponential
  72  * back-off timer for this address to zero.  Done when
  73  * an address was used to create a successful connection.
  74  *
  75  * @param address the address to reset the blocking timer
  76  * @param session the session (can be NULL)
  77  */
  78 void
  79 GST_ats_block_reset (const struct GNUNET_HELLO_Address *address,
  80                      struct Session *session);
  81
  82
  83 /**
  84  * Notify ATS about the a new inbound address.  We may already
  85  * know the address (as this is called each time we receive
  86  * a message from an inbound connection).  If the address is
  87  * indeed new, make it available to ATS.
  88  *
  89  * @param address the address
  90  * @param session the session
  91  * @param prop performance information
  92  */
  93 void
  94 GST_ats_add_inbound_address (const struct GNUNET_HELLO_Address *address,
  95                              struct Session *session,
  96                              const struct GNUNET_ATS_Properties *prop);
  97
  98
  99 /**
 100  * Notify ATS about the new address including the network this address is
 101  * located in.  The address must NOT be inbound and must be new to ATS.
 102  *
 103  * @param address the address
 104  * @param prop performance information
 105  */
 106 void
 107 GST_ats_add_address (const struct GNUNET_HELLO_Address *address,
 108                      const struct GNUNET_ATS_Properties *prop);
 109
 110
 111 /**
 112  * Notify ATS about a new session now existing for the given
 113  * address.
 114  *
 115  * @param address the address
 116  * @param session the session
 117  */
 118 void
 119 GST_ats_new_session (const struct GNUNET_HELLO_Address *address,
 120                      struct Session *session);
 121
 122
 123 /**
 124  * Notify ATS about property changes to an address's properties.
 125  * FIXME: we probably want to split this one up for the different
 126  * updatable properties.
 127  *
 128  * @param address the address
 129  * @param session the session
 130  * @param prop updated performance information
 131  */
 132 void
 133 GST_ats_update_metrics (const struct GNUNET_HELLO_Address *address,
 134                         struct Session *session,
 135                         const struct GNUNET_ATS_Properties *prop);
 136
 137
 138 /**
 139  * Notify ATS about utilization changes to an address.
 140  *
 141  * @param address our information about the address
 142  * @param bps_in new utilization inbound
 143  * @param bps_out new utilization outbound
 144  */
 145 void
 146 GST_ats_update_utilization (const struct GNUNET_HELLO_Address *address,
 147                             uint32_t bps_in,
 148                             uint32_t bps_out);
 149
 150
 151 /**
 152  * Notify ATS about property changes to an address's properties.
 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 property changes to an address's properties.
 165  *
 166  * @param address the address
 167  * @param distance new distance value
 168  */
 169 void
 170 GST_ats_update_distance (const struct GNUNET_HELLO_Address *address,
 171                          uint32_t distance);
 172
 173
 174 /**
 175  * Notify ATS that the session (but not the address) of
 176  * a given address is no longer relevant.
 177  *
 178  * @param address the address
 179  * @param session the session
 180  */
 181 void
 182 GST_ats_del_session (const struct GNUNET_HELLO_Address *address,
 183                      struct Session *session);
 184
 185
 186 /**
 187  * Notify ATS that the address has expired and thus cannot
 188  * be used any longer.  This function must only be called
 189  * if the corresponding session is already gone.
 190  *
 191  * @param address the address
 192  */
 193 void
 194 GST_ats_expire_address (const struct GNUNET_HELLO_Address *address);
 195
 196
 197 #endif