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