src/cadet/gnunet-service-cadet_channel.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2013 GNUnet e.V.
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      option) any later version.
   9
  10      GNUnet is distributed in the hope that it will be useful, but
  11      WITHOUT ANY WARRANTY; without even the implied warranty of
  12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @file cadet/gnunet-service-cadet_channel.h
  23  * @brief cadet service; dealing with end-to-end channels
  24  * @author Bartlomiej Polot
  25  *
  26  * All functions in this file should use the prefix GMCH (Gnunet Cadet CHannel)
  27  */
  28
  29 #ifndef GNUNET_SERVICE_CADET_CHANNEL_H
  30 #define GNUNET_SERVICE_CADET_CHANNEL_H
  31
  32 #ifdef __cplusplus
  33 extern "C"
  34 {
  35 #if 0                           /* keep Emacsens' auto-indent happy */
  36 }
  37 #endif
  38 #endif
  39
  40 #include "platform.h"
  41 #include "gnunet_util_lib.h"
  42
  43 #include "cadet_protocol.h"
  44 #include "cadet.h"
  45
  46 /**
  47  * Struct containing all information regarding a channel to a remote client.
  48  */
  49 struct CadetChannel;
  50
  51
  52 #include "gnunet-service-cadet_tunnel.h"
  53 #include "gnunet-service-cadet_local.h"
  54
  55
  56 /**
  57  * Destroy a channel and free all resources.
  58  *
  59  * @param ch Channel to destroy.
  60  */
  61 void
  62 GCCH_destroy (struct CadetChannel *ch);
  63
  64
  65 /**
  66  * Get the channel's public ID.
  67  *
  68  * @param ch Channel.
  69  *
  70  * @return ID used to identify the channel with the remote peer.
  71  */
  72 CADET_ChannelNumber
  73 GCCH_get_id (const struct CadetChannel *ch);
  74
  75 /**
  76  * Get the channel tunnel.
  77  *
  78  * @param ch Channel to get the tunnel from.
  79  *
  80  * @return tunnel of the channel.
  81  */
  82 struct CadetTunnel *
  83 GCCH_get_tunnel (const struct CadetChannel *ch);
  84
  85 /**
  86  * Get free buffer space towards the client on a specific channel.
  87  *
  88  * @param ch Channel.
  89  * @param fwd Is query about FWD traffic?
  90  *
  91  * @return Free buffer space [0 - 64]
  92  */
  93 unsigned int
  94 GCCH_get_buffer (struct CadetChannel *ch, int fwd);
  95
  96
  97 /**
  98  * Get flow control status of end point: is client allow to send?
  99  *
 100  * @param ch Channel.
 101  * @param fwd Is query about FWD traffic? (Request root status).
 102  *
 103  * @return #GNUNET_YES if client is allowed to send us data.
 104  */
 105 int
 106 GCCH_get_allowed (struct CadetChannel *ch, int fwd);
 107
 108
 109 /**
 110  * Is the root client for this channel on this peer?
 111  *
 112  * @param ch Channel.
 113  * @param fwd Is this for fwd traffic?
 114  *
 115  * @return #GNUNET_YES in case it is.
 116  */
 117 int
 118 GCCH_is_origin (struct CadetChannel *ch, int fwd);
 119
 120 /**
 121  * Is the destination client for this channel on this peer?
 122  *
 123  * @param ch Channel.
 124  * @param fwd Is this for fwd traffic?
 125  *
 126  * @return #GNUNET_YES in case it is.
 127  */
 128 int
 129 GCCH_is_terminal (struct CadetChannel *ch, int fwd);
 130
 131 /**
 132  * Send an end-to-end ACK message for the most recent in-sequence payload.
 133  *
 134  * If channel is not reliable, do nothing.
 135  *
 136  * @param ch Channel this is about.
 137  * @param fwd Is for FWD traffic? (ACK dest->owner)
 138  */
 139 void
 140 GCCH_send_data_ack (struct CadetChannel *ch, int fwd);
 141
 142 /**
 143  * Notify the destination client that a new incoming channel was created.
 144  *
 145  * @param ch Channel that was created.
 146  */
 147 void
 148 GCCH_send_create (struct CadetChannel *ch);
 149
 150 /**
 151  * Allow a client to send us more data, in case it was choked.
 152  *
 153  * @param ch Channel.
 154  * @param fwd Is this about FWD traffic? (Root client).
 155  */
 156 void
 157 GCCH_allow_client (struct CadetChannel *ch, int fwd);
 158
 159 /**
 160  * Log channel info.
 161  *
 162  * @param ch Channel.
 163  * @param level Debug level to use.
 164  */
 165 void
 166 GCCH_debug (struct CadetChannel *ch, enum GNUNET_ErrorType level);
 167
 168 /**
 169  * Handle an ACK given by a client.
 170  *
 171  * Mark client as ready and send him any buffered data we could have for him.
 172  *
 173  * @param ch Channel.
 174  * @param fwd Is this a "FWD ACK"? (FWD ACKs are sent by root and go BCK)
 175  */
 176 void
 177 GCCH_handle_local_ack (struct CadetChannel *ch, int fwd);
 178
 179 /**
 180  * Handle data given by a client.
 181  *
 182  * Check whether the client is allowed to send in this tunnel, save if channel
 183  * is reliable and send an ACK to the client if there is still buffer space
 184  * in the tunnel.
 185  *
 186  * @param ch Channel.
 187  * @param c Client which sent the data.
 188  * @param fwd Is this a FWD data?
 189  * @param message Data message.
 190  * @param size Size of data.
 191  *
 192  * @return GNUNET_OK if everything goes well, GNUNET_SYSERR in case of en error.
 193  */
 194 int
 195 GCCH_handle_local_data (struct CadetChannel *ch,
 196                         struct CadetClient *c, int fwd,
 197                         const struct GNUNET_MessageHeader *message,
 198                         size_t size);
 199
 200 /**
 201  * Handle a channel destroy requested by a client.
 202  *
 203  * Destroy the channel and the tunnel in case this was the last channel.
 204  *
 205  * @param ch Channel.
 206  * @param c Client that requested the destruction (to avoid notifying him).
 207  * @param is_root Is the request coming from root?
 208  */
 209 void
 210 GCCH_handle_local_destroy (struct CadetChannel *ch,
 211                            struct CadetClient *c,
 212                            int is_root);
 213
 214 /**
 215  * Handle a channel create requested by a client.
 216  *
 217  * Create the channel and the tunnel in case this was the first0 channel.
 218  *
 219  * @param c Client that requested the creation (will be the root).
 220  * @param msg Create Channel message.
 221  *
 222  * @return GNUNET_OK if everything went fine, GNUNET_SYSERR otherwise.
 223  */
 224 int
 225 GCCH_handle_local_create (struct CadetClient *c,
 226                           struct GNUNET_CADET_ChannelMessage *msg);
 227
 228 /**
 229  * Handler for cadet network payload traffic.
 230  *
 231  * @param ch Channel for the message.
 232  * @param msg Unencryted data message.
 233  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 234  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 235  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 236  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 237  */
 238 void
 239 GCCH_handle_data (struct CadetChannel *ch,
 240                   const struct GNUNET_CADET_Data *msg,
 241                   int fwd);
 242
 243 /**
 244  * Handler for cadet network traffic end-to-end ACKs.
 245  *
 246  * @param ch Channel on which we got this message.
 247  * @param msg Data message.
 248  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 249  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 250  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 251  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 252  */
 253 void
 254 GCCH_handle_data_ack (struct CadetChannel *ch,
 255                       const struct GNUNET_CADET_DataACK *msg,
 256                       int fwd);
 257
 258 /**
 259  * Handler for channel create messages.
 260  *
 261  * Does not have fwd parameter because it's always 'FWD': channel is incoming.
 262  *
 263  * @param t Tunnel this channel will be in.
 264  * @param msg Channel crate message.
 265  */
 266 struct CadetChannel *
 267 GCCH_handle_create (struct CadetTunnel *t,
 268                     const struct GNUNET_CADET_ChannelCreate *msg);
 269
 270 /**
 271  * Handler for channel NACK messages.
 272  *
 273  * NACK messages always go dest -> root, no need for 'fwd' or 'msg' parameter.
 274  *
 275  * @param ch Channel.
 276  */
 277 void
 278 GCCH_handle_nack (struct CadetChannel *ch);
 279
 280 /**
 281  * Handler for channel ack messages.
 282  *
 283  * @param ch Channel this channel is to be created in.
 284  * @param msg Message.
 285  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 286  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 287  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 288  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 289  */
 290 void
 291 GCCH_handle_ack (struct CadetChannel *ch,
 292                  const struct GNUNET_CADET_ChannelManage *msg,
 293                  int fwd);
 294
 295 /**
 296  * Handler for channel destroy messages.
 297  *
 298  * @param ch Channel this channel is to be destroyed of.
 299  * @param msg Message.
 300  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 301  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 302  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 303  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 304  */
 305 void
 306 GCCH_handle_destroy (struct CadetChannel *ch,
 307                      const struct GNUNET_CADET_ChannelManage *msg,
 308                      int fwd);
 309
 310 /**
 311  * Sends an already built message on a channel.
 312  *
 313  * If the channel is on a loopback tunnel, notifies the appropriate destination
 314  * client locally.
 315  *
 316  * On a normal channel passes the message to the tunnel for encryption and
 317  * sending on a connection.
 318  *
 319  * This function DOES NOT save the message for retransmission.
 320  *
 321  * @param message Message to send. Function makes a copy of it.
 322  * @param ch Channel on which this message is transmitted.
 323  * @param fwd Is this a fwd message?
 324  * @param existing_copy This is a retransmission, don't save a copy.
 325  */
 326 void
 327 GCCH_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
 328                             struct CadetChannel *ch, int fwd,
 329                             void *existing_copy);
 330
 331 /**
 332  * Get the static string for identification of the channel.
 333  *
 334  * @param ch Channel.i
 335  *
 336  * @return Static string with the channel IDs.
 337  */
 338 const char *
 339 GCCH_2s (const struct CadetChannel *ch);
 340
 341
 342 #if 0                           /* keep Emacsens' auto-indent happy */
 343 {
 344 #endif
 345 #ifdef __cplusplus
 346 }
 347 #endif
 348
 349 /* ifndef GNUNET_SERVICE_CADET_CHANNEL_H */
 350 #endif
 351 /* end of gnunet-service-cadet_channel.h */