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