src/include/gnunet_ats_plugin_new.h

   1 /*
   2  This file is part of GNUnet
   3  Copyright (C) 2009-2015, 2018 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  You should have received a copy of the GNU Affero General Public License
  16  along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * API for the ATS solvers.
  26  *
  27  * @defgroup ats-plugin  ATS service plugin API
  28  * Plugin API for the ATS service.
  29  *
  30  * Specifies the struct that is given to the plugin's entry method and the other
  31  * struct that must be returned.  Note that the destructors of ATS plugins will
  32  * be given the value returned by the constructor and is expected to return a
  33  * NULL pointer.
  34  *
  35  * @{
  36  */
  37 #ifndef PLUGIN_ATS_H
  38 #define PLUGIN_ATS_H
  39
  40 #include "gnunet_util_lib.h"
  41 #include "gnunet_ats_application_service.h"
  42 #include "gnunet_ats_transport_service.h"
  43 #include "gnunet_statistics_service.h"
  44
  45
  46 /**
  47  * Preference being expressed by an application client.
  48  */
  49 struct GNUNET_ATS_Preference {
  50
  51   /**
  52    * Peer to get address suggestions for.
  53    */
  54   struct GNUNET_PeerIdentity peer;
  55
  56   /**
  57    * How much bandwidth in bytes/second does the application expect?
  58    */
  59   struct GNUNET_BANDWIDTH_Value32NBO bw;
  60
  61   /**
  62    * What type of performance preference does the client have?
  63    */
  64   enum GNUNET_MQ_PreferenceKind pk;
  65 };
  66
  67
  68 /**
  69  * Opaque representation of a session the plugin can allocate bandwidth for.
  70  */
  71 struct GNUNET_ATS_Session;
  72
  73 /**
  74  * Plugin-relevant information about a session.
  75  */
  76 struct GNUNET_ATS_SessionData {
  77
  78   /**
  79    * Peer the session is with.
  80    */
  81   struct GNUNET_PeerIdentity peer;
  82
  83   /**
  84    * ATS performance characteristics for a session.
  85    */
  86   struct GNUNET_ATS_Properties prop;
  87
  88   /**
  89    * Handle to the session that has the given properties.
  90    */
  91   struct GNUNET_ATS_Session *session;
  92
  93   /**
  94    * Is the session inbound only?
  95    */
  96   int inbound_only;
  97
  98 };
  99
 100 /**
 101  * Internal representation of a preference by the plugin.
 102  * (If desired, plugin may just use NULL.)
 103  */
 104 struct GNUNET_ATS_PreferenceHandle;
 105
 106 /**
 107  * Internal representation of a session by the plugin.
 108  * (If desired, plugin may just use NULL.)
 109  */
 110 struct GNUNET_ATS_SessionHandle;
 111
 112
 113 /**
 114  * Solver functions.
 115  *
 116  * Each solver is required to set up and return an instance
 117  * of this struct during initialization.
 118  */
 119 struct GNUNET_ATS_SolverFunctions
 120 {
 121
 122   /**
 123    * Closure to pass to all solver functions in this struct.
 124    */
 125   void *cls;
 126
 127   /**
 128    * The plugin should begin to respect a new preference.
 129    *
 130    * @param cls the closure
 131    * @param pref the preference to add
 132    * @return plugin's internal representation, or NULL
 133    */
 134   struct GNUNET_ATS_PreferenceHandle *
 135   (*preference_add)(void *cls,
 136                     const struct GNUNET_ATS_Preference *pref);
 137
 138   /**
 139    * The plugin should end respecting a preference.
 140    *
 141    * @param cls the closure
 142    * @param ph whatever @e preference_add returned
 143    * @param pref the preference to delete
 144    * @return plugin's internal representation, or NULL
 145    */
 146   void
 147   (*preference_del)(void *cls,
 148                     struct GNUNET_ATS_PreferenceHandle *ph,
 149                     const struct GNUNET_ATS_Preference *pref);
 150
 151   /**
 152    * Transport established a new session with performance
 153    * characteristics given in @a data.
 154    *
 155    * @param cls closure
 156    * @param data performance characteristics of @a sh
 157    * @param address address information (for debugging)
 158    * @return handle by which the plugin will identify this session
 159    */
 160   struct GNUNET_ATS_SessionHandle *
 161   (*session_add)(void *cls,
 162                  const struct GNUNET_ATS_SessionData *data,
 163                  const char *address);
 164
 165   /**
 166    * @a data changed for a given @a sh, solver should consider
 167    * the updated performance characteristics.
 168    *
 169    * @param cls closure
 170    * @param sh session this is about
 171    * @param data performance characteristics of @a sh
 172    */
 173   void
 174   (*session_update)(void *cls,
 175                     struct GNUNET_ATS_SessionHandle *sh,
 176                     const struct GNUNET_ATS_SessionData *data);
 177
 178   /**
 179    * A session went away. Solver should update accordingly.
 180    *
 181    * @param cls closure
 182    * @param sh session this is about
 183    * @param data (last) performance characteristics of @a sh
 184    */
 185   void
 186   (*session_del)(void *cls,
 187                  struct GNUNET_ATS_SessionHandle *sh,
 188                  const struct GNUNET_ATS_SessionData *data);
 189
 190 };
 191
 192
 193 /**
 194  * The ATS plugin will pass a pointer to a struct
 195  * of this type as to the initialization function
 196  * of the ATS plugins.
 197  */
 198 struct GNUNET_ATS_PluginEnvironment
 199 {
 200   /**
 201    * Configuration handle to be used by the solver
 202    */
 203   const struct GNUNET_CONFIGURATION_Handle *cfg;
 204
 205   /**
 206    * Statistics handle to be used by the solver
 207    */
 208   struct GNUNET_STATISTICS_Handle *stats;
 209
 210   /**
 211    * Closure to pass to all callbacks in this struct.
 212    */
 213   void *cls;
 214
 215   /**
 216    * Suggest to the transport that it should try establishing
 217    * a connection using the given address.
 218    *
 219    * @param cls closure, NULL
 220    * @param pid peer this is about
 221    * @param address address the transport should try
 222    */
 223   void
 224   (*suggest_cb) (void *cls,
 225                  const struct GNUNET_PeerIdentity *pid,
 226                  const char *address);
 227
 228   /**
 229    * Tell the transport that it should allocate the given
 230    * bandwidth to the specified session.
 231    *
 232    * @param cls closure, NULL
 233    * @param session session this is about
 234    * @param peer peer this is about
 235    * @param bw_in suggested bandwidth for receiving
 236    * @param bw_out suggested bandwidth for transmission
 237    */
 238   void
 239   (*allocate_cb) (void *cls,
 240                   struct GNUNET_ATS_Session *session,
 241                   const struct GNUNET_PeerIdentity *peer,
 242                   struct GNUNET_BANDWIDTH_Value32NBO bw_in,
 243                   struct GNUNET_BANDWIDTH_Value32NBO bw_out);
 244
 245 };
 246
 247
 248
 249 #endif
 250
 251 /** @} */  /* end of group */