src/transport/gnunet-service-transport_ats.h

   1 /*
   2      This file is part of GNUnet.
   3      (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  * FIXME:
  26  * - add API to give ATS feedback about an address that was
  27  *   suggested but did not work out (without fully 'deleting'
  28  *   it forever)
  29  * - improve ATS API to take advantage of this new subsystem
  30  *   when calling ATS functions, make ATS API match this API
  31  *   more closely
  32  * - combine with API to tell ATS about address "use"
  33  */
  34 #ifndef GNUNET_SERVICE_TRANSPORT_ATS_H
  35 #define GNUNET_SERVICE_TRANSPORT_ATS_H
  36
  37 #include "gnunet_ats_service.h"
  38
  39 /**
  40  * Initialize ATS subsystem.
  41  */
  42 void
  43 GST_ats_init (void);
  44
  45
  46 /**
  47  * Shutdown ATS subsystem.
  48  */
  49 void
  50 GST_ats_done (void);
  51
  52
  53 /**
  54  * Test if ATS knows about this address.
  55  *
  56  * @param address the address
  57  * @param session the session
  58  * @return #GNUNET_YES if address is known, #GNUNET_NO if not.
  59  */
  60 int
  61 GST_ats_is_known (const struct GNUNET_HELLO_Address *address,
  62                   struct Session *session);
  63
  64 /**
  65  * Notify ATS about the new address including the network this address is
  66  * located in.
  67  *
  68  * @param address the address
  69  * @param session the session
  70  * @param ats ats information
  71  * @param ats_count number of @a ats information
  72  */
  73 void
  74 GST_ats_add_address (const struct GNUNET_HELLO_Address *address,
  75                      struct Session *session,
  76                      const struct GNUNET_ATS_Information *ats,
  77                      uint32_t ats_count);
  78
  79
  80 /**
  81  * Notify ATS about a new session now existing for the given
  82  * address.
  83  *
  84  * @param address the address
  85  * @param session the session
  86  */
  87 void
  88 GST_ats_new_session (const struct GNUNET_HELLO_Address *address,
  89                      struct Session *session);
  90
  91
  92 /**
  93  * Notify ATS about a new session now being in use (or not).
  94  *
  95  * @param address the address
  96  * @param session the session
  97  * @param in_use #GNUNET_YES or #GNUNET_NO
  98  */
  99 void
 100 GST_ats_set_in_use (const struct GNUNET_HELLO_Address *address,
 101                     struct Session *session,
 102                     int in_use);
 103
 104
 105 /**
 106  * Notify ATS about property changes to an address
 107  *
 108  * @param address the address
 109  * @param session the session
 110  * @param ats performance information
 111  * @param ats_count number of elements in @a ats
 112  */
 113 void
 114 GST_ats_update_metrics (const struct GNUNET_HELLO_Address *address,
 115                         struct Session *session,
 116                         const struct GNUNET_ATS_Information *ats,
 117                         uint32_t ats_count);
 118
 119
 120 /**
 121  * Notify ATS that the session (but not the address) of
 122  * a given address is no longer relevant.
 123  *
 124  * @param address the address
 125  * @param session the session
 126  */
 127 void
 128 GST_ats_del_session (const struct GNUNET_HELLO_Address *address,
 129                      struct Session *session);
 130
 131
 132 /**
 133  * Notify ATS that the address has expired and thus cannot
 134  * be used any longer.  This function must only be called
 135  * if the corresponding session is already gone.
 136  *
 137  * @param address the address
 138  */
 139 void
 140 GST_ats_expire_address (const struct GNUNET_HELLO_Address *address);
 141
 142
 143 #endif