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