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 /**
 216  * Handle a channel create requested by a client.
 217  *
 218  * Create the channel and the tunnel in case this was the first0 channel.
 219  *
 220  * @param c Client that requested the creation (will be the root).
 221  * @param msg Create Channel message.
 222  *
 223  * @return #GNUNET_OK if everything went fine, #GNUNET_SYSERR otherwise.
 224  */
 225 int
 226 GCCH_handle_local_create (struct CadetClient *c,
 227                           struct GNUNET_CADET_ChannelCreateMessage *msg);
 228
 229 /**
 230  * Handler for cadet network payload traffic.
 231  *
 232  * @param ch Channel for the message.
 233  * @param msg Unencryted data message.
 234  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 235  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 236  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 237  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 238  */
 239 void
 240 GCCH_handle_data (struct CadetChannel *ch,
 241                   const struct GNUNET_CADET_Data *msg,
 242                   int fwd);
 243
 244
 245 /**
 246  * Handler for cadet network traffic end-to-end ACKs.
 247  *
 248  * @param ch Channel on which we got this message.
 249  * @param msg Data message.
 250  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 251  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 252  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 253  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 254  */
 255 void
 256 GCCH_handle_data_ack (struct CadetChannel *ch,
 257                       const struct GNUNET_CADET_DataACK *msg,
 258                       int fwd);
 259
 260
 261 /**
 262  * Handler for channel create messages.
 263  *
 264  * Does not have fwd parameter because it's always 'FWD': channel is incoming.
 265  *
 266  * @param t Tunnel this channel will be in.
 267  * @param msg Channel crate message.
 268  */
 269 struct CadetChannel *
 270 GCCH_handle_create (struct CadetTunnel *t,
 271                     const struct GNUNET_CADET_ChannelCreate *msg);
 272
 273
 274 /**
 275  * Handler for channel NACK messages.
 276  *
 277  * NACK messages always go dest -> root, no need for 'fwd' or 'msg' parameter.
 278  *
 279  * @param ch Channel.
 280  */
 281 void
 282 GCCH_handle_nack (struct CadetChannel *ch);
 283
 284
 285 /**
 286  * Handler for channel ack messages.
 287  *
 288  * @param ch Channel this channel is to be created in.
 289  * @param msg Message.
 290  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 291  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 292  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 293  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 294  */
 295 void
 296 GCCH_handle_ack (struct CadetChannel *ch,
 297                  const struct GNUNET_CADET_ChannelManage *msg,
 298                  int fwd);
 299
 300
 301 /**
 302  * Handler for channel destroy messages.
 303  *
 304  * @param ch Channel this channel is to be destroyed of.
 305  * @param msg Message.
 306  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 307  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 308  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 309  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 310  */
 311 void
 312 GCCH_handle_destroy (struct CadetChannel *ch,
 313                      const struct GNUNET_CADET_ChannelManage *msg,
 314                      int fwd);
 315
 316
 317 /**
 318  * Sends an already built message on a channel.
 319  *
 320  * If the channel is on a loopback tunnel, notifies the appropriate destination
 321  * client locally.
 322  *
 323  * On a normal channel passes the message to the tunnel for encryption and
 324  * sending on a connection.
 325  *
 326  * This function DOES NOT save the message for retransmission.
 327  *
 328  * @param message Message to send. Function makes a copy of it.
 329  * @param ch Channel on which this message is transmitted.
 330  * @param fwd Is this a fwd message?
 331  * @param existing_copy This is a retransmission, don't save a copy.
 332  */
 333 void
 334 GCCH_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
 335                             struct CadetChannel *ch, int fwd,
 336                             void *existing_copy);
 337
 338
 339 /**
 340  * Get the static string for identification of the channel.
 341  *
 342  * @param ch Channel.i
 343  *
 344  * @return Static string with the channel IDs.
 345  */
 346 const char *
 347 GCCH_2s (const struct CadetChannel *ch);
 348
 349
 350 #if 0                           /* keep Emacsens' auto-indent happy */
 351 {
 352 #endif
 353 #ifdef __cplusplus
 354 }
 355 #endif
 356
 357 /* ifndef GNUNET_SERVICE_CADET_CHANNEL_H */
 358 #endif
 359 /* end of gnunet-service-cadet_channel.h */