src/include/gnunet_ats_application_service.h

   1 /*
   2    This file is part of GNUnet.
   3    Copyright (C) 2010-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  * @file
  22  * Bandwidth allocation API for applications to interact with
  23  *
  24  * @author Christian Grothoff
  25  * @author Matthias Wachs
  26  *
  27  * @defgroup ats  ATS service
  28  * Bandwidth allocation
  29  *
  30  * @see [Documentation](https://gnunet.org/ats-subsystem)
  31  *
  32  * @{
  33  */
  34 #ifndef GNUNET_ATS_APPLICATION_SERVICE_H
  35 #define GNUNET_ATS_APPLICATION_SERVICE_H
  36
  37 #include "gnunet_constants.h"
  38 #include "gnunet_util_lib.h"
  39
  40 /**
  41  * Handle to the ATS subsystem for making suggestions about
  42  * connections the peer would like to have.
  43  */
  44 struct GNUNET_ATS_ApplicationHandle;
  45
  46
  47 /**
  48  * Initialize the ATS application client handle.
  49  *
  50  * @param cfg configuration to use
  51  * @return ats application handle, NULL on error
  52  */
  53 struct GNUNET_ATS_ApplicationHandle *
  54 GNUNET_ATS_application_init (const struct GNUNET_CONFIGURATION_Handle *cfg);
  55
  56
  57 /**
  58  * Shutdown ATS application client.
  59  *
  60  * @param ch handle to destroy
  61  */
  62 void
  63 GNUNET_ATS_application_done (struct GNUNET_ATS_ApplicationHandle *ch);
  64
  65
  66 /**
  67  * Handle for suggestion requests.
  68  */
  69 struct GNUNET_ATS_ApplicationSuggestHandle;
  70
  71
  72 /**
  73  * An application would like to communicate with a peer.  ATS should
  74  * allocate bandwith using a suitable address for requiremetns @a pk
  75  * to transport.
  76  *
  77  * @param ch handle
  78  * @param peer identity of the peer we need an address for
  79  * @param pk what kind of application will the application require (can be
  80  *         #GNUNET_MQ_PREFERENCE_NONE, we will still try to connect)
  81  * @param bw desired bandwith, can be zero (we will still try to connect)
  82  * @return suggestion handle, NULL if request is already pending
  83  */
  84 struct GNUNET_ATS_ApplicationSuggestHandle *
  85 GNUNET_ATS_application_suggest (struct GNUNET_ATS_ApplicationHandle *ch,
  86                                 const struct GNUNET_PeerIdentity *peer,
  87                                 enum GNUNET_MQ_PreferenceKind pk,
  88                                 struct GNUNET_BANDWIDTH_Value32NBO bw);
  89
  90
  91 /**
  92  * We no longer care about communicating with a peer.
  93  *
  94  * @param sh handle
  95  */
  96 void
  97 GNUNET_ATS_application_suggest_cancel (struct
  98                                        GNUNET_ATS_ApplicationSuggestHandle *sh);
  99
 100 /** @} */  /* end of group */
 101
 102 #endif
 103 /* end of file gnunet_ats_application_service.h */