src/cadet/gnunet-service-cadet-new_connection.h

   1
   2 /*
   3      This file is part of GNUnet.
   4      Copyright (C) 2001-2017 GNUnet e.V.
   5
   6      GNUnet is free software; you can redistribute it and/or modify
   7      it under the terms of the GNU General Public License as published
   8      by the Free Software Foundation; either version 3, or (at your
   9      option) any later version.
  10
  11      GNUnet is distributed in the hope that it will be useful, but
  12      WITHOUT ANY WARRANTY; without even the implied warranty of
  13      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14      General Public License for more details.
  15
  16      You should have received a copy of the GNU General Public License
  17      along with GNUnet; see the file COPYING.  If not, write to the
  18      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  19      Boston, MA 02110-1301, USA.
  20 */
  21
  22 /**
  23  * @file cadet/gnunet-service-cadet-new_connection.h
  24  * @brief
  25  * @author Bartlomiej Polot
  26  * @author Christian Grothoff
  27  */
  28 #ifndef GNUNET_SERVICE_CADET_CONNECTION_H
  29 #define GNUNET_SERVICE_CADET_CONNECTION_H
  30
  31 #include "gnunet_util_lib.h"
  32 #include "gnunet-service-cadet-new.h"
  33 #include "gnunet-service-cadet-new_peer.h"
  34 #include "cadet_protocol.h"
  35
  36
  37 /**
  38  * Function called to notify tunnel about change in our readyness.
  39  *
  40  * @param cls closure
  41  * @param is_ready #GNUNET_YES if the connection is now ready for transmission,
  42  *                 #GNUNET_NO if the connection is no longer ready for transmission
  43  */
  44 typedef void
  45 (*GCC_ReadyCallback)(void *cls,
  46                      int is_ready);
  47
  48
  49 /**
  50  * Destroy a connection, called when the CORE layer is already done
  51  * (i.e. has received a BROKEN message), but if we still have to
  52  * communicate the destruction of the connection to the tunnel (if one
  53  * exists).
  54  *
  55  * @param cc connection to destroy
  56  */
  57 void
  58 GCC_destroy_without_core (struct CadetConnection *cc);
  59
  60
  61 /**
  62  * Destroy a connection, called if the tunnel association with the
  63  * connection was already broken, but we still need to notify the CORE
  64  * layer about the breakage.
  65  *
  66  * @param cc connection to destroy
  67  */
  68 void
  69 GCC_destroy_without_tunnel (struct CadetConnection *cc);
  70
  71
  72 /**
  73  * Create a connection to @a destination via @a path and
  74  * notify @a cb whenever we are ready for more data.
  75  *
  76  * @param destination where to go
  77  * @param path which path to take (may not be the full path)
  78  * @param options options for the connection
  79  * @param ct which tunnel uses this connection
  80  * @param ready_cb function to call when ready to transmit
  81  * @param ready_cb_cls closure for @a cb
  82  * @return handle to the connection
  83  */
  84 struct CadetConnection *
  85 GCC_create (struct CadetPeer *destination,
  86             struct CadetPeerPath *path,
  87             enum GNUNET_CADET_ChannelOption options,
  88             struct CadetTConnection *ct,
  89             GCC_ReadyCallback ready_cb,
  90             void *ready_cb_cls);
  91
  92
  93 /**
  94  * Create a connection to @a destination via @a path and
  95  * notify @a cb whenever we are ready for more data.  This
  96  * is an inbound tunnel, so we must use the existing @a cid
  97  *
  98  * @param destination where to go
  99  * @param path which path to take (may not be the full path)
 100  * @param options options for the connection
 101  * @param ct which tunnel uses this connection
 102  * @param ready_cb function to call when ready to transmit
 103  * @param ready_cb_cls closure for @a cb
 104  * @return handle to the connection, NULL if we already have
 105  *         a connection that takes precedence on @a path
 106  */
 107 struct CadetConnection *
 108 GCC_create_inbound (struct CadetPeer *destination,
 109                     struct CadetPeerPath *path,
 110                     enum GNUNET_CADET_ChannelOption options,
 111                     struct CadetTConnection *ct,
 112                     const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid,
 113                     GCC_ReadyCallback ready_cb,
 114                     void *ready_cb_cls);
 115
 116
 117 /**
 118  * Transmit message @a msg via connection @a cc.  Must only be called
 119  * (once) after the connection has signalled that it is ready via the
 120  * `ready_cb`.  Clients can also use #GCC_is_ready() to check if the
 121  * connection is right now ready for transmission.
 122  *
 123  * @param cc connection identification
 124  * @param env envelope with message to transmit;
 125  *            the #GNUNET_MQ_notify_send() must not have yet been used
 126  *            for the envelope.  Also, the message better match the
 127  *            connection identifier of this connection...
 128  */
 129 void
 130 GCC_transmit (struct CadetConnection *cc,
 131               struct GNUNET_MQ_Envelope *env);
 132
 133
 134 /**
 135  * A CREATE_ACK was received for this connection, process it.
 136  *
 137  * @param cc the connection that got the ACK.
 138  */
 139 void
 140 GCC_handle_connection_create_ack (struct CadetConnection *cc);
 141
 142
 143 /**
 144  * We got a #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE for a
 145  * connection that we already have.  Either our ACK got lost
 146  * or something is fishy.  Consider retransmitting the ACK.
 147  *
 148  * @param cc connection that got the duplicate CREATE
 149  */
 150 void
 151 GCC_handle_duplicate_create (struct CadetConnection *cc);
 152
 153
 154 /**
 155  * Handle KX message.
 156  *
 157  * @param cc connection that received encrypted message
 158  * @param msg the key exchange message
 159  */
 160 void
 161 GCC_handle_kx (struct CadetConnection *cc,
 162                const struct GNUNET_CADET_TunnelKeyExchangeMessage *msg);
 163
 164
 165 /**
 166  * Handle KX_AUTH message.
 167  *
 168  * @param cc connection that received encrypted message
 169  * @param msg the key exchange message
 170  */
 171 void
 172 GCC_handle_kx_auth (struct CadetConnection *cc,
 173                     const struct GNUNET_CADET_TunnelKeyExchangeAuthMessage *msg);
 174
 175
 176 /**
 177  * Handle encrypted message.
 178  *
 179  * @param cc connection that received encrypted message
 180  * @param msg the encrypted message to decrypt
 181  */
 182 void
 183 GCC_handle_encrypted (struct CadetConnection *cc,
 184                       const struct GNUNET_CADET_TunnelEncryptedMessage *msg);
 185
 186
 187 /**
 188  * Return the tunnel associated with this connection.
 189  *
 190  * @param cc connection to query
 191  * @return corresponding entry in the tunnel's connection list
 192  */
 193 struct CadetTConnection *
 194 GCC_get_ct (struct CadetConnection *cc);
 195
 196
 197 /**
 198  * Obtain the path used by this connection.
 199  *
 200  * @param cc connection
 201  * @return path to @a cc
 202  */
 203 struct CadetPeerPath *
 204 GCC_get_path (struct CadetConnection *cc);
 205
 206
 207 /**
 208  * Obtain unique ID for the connection.
 209  *
 210  * @param cc connection.
 211  * @return unique number of the connection
 212  */
 213 const struct GNUNET_CADET_ConnectionTunnelIdentifier *
 214 GCC_get_id (struct CadetConnection *cc);
 215
 216
 217 /**
 218  * Get a (static) string for a connection.
 219  *
 220  * @param cc Connection.
 221  */
 222 const char *
 223 GCC_2s (const struct CadetConnection *cc);
 224
 225
 226 /**
 227  * Log connection info.
 228  *
 229  * @param cc connection
 230  * @param level Debug level to use.
 231  */
 232 void
 233 GCC_debug (struct CadetConnection *cc,
 234            enum GNUNET_ErrorType level);
 235
 236
 237 #endif