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 A connection is a live end-to-end messaging mechanism
  25  *       where the peers are identified by a path and know how
  26  *       to forward along the route using a connection identifier
  27  *       for routing the data.
  28  * @author Bartlomiej Polot
  29  * @author Christian Grothoff
  30  */
  31 #ifndef GNUNET_SERVICE_CADET_CONNECTION_H
  32 #define GNUNET_SERVICE_CADET_CONNECTION_H
  33
  34 #include "gnunet_util_lib.h"
  35 #include "gnunet-service-cadet-new.h"
  36 #include "gnunet-service-cadet-new_peer.h"
  37 #include "cadet_protocol.h"
  38
  39
  40 /**
  41  * Function called to notify tunnel about change in our readyness.
  42  *
  43  * @param cls closure
  44  * @param is_ready #GNUNET_YES if the connection is now ready for transmission,
  45  *                 #GNUNET_NO if the connection is no longer ready for transmission
  46  */
  47 typedef void
  48 (*GCC_ReadyCallback)(void *cls,
  49                      int is_ready);
  50
  51
  52 /**
  53  * Destroy a connection, called when the CORE layer is already done
  54  * (i.e. has received a BROKEN message), but if we still have to
  55  * communicate the destruction of the connection to the tunnel (if one
  56  * exists).
  57  *
  58  * @param cc connection to destroy
  59  */
  60 void
  61 GCC_destroy_without_core (struct CadetConnection *cc);
  62
  63
  64 /**
  65  * Destroy a connection, called if the tunnel association with the
  66  * connection was already broken, but we still need to notify the CORE
  67  * layer about the breakage.
  68  *
  69  * @param cc connection to destroy
  70  */
  71 void
  72 GCC_destroy_without_tunnel (struct CadetConnection *cc);
  73
  74
  75 /**
  76  * Create a connection to @a destination via @a path and
  77  * notify @a cb whenever we are ready for more data.
  78  *
  79  * @param destination where to go
  80  * @param path which path to take (may not be the full path)
  81  * @param options options for the connection
  82  * @param ct which tunnel uses this connection
  83  * @param ready_cb function to call when ready to transmit
  84  * @param ready_cb_cls closure for @a cb
  85  * @return handle to the connection
  86  */
  87 struct CadetConnection *
  88 GCC_create (struct CadetPeer *destination,
  89             struct CadetPeerPath *path,
  90             enum GNUNET_CADET_ChannelOption options,
  91             struct CadetTConnection *ct,
  92             GCC_ReadyCallback ready_cb,
  93             void *ready_cb_cls);
  94
  95
  96 /**
  97  * Create a connection to @a destination via @a path and
  98  * notify @a cb whenever we are ready for more data.  This
  99  * is an inbound tunnel, so we must use the existing @a cid
 100  *
 101  * @param destination where to go
 102  * @param path which path to take (may not be the full path)
 103  * @param options options for the connection
 104  * @param ct which tunnel uses this connection
 105  * @param ready_cb function to call when ready to transmit
 106  * @param ready_cb_cls closure for @a cb
 107  * @return handle to the connection, NULL if we already have
 108  *         a connection that takes precedence on @a path
 109  */
 110 struct CadetConnection *
 111 GCC_create_inbound (struct CadetPeer *destination,
 112                     struct CadetPeerPath *path,
 113                     enum GNUNET_CADET_ChannelOption options,
 114                     struct CadetTConnection *ct,
 115                     const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid,
 116                     GCC_ReadyCallback ready_cb,
 117                     void *ready_cb_cls);
 118
 119
 120 /**
 121  * Transmit message @a msg via connection @a cc.  Must only be called
 122  * (once) after the connection has signalled that it is ready via the
 123  * `ready_cb`.  Clients can also use #GCC_is_ready() to check if the
 124  * connection is right now ready for transmission.
 125  *
 126  * @param cc connection identification
 127  * @param env envelope with message to transmit;
 128  *            the #GNUNET_MQ_notify_send() must not have yet been used
 129  *            for the envelope.  Also, the message better match the
 130  *            connection identifier of this connection...
 131  */
 132 void
 133 GCC_transmit (struct CadetConnection *cc,
 134               struct GNUNET_MQ_Envelope *env);
 135
 136
 137 /**
 138  * A CREATE_ACK was received for this connection, process it.
 139  *
 140  * @param cc the connection that got the ACK.
 141  */
 142 void
 143 GCC_handle_connection_create_ack (struct CadetConnection *cc);
 144
 145
 146 /**
 147  * We got a #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE for a
 148  * connection that we already have.  Either our ACK got lost
 149  * or something is fishy.  Consider retransmitting the ACK.
 150  *
 151  * @param cc connection that got the duplicate CREATE
 152  */
 153 void
 154 GCC_handle_duplicate_create (struct CadetConnection *cc);
 155
 156
 157 /**
 158  * Handle KX message.
 159  *
 160  * @param cc connection that received encrypted message
 161  * @param msg the key exchange message
 162  */
 163 void
 164 GCC_handle_kx (struct CadetConnection *cc,
 165                const struct GNUNET_CADET_TunnelKeyExchangeMessage *msg);
 166
 167
 168 /**
 169  * Handle KX_AUTH message.
 170  *
 171  * @param cc connection that received encrypted message
 172  * @param msg the key exchange message
 173  */
 174 void
 175 GCC_handle_kx_auth (struct CadetConnection *cc,
 176                     const struct GNUNET_CADET_TunnelKeyExchangeAuthMessage *msg);
 177
 178
 179 /**
 180  * Performance metrics for a connection.
 181  */
 182 struct CadetConnectionMetrics
 183 {
 184
 185   /**
 186    * Our current best estimate of the latency, based on a weighted
 187    * average of at least @a latency_datapoints values.
 188    */
 189   struct GNUNET_TIME_Relative aged_latency;
 190
 191   /**
 192    * When was this connection first established? (by us sending or
 193    * receiving the CREATE_ACK for the first time)
 194    */
 195   struct GNUNET_TIME_Absolute age;
 196
 197   /**
 198    * When was this connection last used? (by us sending or
 199    * receiving a PAYLOAD message on it)
 200    */
 201   struct GNUNET_TIME_Absolute last_use;
 202
 203   /**
 204    * How many packets that ought to generate an ACK did we send via
 205    * this connection?
 206    */
 207   unsigned long long num_acked_transmissions;
 208
 209   /**
 210    * Number of packets that were sent via this connection did actually
 211    * receive an ACK?  (Note: ACKs may be transmitted and lost via
 212    * other connections, so this value should only be interpreted
 213    * relative to @e num_acked_transmissions and in relation to other
 214    * connections.)
 215    */
 216   unsigned long long num_successes;
 217
 218 };
 219
 220
 221 /**
 222  * Obtain performance @a metrics from @a cc.
 223  *
 224  * @param cc connection to query
 225  * @return the metrics
 226  */
 227 const struct CadetConnectionMetrics *
 228 GCC_get_metrics (struct CadetConnection *cc);
 229
 230
 231 /**
 232  * Handle encrypted message.
 233  *
 234  * @param cc connection that received encrypted message
 235  * @param msg the encrypted message to decrypt
 236  */
 237 void
 238 GCC_handle_encrypted (struct CadetConnection *cc,
 239                       const struct GNUNET_CADET_TunnelEncryptedMessage *msg);
 240
 241
 242 /**
 243  * We sent a message for which we expect to receive an ACK via
 244  * the connection identified by @a cti.
 245  *
 246  * @param cid connection identifier where we expect an ACK
 247  */
 248 void
 249 GCC_ack_expected (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
 250
 251
 252 /**
 253  * We observed an ACK for a message that was originally sent via
 254  * the connection identified by @a cti.
 255  *
 256  * @param cid connection identifier where we got an ACK for a message
 257  *            that was originally sent via this connection (the ACK
 258  *            may have gotten back to us via a different connection).
 259  */
 260 void
 261 GCC_ack_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
 262
 263
 264 /**
 265  * We observed some the given @a latency on the connection
 266  * identified by @a cti.  (The same connection was taken
 267  * in both directions.)
 268  *
 269  * @param cti connection identifier where we measured latency
 270  * @param latency the observed latency
 271  */
 272 void
 273 GCC_latency_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
 274                       struct GNUNET_TIME_Relative latency);
 275
 276
 277 /**
 278  * Return the tunnel associated with this connection.
 279  *
 280  * @param cc connection to query
 281  * @return corresponding entry in the tunnel's connection list
 282  */
 283 struct CadetTConnection *
 284 GCC_get_ct (struct CadetConnection *cc);
 285
 286
 287 /**
 288  * Obtain the path used by this connection.
 289  *
 290  * @param cc connection
 291  * @return path to @a cc
 292  */
 293 struct CadetPeerPath *
 294 GCC_get_path (struct CadetConnection *cc);
 295
 296
 297 /**
 298  * Obtain unique ID for the connection.
 299  *
 300  * @param cc connection.
 301  * @return unique number of the connection
 302  */
 303 const struct GNUNET_CADET_ConnectionTunnelIdentifier *
 304 GCC_get_id (struct CadetConnection *cc);
 305
 306
 307 /**
 308  * Get a (static) string for a connection.
 309  *
 310  * @param cc Connection.
 311  */
 312 const char *
 313 GCC_2s (const struct CadetConnection *cc);
 314
 315
 316 /**
 317  * Log connection info.
 318  *
 319  * @param cc connection
 320  * @param level Debug level to use.
 321  */
 322 void
 323 GCC_debug (struct CadetConnection *cc,
 324            enum GNUNET_ErrorType level);
 325
 326
 327 #endif