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 struct GNUNET_CADET_ChannelTunnelNumber
  73 GCCH_get_id (const struct CadetChannel *ch);
  74
  75
  76 /**
  77  * Get the channel tunnel.
  78  *
  79  * @param ch Channel to get the tunnel from.
  80  *
  81  * @return tunnel of the channel.
  82  */
  83 struct CadetTunnel *
  84 GCCH_get_tunnel (const struct CadetChannel *ch);
  85
  86
  87 /**
  88  * Get free buffer space towards the client on a specific channel.
  89  *
  90  * @param ch Channel.
  91  * @param fwd Is query about FWD traffic?
  92  *
  93  * @return Free buffer space [0 - 64]
  94  */
  95 unsigned int
  96 GCCH_get_buffer (struct CadetChannel *ch, int fwd);
  97
  98
  99 /**
 100  * Get flow control status of end point: is client allow to send?
 101  *
 102  * @param ch Channel.
 103  * @param fwd Is query about FWD traffic? (Request root status).
 104  *
 105  * @return #GNUNET_YES if client is allowed to send us data.
 106  */
 107 int
 108 GCCH_get_allowed (struct CadetChannel *ch, int fwd);
 109
 110
 111 /**
 112  * Is the root client for this channel on this peer?
 113  *
 114  * @param ch Channel.
 115  * @param fwd Is this for fwd traffic?
 116  *
 117  * @return #GNUNET_YES in case it is.
 118  */
 119 int
 120 GCCH_is_origin (struct CadetChannel *ch, int fwd);
 121
 122 /**
 123  * Is the destination client for this channel on this peer?
 124  *
 125  * @param ch Channel.
 126  * @param fwd Is this for fwd traffic?
 127  *
 128  * @return #GNUNET_YES in case it is.
 129  */
 130 int
 131 GCCH_is_terminal (struct CadetChannel *ch, int fwd);
 132
 133 /**
 134  * Send an end-to-end ACK message for the most recent in-sequence payload.
 135  *
 136  * If channel is not reliable, do nothing.
 137  *
 138  * @param ch Channel this is about.
 139  * @param fwd Is for FWD traffic? (ACK dest->owner)
 140  */
 141 void
 142 GCCH_send_data_ack (struct CadetChannel *ch, int fwd);
 143
 144 /**
 145  * Notify the destination client that a new incoming channel was created.
 146  *
 147  * @param ch Channel that was created.
 148  */
 149 void
 150 GCCH_send_create (struct CadetChannel *ch);
 151
 152 /**
 153  * Allow a client to send us more data, in case it was choked.
 154  *
 155  * @param ch Channel.
 156  * @param fwd Is this about FWD traffic? (Root client).
 157  */
 158 void
 159 GCCH_allow_client (struct CadetChannel *ch, int fwd);
 160
 161 /**
 162  * Log channel info.
 163  *
 164  * @param ch Channel.
 165  * @param level Debug level to use.
 166  */
 167 void
 168 GCCH_debug (struct CadetChannel *ch, enum GNUNET_ErrorType level);
 169
 170 /**
 171  * Handle an ACK given by a client.
 172  *
 173  * Mark client as ready and send him any buffered data we could have for him.
 174  *
 175  * @param ch Channel.
 176  * @param fwd Is this a "FWD ACK"? (FWD ACKs are sent by root and go BCK)
 177  */
 178 void
 179 GCCH_handle_local_ack (struct CadetChannel *ch, int fwd);
 180
 181 /**
 182  * Handle data given by a client.
 183  *
 184  * Check whether the client is allowed to send in this tunnel, save if channel
 185  * is reliable and send an ACK to the client if there is still buffer space
 186  * in the tunnel.
 187  *
 188  * @param ch Channel.
 189  * @param c Client which sent the data.
 190  * @param fwd Is this a FWD data?
 191  * @param message Data message.
 192  * @param size Size of data.
 193  *
 194  * @return GNUNET_OK if everything goes well, GNUNET_SYSERR in case of en error.
 195  */
 196 int
 197 GCCH_handle_local_data (struct CadetChannel *ch,
 198                         struct CadetClient *c, int fwd,
 199                         const struct GNUNET_MessageHeader *message,
 200                         size_t size);
 201
 202 /**
 203  * Handle a channel destroy requested by a client.
 204  *
 205  * Destroy the channel and the tunnel in case this was the last channel.
 206  *
 207  * @param ch Channel.
 208  * @param c Client that requested the destruction (to avoid notifying him).
 209  * @param is_root Is the request coming from root?
 210  */
 211 void
 212 GCCH_handle_local_destroy (struct CadetChannel *ch,
 213                            struct CadetClient *c,
 214                            int is_root);
 215
 216
 217 /**
 218  * Handle a channel create requested by a client.
 219  *
 220  * Create the channel and the tunnel in case this was the first0 channel.
 221  *
 222  * @param c Client that requested the creation (will be the root).
 223  * @param msg Create Channel message.
 224  *
 225  * @return #GNUNET_OK if everything went fine, #GNUNET_SYSERR otherwise.
 226  */
 227 int
 228 GCCH_handle_local_create (struct CadetClient *c,
 229                           struct GNUNET_CADET_LocalChannelCreateMessage *msg);
 230
 231 /**
 232  * Handler for cadet network payload traffic.
 233  *
 234  * @param ch Channel for the message.
 235  * @param msg Unencryted data message.
 236  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 237  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 238  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 239  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 240  */
 241 void
 242 GCCH_handle_data (struct CadetChannel *ch,
 243                   const struct GNUNET_CADET_ChannelAppDataMessage *msg,
 244                   int fwd);
 245
 246
 247 /**
 248  * Handler for cadet network traffic end-to-end ACKs.
 249  *
 250  * @param ch Channel on which we got this message.
 251  * @param msg Data message.
 252  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 253  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 254  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 255  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 256  */
 257 void
 258 GCCH_handle_data_ack (struct CadetChannel *ch,
 259                       const struct GNUNET_CADET_ChannelDataAckMessage *msg,
 260                       int fwd);
 261
 262
 263 /**
 264  * Handler for channel create messages.
 265  *
 266  * Does not have fwd parameter because it's always 'FWD': channel is incoming.
 267  *
 268  * @param t Tunnel this channel will be in.
 269  * @param msg Channel crate message.
 270  */
 271 struct CadetChannel *
 272 GCCH_handle_create (struct CadetTunnel *t,
 273                     const struct GNUNET_CADET_ChannelOpenMessage *msg);
 274
 275
 276 /**
 277  * Handler for channel NACK messages.
 278  *
 279  * NACK messages always go dest -> root, no need for 'fwd' or 'msg' parameter.
 280  *
 281  * @param ch Channel.
 282  */
 283 void
 284 GCCH_handle_nack (struct CadetChannel *ch);
 285
 286
 287 /**
 288  * Handler for channel ack messages.
 289  *
 290  * @param ch Channel this channel is to be created in.
 291  * @param msg Message.
 292  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 293  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 294  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 295  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 296  */
 297 void
 298 GCCH_handle_ack (struct CadetChannel *ch,
 299                  const struct GNUNET_CADET_ChannelManageMessage *msg,
 300                  int fwd);
 301
 302
 303 /**
 304  * Handler for channel destroy messages.
 305  *
 306  * @param ch Channel this channel is to be destroyed of.
 307  * @param msg Message.
 308  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 309  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 310  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 311  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 312  */
 313 void
 314 GCCH_handle_destroy (struct CadetChannel *ch,
 315                      const struct GNUNET_CADET_ChannelManageMessage *msg,
 316                      int fwd);
 317
 318
 319 /**
 320  * Sends an already built message on a channel.
 321  *
 322  * If the channel is on a loopback tunnel, notifies the appropriate destination
 323  * client locally.
 324  *
 325  * On a normal channel passes the message to the tunnel for encryption and
 326  * sending on a connection.
 327  *
 328  * This function DOES NOT save the message for retransmission.
 329  *
 330  * @param message Message to send. Function makes a copy of it.
 331  * @param ch Channel on which this message is transmitted.
 332  * @param fwd Is this a fwd message?
 333  * @param existing_copy This is a retransmission, don't save a copy.
 334  */
 335 void
 336 GCCH_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
 337                             struct CadetChannel *ch, int fwd,
 338                             void *existing_copy);
 339
 340
 341 /**
 342  * Get the static string for identification of the channel.
 343  *
 344  * @param ch Channel.i
 345  *
 346  * @return Static string with the channel IDs.
 347  */
 348 const char *
 349 GCCH_2s (const struct CadetChannel *ch);
 350
 351
 352
 353
 354 #if 0                           /* keep Emacsens' auto-indent happy */
 355 {
 356 #endif
 357 #ifdef __cplusplus
 358 }
 359 #endif
 360
 361 /* ifndef GNUNET_SERVICE_CADET_CHANNEL_H */
 362 #endif
 363 /* end of gnunet-service-cadet_channel.h */