src/include/gnunet_transport_core_service.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-2016 GNUnet e.V.
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20 /**
  21  * @author Christian Grothoff
  22  *
  23  * @file
  24  * API of the transport service towards the CORE service.
  25  *
  26  * @defgroup transport TRANSPORT service
  27  * Communication with other peers
  28  *
  29  * @see [Documentation](https://gnunet.org/transport-service)
  30  *
  31  * @{
  32  */
  33 #ifndef GNUNET_TRANSPORT_CORE_SERVICE_H
  34 #define GNUNET_TRANSPORT_CORE_SERVICE_H
  35
  36 #ifdef __cplusplus
  37 extern "C"
  38 {
  39 #if 0                           /* keep Emacsens' auto-indent happy */
  40 }
  41 #endif
  42 #endif
  43
  44 #include "gnunet_util_lib.h"
  45
  46 /**
  47  * Version number of the transport API.
  48  */
  49 #define GNUNET_TRANSPORT_CORE_VERSION 0x00000000
  50
  51
  52 /**
  53  * Function called by the transport for each received message.
  54  *
  55  * @param cls closure
  56  * @param peer (claimed) identity of the other peer
  57  * @param message the message
  58  */
  59 typedef void
  60 (*GNUNET_TRANSPORT_ReceiveCallback) (void *cls,
  61                                      const struct GNUNET_PeerIdentity *peer,
  62                                      const struct GNUNET_MessageHeader *message);
  63
  64
  65 /**
  66  * Opaque handle to the service.
  67  */
  68 struct GNUNET_TRANSPORT_Handle;
  69
  70
  71 /**
  72  * Function called to notify CORE service that another
  73  * @a peer connected to us.
  74  *
  75  * @param cls closure
  76  * @param peer the peer that connected, never NULL
  77  * @param mq message queue for sending messages to this peer
  78  */
  79 typedef void
  80 (*GNUNET_TRANSPORT_NotifyConnect) (void *cls,
  81                                    const struct GNUNET_PeerIdentity *peer,
  82                                    struct GNUNET_MQ_Handle *mq);
  83
  84
  85 /**
  86  * Function called to notify CORE service that another
  87  * @a peer disconnected from us.  The associated message
  88  * queue must not be used henceforth.
  89  *
  90  * @param cls closure
  91  * @param peer the peer that disconnected, never NULL
  92  */
  93 typedef void
  94 (*GNUNET_TRANSPORT_NotifyDisconnect) (void *cls,
  95                                       const struct GNUNET_PeerIdentity *peer);
  96
  97
  98 /**
  99  * Function called if we have "excess" bandwidth to a peer.
 100  * The notification will happen the first time we have excess
 101  * bandwidth, and then only again after the client has performed
 102  * some transmission to the peer.
 103  *
 104  * Excess bandwidth is defined as being allowed (by ATS) to send
 105  * more data, and us reaching the limit of the capacity build-up
 106  * (which, if we go past it, means we don't use available bandwidth).
 107  * See also the "max carry" in `struct GNUNET_BANDWIDTH_Tracker`.
 108  *
 109  * @param cls the closure
 110  * @param neighbour peer that we have excess bandwidth to
 111  */
 112 typedef void
 113 (*GNUNET_TRANSPORT_NotifyExcessBandwidth)(void *cls,
 114                                           const struct GNUNET_PeerIdentity *neighbour);
 115
 116
 117 /**
 118  * Connect to the transport service.
 119  *
 120  * @param cfg configuration to use
 121  * @param self our own identity (if API should check that it matches
 122  *             the identity found by transport), or NULL (no check)
 123  * @param cls closure for the callbacks
 124  * @param rec_handlers NULL-terminated array of handlers for incoming
 125  *                     messages, or NULL
 126  * @param nc function to call on connect events, or NULL
 127  * @param nd function to call on disconnect events, or NULL
 128  * @param neb function to call if we have excess bandwidth to a peer
 129  * @return NULL on error
 130  */
 131 struct GNUNET_TRANSPORT_Handle *
 132 GNUNET_TRANSPORT_core_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
 133                                const struct GNUNET_PeerIdentity *self,
 134                                void *cls,
 135                                GNUNET_MQ_MessageHandler *rec_handlers,
 136                                GNUNET_TRANSPORT_NotifyConnect nc,
 137                                GNUNET_TRANSPORT_NotifyDisconnect nd,
 138                                GNUNET_TRANSPORT_NotifyExcessBandwidth neb);
 139
 140
 141 /**
 142  * Disconnect from the transport service.
 143  *
 144  * @param handle handle returned from connect
 145  */
 146 void
 147 GNUNET_TRANSPORT_disconnect (struct GNUNET_TRANSPORT_Handle *handle);
 148
 149
 150 /**
 151  * Checks if a given peer is connected to us. Convenience
 152  * API in case a client does not track connect/disconnect
 153  * events internally.
 154  *
 155  * @param handle connection to transport service
 156  * @param peer the peer to check
 157  * @return #GNUNET_YES (connected) or #GNUNET_NO (disconnected)
 158  */
 159 int
 160 GNUNET_TRANSPORT_check_peer_connected (struct GNUNET_TRANSPORT_Handle *handle,
 161                                        const struct GNUNET_PeerIdentity *peer);
 162
 163
 164
 165 #if 0                           /* keep Emacsens' auto-indent happy */
 166 {
 167 #endif
 168 #ifdef __cplusplus
 169 }
 170 #endif
 171
 172 /* ifndef GNUNET_TRANSPORT_CORE_SERVICE_H */
 173 #endif
 174
 175 /** @} */  /* end of group */
 176
 177 /* end of gnunet_transport_core_service.h */