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