src/include/gnunet_transport_application_service.h

   1 /*
   2    This file is part of GNUnet.
   3    Copyright (C) 2010-2015, 2018, 2019 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 TRANSPORT service
  28  * Bandwidth allocation
  29  *
  30  * @{
  31  */
  32 #ifndef GNUNET_TRANSPORT_APPLICATION_SERVICE_H
  33 #define GNUNET_TRANSPORT_APPLICATION_SERVICE_H
  34
  35 #include "gnunet_constants.h"
  36 #include "gnunet_util_lib.h"
  37 #include "gnunet_nt_lib.h"
  38
  39 /**
  40  * Handle to the TRANSPORT subsystem for making suggestions about
  41  * connections the peer would like to have.
  42  */
  43 struct GNUNET_TRANSPORT_ApplicationHandle;
  44
  45
  46 /**
  47  * Initialize the TRANSPORT application client handle.
  48  *
  49  * @param cfg configuration to use
  50  * @return ats application handle, NULL on error
  51  */
  52 struct GNUNET_TRANSPORT_ApplicationHandle *
  53 GNUNET_TRANSPORT_application_init (
  54   const struct GNUNET_CONFIGURATION_Handle *cfg);
  55
  56
  57 /**
  58  * Shutdown TRANSPORT application client.
  59  *
  60  * @param ch handle to destroy
  61  */
  62 void
  63 GNUNET_TRANSPORT_application_done (
  64   struct GNUNET_TRANSPORT_ApplicationHandle *ch);
  65
  66
  67 /**
  68  * An application would like TRANSPORT to connect to a peer.
  69  *
  70  * @param ch handle
  71  * @param peer identity of the peer we need an address for
  72  * @param pk what kind of application will the application require (can be
  73  *         #GNUNET_MQ_PRIO_BACKGROUND, we will still try to connect)
  74  * @param bw desired bandwith, can be zero (we will still try to connect)
  75  * @return suggest handle, NULL if a request is already pending
  76  */
  77 struct GNUNET_TRANSPORT_ApplicationSuggestHandle *
  78 GNUNET_TRANSPORT_application_suggest (
  79   struct GNUNET_TRANSPORT_ApplicationHandle *ch,
  80   const struct GNUNET_PeerIdentity *peer,
  81   enum GNUNET_MQ_PriorityPreferences pk,
  82   struct GNUNET_BANDWIDTH_Value32NBO bw);
  83
  84
  85 /**
  86  * We no longer care about being connected to a peer.
  87  *
  88  * @param sh handle to stop
  89  */
  90 void
  91 GNUNET_TRANSPORT_application_suggest_cancel (
  92   struct GNUNET_TRANSPORT_ApplicationSuggestHandle *sh);
  93
  94
  95 /**
  96  * An application (or a communicator) has received a HELLO (or other address
  97  * data of another peer) and wants TRANSPORT to validate that the address is
  98  * correct.  The result is NOT returned, in fact TRANSPORT may do nothing
  99  * (i.e. if it has too many active validations or recently tried this one
 100  * already).  If the @a addr validates, TRANSPORT will persist the address
 101  * with PEERSTORE.
 102  *
 103  * @param ch handle
 104  * @param peer identity of the peer we have an address for
 105  * @param nt network type of @a addr (as claimed by the other peer);
 106  *        used by TRANSPORT to avoid trying @a addr's that really cannot work
 107  *        due to network type missmatches
 108  * @param addr address to validate
 109  */
 110 void
 111 GNUNET_TRANSPORT_application_validate (
 112   struct GNUNET_TRANSPORT_ApplicationHandle *ch,
 113   const struct GNUNET_PeerIdentity *peer,
 114   enum GNUNET_NetworkType nt,
 115   const char *addr);
 116
 117 /** @} */ /* end of group */
 118
 119 #endif
 120 /* end of file gnunet_ats_application_service.h */