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 ct which tunnel uses this connection
  79  * @param ready_cb function to call when ready to transmit
  80  * @param ready_cb_cls closure for @a cb
  81  * @return handle to the connection
  82  */
  83 struct CadetConnection *
  84 GCC_create (struct CadetPeer *destination,
  85             struct CadetPeerPath *path,
  86             struct CadetTConnection *ct,
  87             GCC_ReadyCallback ready_cb,
  88             void *ready_cb_cls);
  89
  90
  91 /**
  92  * Create a connection to @a destination via @a path and
  93  * notify @a cb whenever we are ready for more data.  This
  94  * is an inbound tunnel, so we must use the existing @a cid
  95  *
  96  * @param destination where to go
  97  * @param path which path to take (may not be the full path)
  98  * @param ct which tunnel uses this connection
  99  * @param ready_cb function to call when ready to transmit
 100  * @param ready_cb_cls closure for @a cb
 101  * @return handle to the connection, NULL if we already have
 102  *         a connection that takes precedence on @a path
 103  */
 104 struct CadetConnection *
 105 GCC_create_inbound (struct CadetPeer *destination,
 106                     struct CadetPeerPath *path,
 107                     struct CadetTConnection *ct,
 108                     const struct GNUNET_CADET_ConnectionTunnelIdentifier *cid,
 109                     GCC_ReadyCallback ready_cb,
 110                     void *ready_cb_cls);
 111
 112
 113 /**
 114  * Transmit message @a msg via connection @a cc.  Must only be called
 115  * (once) after the connection has signalled that it is ready via the
 116  * `ready_cb`.  Clients can also use #GCC_is_ready() to check if the
 117  * connection is right now ready for transmission.
 118  *
 119  * @param cc connection identification
 120  * @param env envelope with message to transmit;
 121  *            the #GNUNET_MQ_notify_send() must not have yet been used
 122  *            for the envelope.  Also, the message better match the
 123  *            connection identifier of this connection...
 124  */
 125 void
 126 GCC_transmit (struct CadetConnection *cc,
 127               struct GNUNET_MQ_Envelope *env);
 128
 129
 130 /**
 131  * A CREATE_ACK was received for this connection, process it.
 132  *
 133  * @param cc the connection that got the ACK.
 134  */
 135 void
 136 GCC_handle_connection_create_ack (struct CadetConnection *cc);
 137
 138
 139 /**
 140  * We got a #GNUNET_MESSAGE_TYPE_CADET_CONNECTION_CREATE for a
 141  * connection that we already have.  Either our ACK got lost
 142  * or something is fishy.  Consider retransmitting the ACK.
 143  *
 144  * @param cc connection that got the duplicate CREATE
 145  */
 146 void
 147 GCC_handle_duplicate_create (struct CadetConnection *cc);
 148
 149
 150 /**
 151  * Handle KX message.
 152  *
 153  * @param cc connection that received encrypted message
 154  * @param msg the key exchange message
 155  */
 156 void
 157 GCC_handle_kx (struct CadetConnection *cc,
 158                const struct GNUNET_CADET_TunnelKeyExchangeMessage *msg);
 159
 160
 161 /**
 162  * Handle KX_AUTH message.
 163  *
 164  * @param cc connection that received encrypted message
 165  * @param msg the key exchange message
 166  */
 167 void
 168 GCC_handle_kx_auth (struct CadetConnection *cc,
 169                     const struct GNUNET_CADET_TunnelKeyExchangeAuthMessage *msg);
 170
 171
 172 /**
 173  * Handle encrypted message.
 174  *
 175  * @param cc connection that received encrypted message
 176  * @param msg the encrypted message to decrypt
 177  */
 178 void
 179 GCC_handle_encrypted (struct CadetConnection *cc,
 180                       const struct GNUNET_CADET_TunnelEncryptedMessage *msg);
 181
 182
 183 /**
 184  * Return the tunnel associated with this connection.
 185  *
 186  * @param cc connection to query
 187  * @return corresponding entry in the tunnel's connection list
 188  */
 189 struct CadetTConnection *
 190 GCC_get_ct (struct CadetConnection *cc);
 191
 192
 193 /**
 194  * Obtain the path used by this connection.
 195  *
 196  * @param cc connection
 197  * @return path to @a cc
 198  */
 199 struct CadetPeerPath *
 200 GCC_get_path (struct CadetConnection *cc);
 201
 202
 203 /**
 204  * Obtain unique ID for the connection.
 205  *
 206  * @param cc connection.
 207  * @return unique number of the connection
 208  */
 209 const struct GNUNET_CADET_ConnectionTunnelIdentifier *
 210 GCC_get_id (struct CadetConnection *cc);
 211
 212
 213 /**
 214  * Get a (static) string for a connection.
 215  *
 216  * @param cc Connection.
 217  */
 218 const char *
 219 GCC_2s (const struct CadetConnection *cc);
 220
 221
 222 /**
 223  * Log connection info.
 224  *
 225  * @param cc connection
 226  * @param level Debug level to use.
 227  */
 228 void
 229 GCC_debug (struct CadetConnection *cc,
 230            enum GNUNET_ErrorType level);
 231
 232
 233 #endif