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