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