src/cadet/gnunet-service-cadet-new_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-new_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-new.h"
  32 #include "gnunet-service-cadet-new_peer.h"
  33
  34
  35 /**
  36  * A channel is a bidirectional connection between two CADET
  37  * clients.  Communiation can be reliable, unreliable, in-order
  38  * or out-of-order.  One client is the "local" client, this
  39  * one initiated the connection.   The other client is the
  40  * "incoming" client, this one listened on a port to accept
  41  * the connection from the "local" client.
  42  */
  43 struct CadetChannel;
  44
  45
  46 /**
  47  * Get the static string for identification of the channel.
  48  *
  49  * @param ch Channel.
  50  *
  51  * @return Static string with the channel IDs.
  52  */
  53 const char *
  54 GCCH_2s (const struct CadetChannel *ch);
  55
  56
  57 /**
  58  * Log channel info.
  59  *
  60  * @param ch Channel.
  61  * @param level Debug level to use.
  62  */
  63 void
  64 GCCH_debug (struct CadetChannel *ch,
  65             enum GNUNET_ErrorType level);
  66
  67
  68 /**
  69  * Get the channel's public ID.
  70  *
  71  * @param ch Channel.
  72  *
  73  * @return ID used to identify the channel with the remote peer.
  74  */
  75 struct GNUNET_CADET_ChannelTunnelNumber
  76 GCCH_get_id (const struct CadetChannel *ch);
  77
  78
  79 /**
  80  * Create a new channel.
  81  *
  82  * @param owner local client owning the channel
  83  * @param owner_id local chid of this channel at the @a owner
  84  * @param destination peer to which we should build the channel
  85  * @param port desired port at @a destination
  86  * @param options options for the channel
  87  * @return handle to the new channel
  88  */
  89 struct CadetChannel *
  90 GCCH_channel_local_new (struct CadetClient *owner,
  91                         struct GNUNET_CADET_ClientChannelNumber owner_id,
  92                         struct CadetPeer *destination,
  93                         const struct GNUNET_HashCode *port,
  94                         uint32_t options);
  95
  96
  97 /**
  98  * A client is bound to the port that we have a channel
  99  * open to.  Send the acknowledgement for the connection
 100  * request and establish the link with the client.
 101  *
 102  * @param ch open incoming channel
 103  * @param c client listening on the respective port
 104  */
 105 void
 106 GCCH_bind (struct CadetChannel *ch,
 107            struct CadetClient *c);
 108
 109
 110 /**
 111  * Destroy locally created channel.  Called by the
 112  * local client, so no need to tell the client.
 113  *
 114  * @param ch channel to destroy
 115  */
 116 void
 117 GCCH_channel_local_destroy (struct CadetChannel *ch);
 118
 119
 120 /**
 121  * Create a new channel based on a request coming in over the network.
 122  *
 123  * @param t tunnel to the remote peer
 124  * @param chid identifier of this channel in the tunnel
 125  * @param origin peer to who initiated the channel
 126  * @param port desired local port
 127  * @param options options for the channel
 128  * @return handle to the new channel
 129  */
 130 struct CadetChannel *
 131 GCCH_channel_incoming_new (struct CadetTunnel *t,
 132                            struct GNUNET_CADET_ChannelTunnelNumber chid,
 133                            const struct GNUNET_HashCode *port,
 134                            uint32_t options);
 135
 136
 137 /**
 138  * Destroy channel that was incoming.  Called by the
 139  * local client, so no need to tell the client.
 140  *
 141  * @param ch channel to destroy
 142  */
 143 void
 144 GCCH_channel_incoming_destroy (struct CadetChannel *ch);
 145
 146
 147 /**
 148  * Destroy channel, based on the other peer closing the
 149  * connection.  Also needs to remove this channel from
 150  * the tunnel.
 151  *
 152  * FIXME: need to make it possible to defer destruction until we have
 153  * received all messages up to the destroy, and right now the destroy
 154  * message (and this API) fails to give is the information we need!
 155  *
 156  * FIXME: also need to know if the other peer got a destroy from
 157  * us before!
 158  *
 159  * @param ch channel to destroy
 160  */
 161 void
 162 GCCH_channel_remote_destroy (struct CadetChannel *ch);
 163
 164
 165 /**
 166  * Handle data given by a client.
 167  *
 168  * Check whether the client is allowed to send in this tunnel, save if
 169  * channel is reliable and send an ACK to the client if there is still
 170  * buffer space in the tunnel.
 171  *
 172  * @param ch Channel.
 173  * @param message payload to transmit.
 174  * @return #GNUNET_OK if everything goes well,
 175  *         #GNUNET_SYSERR in case of an error.
 176  */
 177 int
 178 GCCH_handle_local_data (struct CadetChannel *ch,
 179                         const struct GNUNET_MessageHeader *message);
 180
 181
 182 /**
 183  * Handle ACK from client on local channel.
 184  *
 185  * @param ch channel to destroy
 186  */
 187 void
 188 GCCH_handle_local_ack (struct CadetChannel *ch);
 189
 190 #endif