src/cadet/gnunet-service-cadet_channel.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_channel.h
  24  * @brief GNUnet CADET service with encryption
  25  * @author Bartlomiej Polot
  26  * @author Christian Grothoff
  27  */
  28 #ifndef GNUNET_SERVICE_CADET_CHANNEL_H
  29 #define GNUNET_SERVICE_CADET_CHANNEL_H
  30
  31 #include "gnunet-service-cadet.h"
  32 #include "gnunet-service-cadet_peer.h"
  33 #include "cadet_protocol.h"
  34
  35
  36 /**
  37  * A channel is a bidirectional connection between two CADET
  38  * clients.  Communiation can be reliable, unreliable, in-order
  39  * or out-of-order.  One client is the "local" client, this
  40  * one initiated the connection.   The other client is the
  41  * "incoming" client, this one listened on a port to accept
  42  * the connection from the "local" client.
  43  */
  44 struct CadetChannel;
  45
  46
  47 /**
  48  * Get the static string for identification of the channel.
  49  *
  50  * @param ch Channel.
  51  *
  52  * @return Static string with the channel IDs.
  53  */
  54 const char *
  55 GCCH_2s (const struct CadetChannel *ch);
  56
  57
  58 /**
  59  * Log channel info.
  60  *
  61  * @param ch Channel.
  62  * @param level Debug level to use.
  63  */
  64 void
  65 GCCH_debug (struct CadetChannel *ch,
  66             enum GNUNET_ErrorType level);
  67
  68
  69 /**
  70  * Get the channel's public ID.
  71  *
  72  * @param ch Channel.
  73  *
  74  * @return ID used to identify the channel with the remote peer.
  75  */
  76 struct GNUNET_CADET_ChannelTunnelNumber
  77 GCCH_get_id (const struct CadetChannel *ch);
  78
  79
  80 /**
  81  * Create a new channel.
  82  *
  83  * @param owner local client owning the channel
  84  * @param owner_id local chid of this channel at the @a owner
  85  * @param destination peer to which we should build the channel
  86  * @param port desired port at @a destination
  87  * @param options options for the channel
  88  * @return handle to the new channel
  89  */
  90 struct CadetChannel *
  91 GCCH_channel_local_new (struct CadetClient *owner,
  92                         struct GNUNET_CADET_ClientChannelNumber owner_id,
  93                         struct CadetPeer *destination,
  94                         const struct GNUNET_HashCode *port,
  95                         uint32_t options);
  96
  97
  98 /**
  99  * A client is bound to the port that we have a channel
 100  * open to.  Send the acknowledgement for the connection
 101  * request and establish the link with the client.
 102  *
 103  * @param ch open incoming channel
 104  * @param c client listening on the respective port
 105  */
 106 void
 107 GCCH_bind (struct CadetChannel *ch,
 108            struct CadetClient *c);
 109
 110
 111 /**
 112  * Destroy locally created channel.  Called by the
 113  * local client, so no need to tell the client.
 114  *
 115  * @param ch channel to destroy
 116  * @param c client that caused the destruction
 117  * @param ccn client number of the client @a c
 118  */
 119 void
 120 GCCH_channel_local_destroy (struct CadetChannel *ch,
 121                             struct CadetClient *c,
 122                             struct GNUNET_CADET_ClientChannelNumber ccn);
 123
 124
 125 /**
 126  * Function called once and only once after a channel was bound
 127  * to its tunnel via #GCT_add_channel() is ready for transmission.
 128  * Note that this is only the case for channels that this peer
 129  * initiates, as for incoming channels we assume that they are
 130  * ready for transmission immediately upon receiving the open
 131  * message.  Used to bootstrap the #GCT_send() process.
 132  *
 133  * @param ch the channel for which the tunnel is now ready
 134  */
 135 void
 136 GCCH_tunnel_up (struct CadetChannel *ch);
 137
 138
 139 /**
 140  * Create a new channel based on a request coming in over the network.
 141  *
 142  * @param t tunnel to the remote peer
 143  * @param chid identifier of this channel in the tunnel
 144  * @param origin peer to who initiated the channel
 145  * @param port desired local port
 146  * @param options options for the channel
 147  * @return handle to the new channel
 148  */
 149 struct CadetChannel *
 150 GCCH_channel_incoming_new (struct CadetTunnel *t,
 151                            struct GNUNET_CADET_ChannelTunnelNumber chid,
 152                            const struct GNUNET_HashCode *port,
 153                            uint32_t options);
 154
 155
 156 /**
 157  * We got a #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN message again for
 158  * this channel.  If the binding was successful, (re)transmit the
 159  * #GNUNET_MESSAGE_TYPE_CADET_CHANNEL_OPEN_ACK.
 160  *
 161  * @param ch channel that got the duplicate open
 162  * @param cti identifier of the connection that delivered the message
 163  */
 164 void
 165 GCCH_handle_duplicate_open (struct CadetChannel *ch,
 166                             const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti);
 167
 168
 169
 170 /**
 171  * We got payload data for a channel.  Pass it on to the client.
 172  *
 173  * @param ch channel that got data
 174  * @param cti identifier of the connection that delivered the message
 175  * @param msg message that was received
 176  */
 177 void
 178 GCCH_handle_channel_plaintext_data (struct CadetChannel *ch,
 179                                     const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
 180                                     const struct GNUNET_CADET_ChannelAppDataMessage *msg);
 181
 182
 183 /**
 184  * We got an acknowledgement for payload data for a channel.
 185  * Possibly resume transmissions.
 186  *
 187  * @param ch channel that got the ack
 188  * @param cti identifier of the connection that delivered the message
 189  * @param ack details about what was received
 190  */
 191 void
 192 GCCH_handle_channel_plaintext_data_ack (struct CadetChannel *ch,
 193                                         const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti,
 194                                         const struct GNUNET_CADET_ChannelDataAckMessage *ack);
 195
 196
 197 /**
 198  * We got an acknowledgement for the creation of the channel
 199  * (the port is open on the other side). Begin transmissions.
 200  *
 201  * @param ch channel to destroy
 202  * @param cti identifier of the connection that delivered the message,
 203  *        NULL if the ACK was inferred because we got payload or are on loopback
 204  */
 205 void
 206 GCCH_handle_channel_open_ack (struct CadetChannel *ch,
 207                               const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti);
 208
 209
 210 /**
 211  * Destroy channel, based on the other peer closing the
 212  * connection.  Also needs to remove this channel from
 213  * the tunnel.
 214  *
 215  * FIXME: need to make it possible to defer destruction until we have
 216  * received all messages up to the destroy, and right now the destroy
 217  * message (and this API) fails to give is the information we need!
 218  *
 219  * FIXME: also need to know if the other peer got a destroy from
 220  * us before!
 221  *
 222  * @param ch channel to destroy
 223  * @param cti identifier of the connection that delivered the message,
 224  *            NULL during shutdown
 225  */
 226 void
 227 GCCH_handle_remote_destroy (struct CadetChannel *ch,
 228                             const struct GNUNET_CADET_ConnectionTunnelIdentifier *cti);
 229
 230
 231 /**
 232  * Handle data given by a client.
 233  *
 234  * Check whether the client is allowed to send in this tunnel, save if
 235  * channel is reliable and send an ACK to the client if there is still
 236  * buffer space in the tunnel.
 237  *
 238  * @param ch Channel.
 239  * @param sender_ccn ccn of the sender
 240  * @param buf payload to transmit.
 241  * @param buf_len number of bytes in @a buf
 242  * @return #GNUNET_OK if everything goes well,
 243  *         #GNUNET_SYSERR in case of an error.
 244  */
 245 int
 246 GCCH_handle_local_data (struct CadetChannel *ch,
 247                         struct GNUNET_CADET_ClientChannelNumber sender_ccn,
 248                         const char *buf,
 249                         size_t buf_len);
 250
 251
 252 /**
 253  * Handle ACK from client on local channel.
 254  *
 255  * @param ch channel to destroy
 256  * @param client_ccn ccn of the client sending the ack
 257  */
 258 void
 259 GCCH_handle_local_ack (struct CadetChannel *ch,
 260                        struct GNUNET_CADET_ClientChannelNumber client_ccn);
 261
 262 #endif