src/cadet/gnunet-service-cadet_channel.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2013 Christian Grothoff (and other contributing authors)
   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., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, 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  */
 164 void
 165 GCCH_debug (struct CadetChannel *ch);
 166
 167 /**
 168  * Handle an ACK given by a client.
 169  *
 170  * Mark client as ready and send him any buffered data we could have for him.
 171  *
 172  * @param ch Channel.
 173  * @param fwd Is this a "FWD ACK"? (FWD ACKs are sent by root and go BCK)
 174  */
 175 void
 176 GCCH_handle_local_ack (struct CadetChannel *ch, int fwd);
 177
 178 /**
 179  * Handle data given by a client.
 180  *
 181  * Check whether the client is allowed to send in this tunnel, save if channel
 182  * is reliable and send an ACK to the client if there is still buffer space
 183  * in the tunnel.
 184  *
 185  * @param ch Channel.
 186  * @param c Client which sent the data.
 187  * @param fwd Is this a FWD data?
 188  * @param message Data message.
 189  * @param size Size of data.
 190  *
 191  * @return GNUNET_OK if everything goes well, GNUNET_SYSERR in case of en error.
 192  */
 193 int
 194 GCCH_handle_local_data (struct CadetChannel *ch,
 195                         struct CadetClient *c, int fwd,
 196                         const struct GNUNET_MessageHeader *message,
 197                         size_t size);
 198
 199 /**
 200  * Handle a channel destroy requested by a client.
 201  *
 202  * Destroy the channel and the tunnel in case this was the last channel.
 203  *
 204  * @param ch Channel.
 205  * @param c Client that requested the destruction (to avoid notifying him).
 206  * @param is_root Is the request coming from root?
 207  */
 208 void
 209 GCCH_handle_local_destroy (struct CadetChannel *ch,
 210                            struct CadetClient *c,
 211                            int is_root);
 212
 213 /**
 214  * Handle a channel create requested by a client.
 215  *
 216  * Create the channel and the tunnel in case this was the first0 channel.
 217  *
 218  * @param c Client that requested the creation (will be the root).
 219  * @param msg Create Channel message.
 220  *
 221  * @return GNUNET_OK if everything went fine, GNUNET_SYSERR otherwise.
 222  */
 223 int
 224 GCCH_handle_local_create (struct CadetClient *c,
 225                           struct GNUNET_CADET_ChannelMessage *msg);
 226
 227 /**
 228  * Handler for cadet network payload traffic.
 229  *
 230  * @param ch Channel for the message.
 231  * @param msg Unencryted data message.
 232  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 233  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 234  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 235  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 236  */
 237 void
 238 GCCH_handle_data (struct CadetChannel *ch,
 239                   const struct GNUNET_CADET_Data *msg,
 240                   int fwd);
 241
 242 /**
 243  * Handler for cadet network traffic end-to-end ACKs.
 244  *
 245  * @param ch Channel on which we got this message.
 246  * @param msg Data message.
 247  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 248  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 249  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 250  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 251  */
 252 void
 253 GCCH_handle_data_ack (struct CadetChannel *ch,
 254                       const struct GNUNET_CADET_DataACK *msg,
 255                       int fwd);
 256
 257 /**
 258  * Handler for channel create messages.
 259  *
 260  * Does not have fwd parameter because it's always 'FWD': channel is incoming.
 261  *
 262  * @param t Tunnel this channel will be in.
 263  * @param msg Channel crate message.
 264  */
 265 struct CadetChannel *
 266 GCCH_handle_create (struct CadetTunnel *t,
 267                     const struct GNUNET_CADET_ChannelCreate *msg);
 268
 269 /**
 270  * Handler for channel NACK messages.
 271  *
 272  * NACK messages always go dest -> root, no need for 'fwd' or 'msg' parameter.
 273  *
 274  * @param ch Channel.
 275  */
 276 void
 277 GCCH_handle_nack (struct CadetChannel *ch);
 278
 279 /**
 280  * Handler for channel ack messages.
 281  *
 282  * @param ch Channel this channel is to be created in.
 283  * @param msg Message.
 284  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 285  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 286  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 287  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 288  */
 289 void
 290 GCCH_handle_ack (struct CadetChannel *ch,
 291                  const struct GNUNET_CADET_ChannelManage *msg,
 292                  int fwd);
 293
 294 /**
 295  * Handler for channel destroy messages.
 296  *
 297  * @param ch Channel this channel is to be destroyed of.
 298  * @param msg Message.
 299  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 300  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 301  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 302  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 303  */
 304 void
 305 GCCH_handle_destroy (struct CadetChannel *ch,
 306                      const struct GNUNET_CADET_ChannelManage *msg,
 307                      int fwd);
 308
 309 /**
 310  * Sends an already built message on a channel.
 311  *
 312  * If the channel is on a loopback tunnel, notifies the appropriate destination
 313  * client locally.
 314  *
 315  * On a normal channel passes the message to the tunnel for encryption and
 316  * sending on a connection.
 317  *
 318  * This function DOES NOT save the message for retransmission.
 319  *
 320  * @param message Message to send. Function makes a copy of it.
 321  * @param ch Channel on which this message is transmitted.
 322  * @param fwd Is this a fwd message?
 323  * @param existing_copy This is a retransmission, don't save a copy.
 324  */
 325 void
 326 GCCH_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
 327                             struct CadetChannel *ch, int fwd,
 328                             void *existing_copy);
 329
 330 /**
 331  * Get the static string for identification of the channel.
 332  *
 333  * @param ch Channel.i
 334  *
 335  * @return Static string with the channel IDs.
 336  */
 337 const char *
 338 GCCH_2s (const struct CadetChannel *ch);
 339
 340
 341 #if 0                           /* keep Emacsens' auto-indent happy */
 342 {
 343 #endif
 344 #ifdef __cplusplus
 345 }
 346 #endif
 347
 348 /* ifndef GNUNET_SERVICE_CADET_CHANNEL_H */
 349 #endif
 350 /* end of gnunet-service-cadet_channel.h */