src/ats/gnunet-service-ats_plugins.h

   1 /*
   2  This file is part of GNUnet.
   3  Copyright (C) 2011-2014 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  * @file ats/gnunet-service-ats_plugins.h
  21  * @brief ats service plugin management
  22  * @author Matthias Wachs
  23  * @author Christian Grothoff
  24  */
  25 #ifndef GNUNET_SERVICE_ATS_PLUGINS_H
  26 #define GNUNET_SERVICE_ATS_PLUGINS_H
  27
  28 #include "gnunet-service-ats_addresses.h"
  29
  30
  31 /**
  32  * Initialize address subsystem. The addresses subsystem manages the addresses
  33  * known and current performance information. It has a solver component
  34  * responsible for the resource allocation. It tells the solver about changes
  35  * and receives updates when the solver changes the ressource allocation.
  36  *
  37  * @param cfg configuration to use
  38  * @return #GNUNET_OK on success, #GNUNET_SYSERR on error (failed to load
  39  *         solver plugin)
  40  */
  41 int
  42 GAS_plugin_init (const struct GNUNET_CONFIGURATION_Handle *cfg);
  43
  44
  45 /**
  46  * Shutdown address subsystem.
  47  */
  48 void
  49 GAS_plugin_done (void);
  50
  51
  52 /**
  53  * The preference changed for a peer, update solver.
  54  *
  55  * @param peer the peer
  56  * @param kind the ATS kind
  57  * @param pref_rel the new relative preference value
  58  */
  59 void
  60 GAS_plugin_notify_preference_changed (const struct GNUNET_PeerIdentity *peer,
  61                                       enum GNUNET_ATS_PreferenceKind kind,
  62                                       double pref_rel);
  63
  64
  65 /**
  66  * The relative value for a property changed.
  67  *
  68  * @param address the peer
  69  */
  70 void
  71 GAS_plugin_notify_property_changed (struct ATS_Address *address);
  72
  73
  74 /**
  75  * Tell the solver that the given address can now be used
  76  * for talking to the respective peer.
  77  *
  78  * @param new_address the new address
  79  * @param addr_net network scope the address is in
  80  */
  81 void
  82 GAS_plugin_new_address (struct ATS_Address *new_address);
  83
  84
  85 /**
  86  * Tell the solver that the given address is no longer valid
  87  * can cannot be used any longer.
  88  *
  89  * @param address address that was deleted
  90  */
  91 void
  92 GAS_plugin_delete_address (struct ATS_Address *address);
  93
  94
  95 /**
  96  * Tell the solver that the given client has expressed its
  97  * appreciation for the past performance of a given connection.
  98  *
  99  * @param application client providing the feedback
 100  * @param peer peer the feedback is about
 101  * @param scope timeframe the feedback applies to
 102  * @param kind performance property the feedback relates to
 103  * @param score_abs degree of the appreciation
 104  */
 105 void
 106 GAS_plugin_notify_feedback (struct GNUNET_SERVICE_Client *application,
 107                             const struct GNUNET_PeerIdentity *peer,
 108                             const struct GNUNET_TIME_Relative scope,
 109                             enum GNUNET_ATS_PreferenceKind kind,
 110                             float score_abs);
 111
 112
 113 /**
 114  * Stop instant solving, there are many state updates
 115  * happening in bulk right now.
 116  */
 117 void
 118 GAS_plugin_solver_lock (void);
 119
 120
 121 /**
 122  * Resume instant solving, we are done with the bulk state updates.
 123  */
 124 void
 125 GAS_plugin_solver_unlock (void);
 126
 127
 128 /**
 129  * Notify the plugin that a request to connect to
 130  * a particular peer was given to us.
 131  *
 132  * @param pid identity of peer we now care about
 133  */
 134 void
 135 GAS_plugin_request_connect_start (const struct GNUNET_PeerIdentity *pid);
 136
 137
 138 /**
 139  * Notify the plugin that a request to connect to
 140  * a particular peer was dropped.
 141  *
 142  * @param pid identity of peer we care now less about
 143  */
 144 void
 145 GAS_plugin_request_connect_stop (const struct GNUNET_PeerIdentity *pid);
 146
 147
 148 #endif