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  * Lookup a connection by its identifier.
  77  *
  78  * @param cid identifier to resolve
  79  * @return NULL if connection was not found
  80  */
  81 struct CadetConnection *
  82 GCC_lookup (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
  83
  84
  85 /**
  86  * Create a connection to @a destination via @a path and
  87  * notify @a cb whenever we are ready for more data.
  88  *
  89  * @param destination where to go
  90  * @param path which path to take (may not be the full path)
  91  * @param off offset of @a destination on @a path
  92  * @param options options for the connection
  93  * @param ct which tunnel uses this connection
  94  * @param ready_cb function to call when ready to transmit
  95  * @param ready_cb_cls closure for @a cb
  96  * @return handle to the connection
  97  */
  98 struct CadetConnection *
  99 GCC_create (struct CadetPeer *destination,
 100             struct CadetPeerPath *path,
 101             unsigned int off,
 102             enum GNUNET_CADET_ChannelOption options,
 103             struct CadetTConnection *ct,
 104             GCC_ReadyCallback ready_cb,
 105             void *ready_cb_cls);
 106
 107
 108 /**
 109  * Create a connection to @a destination via @a path and
 110  * notify @a cb whenever we are ready for more data.  This
 111  * is an inbound tunnel, so we must use the existing @a cid
 112  *
 113  * @param destination where to go
 114  * @param path which path to take (may not be the full path)
 115  * @param options options for the connection
 116  * @param ct which tunnel uses this connection
 117  * @param ready_cb function to call when ready to transmit
 118  * @param ready_cb_cls closure for @a cb
 119  * @return handle to the connection, NULL if we already have
 120  *         a connection that takes precedence on @a path
 121  */
 122 struct CadetConnection *
 123 GCC_create_inbound (struct CadetPeer *destination,
 124                     struct CadetPeerPath *path,
 125                     enum GNUNET_CADET_ChannelOption options,
 126                     struct CadetTConnection *ct,
 127                     const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid,
 128                     GCC_ReadyCallback ready_cb,
 129                     void *ready_cb_cls);
 130
 131
 132 /**
 133  * Transmit message @a msg via connection @a cc.  Must only be called
 134  * (once) after the connection has signalled that it is ready via the
 135  * `ready_cb`.  Clients can also use #GCC_is_ready() to check if the
 136  * connection is right now ready for transmission.
 137  *
 138  * @param cc connection identification
 139  * @param env envelope with message to transmit;
 140  *            the #GNUNET_MQ_notify_send() must not have yet been used
 141  *            for the envelope.  Also, the message better match the
 142  *            connection identifier of this connection...
 143  */
 144 void
 145 GCC_transmit (struct CadetConnection *cc,
 146               struct GNUNET_MQ_Envelope *env);
 147
 148
 149 /**
 150  * A CREATE_ACK was received for this connection, process it.
 151  *
 152  * @param cc the connection that got the ACK.
 153  */
 154 void
 155 GCC_handle_connection_create_ack (struct CadetConnection *cc);
 156
 157
 158 /**
 159  * We got a #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE for a
 160  * connection that we already have.  Either our ACK got lost
 161  * or something is fishy.  Consider retransmitting the ACK.
 162  *
 163  * @param cc connection that got the duplicate CREATE
 164  */
 165 void
 166 GCC_handle_duplicate_create (struct CadetConnection *cc);
 167
 168
 169 /**
 170  * Handle KX message.
 171  *
 172  * @param cc connection that received encrypted message
 173  * @param msg the key exchange message
 174  */
 175 void
 176 GCC_handle_kx (struct CadetConnection *cc,
 177                const struct GNUNET_CADET_TunnelKeyExchangeMessage *msg);
 178
 179
 180 /**
 181  * Handle KX_AUTH message.
 182  *
 183  * @param cc connection that received encrypted message
 184  * @param msg the key exchange message
 185  */
 186 void
 187 GCC_handle_kx_auth (struct CadetConnection *cc,
 188                     const struct GNUNET_CADET_TunnelKeyExchangeAuthMessage *msg);
 189
 190
 191 /**
 192  * Performance metrics for a connection.
 193  */
 194 struct CadetConnectionMetrics
 195 {
 196
 197   /**
 198    * Our current best estimate of the latency, based on a weighted
 199    * average of at least @a latency_datapoints values.
 200    */
 201   struct GNUNET_TIME_Relative aged_latency;
 202
 203   /**
 204    * When was this connection first established? (by us sending or
 205    * receiving the CREATE_ACK for the first time)
 206    */
 207   struct GNUNET_TIME_Absolute age;
 208
 209   /**
 210    * When was this connection last used? (by us sending or
 211    * receiving a PAYLOAD message on it)
 212    */
 213   struct GNUNET_TIME_Absolute last_use;
 214
 215   /**
 216    * How many packets that ought to generate an ACK did we send via
 217    * this connection?
 218    */
 219   unsigned long long num_acked_transmissions;
 220
 221   /**
 222    * Number of packets that were sent via this connection did actually
 223    * receive an ACK?  (Note: ACKs may be transmitted and lost via
 224    * other connections, so this value should only be interpreted
 225    * relative to @e num_acked_transmissions and in relation to other
 226    * connections.)
 227    */
 228   unsigned long long num_successes;
 229
 230 };
 231
 232
 233 /**
 234  * Obtain performance @a metrics from @a cc.
 235  *
 236  * @param cc connection to query
 237  * @return the metrics
 238  */
 239 const struct CadetConnectionMetrics *
 240 GCC_get_metrics (struct CadetConnection *cc);
 241
 242
 243 /**
 244  * Handle encrypted message.
 245  *
 246  * @param cc connection that received encrypted message
 247  * @param msg the encrypted message to decrypt
 248  */
 249 void
 250 GCC_handle_encrypted (struct CadetConnection *cc,
 251                       const struct GNUNET_CADET_TunnelEncryptedMessage *msg);
 252
 253
 254 /**
 255  * We sent a message for which we expect to receive an ACK via
 256  * the connection identified by @a cti.
 257  *
 258  * @param cid connection identifier where we expect an ACK
 259  */
 260 void
 261 GCC_ack_expected (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
 262
 263
 264 /**
 265  * We observed an ACK for a message that was originally sent via
 266  * the connection identified by @a cti.
 267  *
 268  * @param cid connection identifier where we got an ACK for a message
 269  *            that was originally sent via this connection (the ACK
 270  *            may have gotten back to us via a different connection).
 271  */
 272 void
 273 GCC_ack_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid);
 274
 275
 276 /**
 277  * We observed some the given @a latency on the connection
 278  * identified by @a cti.  (The same connection was taken
 279  * in both directions.)
 280  *
 281  * @param cti connection identifier where we measured latency
 282  * @param latency the observed latency
 283  */
 284 void
 285 GCC_latency_observed (const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
 286                       struct GNUNET_TIME_Relative latency);
 287
 288
 289 /**
 290  * Return the tunnel associated with this connection.
 291  *
 292  * @param cc connection to query
 293  * @return corresponding entry in the tunnel's connection list
 294  */
 295 struct CadetTConnection *
 296 GCC_get_ct (struct CadetConnection *cc);
 297
 298
 299 /**
 300  * Obtain the path used by this connection.
 301  *
 302  * @param cc connection
 303  * @return path to @a cc
 304  */
 305 struct CadetPeerPath *
 306 GCC_get_path (struct CadetConnection *cc);
 307
 308
 309 /**
 310  * Obtain unique ID for the connection.
 311  *
 312  * @param cc connection.
 313  * @return unique number of the connection
 314  */
 315 const struct GNUNET_CADET_ConnectionTunnelIdentifier *
 316 GCC_get_id (struct CadetConnection *cc);
 317
 318
 319 /**
 320  * Get a (static) string for a connection.
 321  *
 322  * @param cc Connection.
 323  */
 324 const char *
 325 GCC_2s (const struct CadetConnection *cc);
 326
 327
 328 /**
 329  * Log connection info.
 330  *
 331  * @param cc connection
 332  * @param level Debug level to use.
 333  */
 334 void
 335 GCC_debug (struct CadetConnection *cc,
 336            enum GNUNET_ErrorType level);
 337
 338
 339 #endif