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    * 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    * 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  * Internal representation of a preference by the plugin.
  99  * (If desired, plugin may just use NULL.)
 100  */
 101 struct GNUNET_ATS_PreferenceHandle;
 102
 103 /**
 104  * Internal representation of a session by the plugin.
 105  * (If desired, plugin may just use NULL.)
 106  */
 107 struct GNUNET_ATS_SessionHandle;
 108
 109
 110 /**
 111  * Solver functions.
 112  *
 113  * Each solver is required to set up and return an instance
 114  * of this struct during initialization.
 115  */
 116 struct GNUNET_ATS_SolverFunctions {
 117   /**
 118    * Closure to pass to all solver functions in this struct.
 119    */
 120   void *cls;
 121
 122   /**
 123    * The plugin should begin to respect a new preference.
 124    *
 125    * @param cls the closure
 126    * @param pref the preference to add
 127    * @return plugin's internal representation, or NULL
 128    */
 129   struct GNUNET_ATS_PreferenceHandle *
 130   (*preference_add)(void *cls,
 131                     const struct GNUNET_ATS_Preference *pref);
 132
 133   /**
 134    * The plugin should end respecting a preference.
 135    *
 136    * @param cls the closure
 137    * @param ph whatever @e preference_add returned
 138    * @param pref the preference to delete
 139    * @return plugin's internal representation, or NULL
 140    */
 141   void
 142   (*preference_del)(void *cls,
 143                     struct GNUNET_ATS_PreferenceHandle *ph,
 144                     const struct GNUNET_ATS_Preference *pref);
 145
 146   /**
 147    * Transport established a new session with performance
 148    * characteristics given in @a data.
 149    *
 150    * @param cls closure
 151    * @param data performance characteristics of @a sh
 152    * @param address address information (for debugging)
 153    * @return handle by which the plugin will identify this session
 154    */
 155   struct GNUNET_ATS_SessionHandle *
 156   (*session_add)(void *cls,
 157                  const struct GNUNET_ATS_SessionData *data,
 158                  const char *address);
 159
 160   /**
 161    * @a data changed for a given @a sh, solver should consider
 162    * the updated performance characteristics.
 163    *
 164    * @param cls closure
 165    * @param sh session this is about
 166    * @param data performance characteristics of @a sh
 167    */
 168   void
 169   (*session_update)(void *cls,
 170                     struct GNUNET_ATS_SessionHandle *sh,
 171                     const struct GNUNET_ATS_SessionData *data);
 172
 173   /**
 174    * A session went away. Solver should update accordingly.
 175    *
 176    * @param cls closure
 177    * @param sh session this is about
 178    * @param data (last) performance characteristics of @a sh
 179    */
 180   void
 181   (*session_del)(void *cls,
 182                  struct GNUNET_ATS_SessionHandle *sh,
 183                  const struct GNUNET_ATS_SessionData *data);
 184 };
 185
 186
 187 /**
 188  * The ATS plugin will pass a pointer to a struct
 189  * of this type as to the initialization function
 190  * of the ATS plugins.
 191  */
 192 struct GNUNET_ATS_PluginEnvironment {
 193   /**
 194    * Configuration handle to be used by the solver
 195    */
 196   const struct GNUNET_CONFIGURATION_Handle *cfg;
 197
 198   /**
 199    * Statistics handle to be used by the solver
 200    */
 201   struct GNUNET_STATISTICS_Handle *stats;
 202
 203   /**
 204    * Closure to pass to all callbacks in this struct.
 205    */
 206   void *cls;
 207
 208   /**
 209    * Suggest to the transport that it should try establishing
 210    * a connection using the given address.
 211    *
 212    * @param cls closure, NULL
 213    * @param pid peer this is about
 214    * @param address address the transport should try
 215    */
 216   void
 217   (*suggest_cb) (void *cls,
 218                  const struct GNUNET_PeerIdentity *pid,
 219                  const char *address);
 220
 221   /**
 222    * Tell the transport that it should allocate the given
 223    * bandwidth to the specified session.
 224    *
 225    * @param cls closure, NULL
 226    * @param session session this is about
 227    * @param peer peer this is about
 228    * @param bw_in suggested bandwidth for receiving
 229    * @param bw_out suggested bandwidth for transmission
 230    */
 231   void
 232   (*allocate_cb) (void *cls,
 233                   struct GNUNET_ATS_Session *session,
 234                   const struct GNUNET_PeerIdentity *peer,
 235                   struct GNUNET_BANDWIDTH_Value32NBO bw_in,
 236                   struct GNUNET_BANDWIDTH_Value32NBO bw_out);
 237 };
 238
 239
 240
 241 #endif
 242
 243 /** @} */  /* end of group */