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 /* FIXME: might want to add a function to reset the
  71    back-off from blocking */
  72
  73 /**
  74  * Notify ATS about the a new inbound address.  We may already
  75  * know the address (as this is called each time we receive
  76  * a message from an inbound connection).  If the address is
  77  * indeed new, make it available to ATS.
  78  *
  79  * @param address the address
  80  * @param session the session
  81  * @param ats ats information
  82  * @param ats_count number of @a ats information
  83  */
  84 void
  85 GST_ats_add_inbound_address (const struct GNUNET_HELLO_Address *address,
  86                              struct Session *session,
  87                              const struct GNUNET_ATS_Information *ats,
  88                              uint32_t ats_count);
  89
  90
  91 /**
  92  * Notify ATS about the new address including the network this address is
  93  * located in.  The address must NOT be inbound and must be new to ATS.
  94  *
  95  * @param address the address
  96  * @param ats ats information
  97  * @param ats_count number of @a ats information
  98  */
  99 void
 100 GST_ats_add_address (const struct GNUNET_HELLO_Address *address,
 101                      const struct GNUNET_ATS_Information *ats,
 102                      uint32_t ats_count);
 103
 104
 105 /**
 106  * Notify ATS about a new session now existing for the given
 107  * address.
 108  *
 109  * @param address the address
 110  * @param session the session
 111  */
 112 void
 113 GST_ats_new_session (const struct GNUNET_HELLO_Address *address,
 114                      struct Session *session);
 115
 116
 117 /**
 118  * Notify ATS about property changes to an address
 119  *
 120  * @param address the address
 121  * @param session the session
 122  * @param ats performance information
 123  * @param ats_count number of elements in @a ats
 124  */
 125 void
 126 GST_ats_update_metrics (const struct GNUNET_HELLO_Address *address,
 127                         struct Session *session,
 128                         const struct GNUNET_ATS_Information *ats,
 129                         uint32_t ats_count);
 130
 131
 132 /**
 133  * Notify ATS that the session (but not the address) of
 134  * a given address is no longer relevant.
 135  *
 136  * @param address the address
 137  * @param session the session
 138  */
 139 void
 140 GST_ats_del_session (const struct GNUNET_HELLO_Address *address,
 141                      struct Session *session);
 142
 143
 144 /**
 145  * Notify ATS that the address has expired and thus cannot
 146  * be used any longer.  This function must only be called
 147  * if the corresponding session is already gone.
 148  *
 149  * @param address the address
 150  */
 151 void
 152 GST_ats_expire_address (const struct GNUNET_HELLO_Address *address);
 153
 154
 155 #endif