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