src/mesh/gnunet-service-mesh_channel.h

   1 /*
   2      This file is part of GNUnet.
   3      (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 mesh/gnunet-service-mesh_channel.h
  23  * @brief mesh service; dealing with end-to-end channels
  24  * @author Bartlomiej Polot
  25  *
  26  * All functions in this file should use the prefix GMCH (Gnunet Mesh CHannel)
  27  */
  28
  29 #ifndef GNUNET_SERVICE_MESH_CHANNEL_H
  30 #define GNUNET_SERVICE_MESH_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 "mesh_protocol.h"
  44 #include "mesh.h"
  45
  46 /**
  47  * Struct containing all information regarding a channel to a remote client.
  48  */
  49 struct MeshChannel;
  50
  51
  52 #include "gnunet-service-mesh_tunnel.h"
  53 #include "gnunet-service-mesh_local.h"
  54
  55
  56 /**
  57  * Destroy a channel and free all resources.
  58  *
  59  * @param ch Channel to destroy.
  60  */
  61 void
  62 GMCH_destroy (struct MeshChannel *ch);
  63
  64 /**
  65  * Get channel ID.
  66  *
  67  * @param ch Channel.
  68  *
  69  * @return ID
  70  */
  71 MESH_ChannelNumber
  72 GMCH_get_id (const struct MeshChannel *ch);
  73
  74 /**
  75  * Get the channel tunnel.
  76  *
  77  * @param ch Channel to get the tunnel from.
  78  *
  79  * @return tunnel of the channel.
  80  */
  81 struct MeshTunnel3 *
  82 GMCH_get_tunnel (const struct MeshChannel *ch);
  83
  84 /**
  85  * Get free buffer space towards the client on a specific channel.
  86  *
  87  * @param ch Channel.
  88  * @param fwd Is query about FWD traffic?
  89  *
  90  * @return Free buffer space [0 - 64]
  91  */
  92 unsigned int
  93 GMCH_get_buffer (struct MeshChannel *ch, int fwd);
  94
  95
  96 /**
  97  * Get flow control status of end point: is client allow to send?
  98  *
  99  * @param ch Channel.
 100  * @param fwd Is query about FWD traffic? (Request root status).
 101  *
 102  * @return #GNUNET_YES if client is allowed to send us data.
 103  */
 104 int
 105 GMCH_get_allowed (struct MeshChannel *ch, int fwd);
 106
 107
 108 /**
 109  * Is the root client for this channel on this peer?
 110  *
 111  * @param ch Channel.
 112  * @param fwd Is this for fwd traffic?
 113  *
 114  * @return #GNUNET_YES in case it is.
 115  */
 116 int
 117 GMCH_is_origin (struct MeshChannel *ch, int fwd);
 118
 119 /**
 120  * Is the destination client for this channel on this peer?
 121  *
 122  * @param ch Channel.
 123  * @param fwd Is this for fwd traffic?
 124  *
 125  * @return #GNUNET_YES in case it is.
 126  */
 127 int
 128 GMCH_is_terminal (struct MeshChannel *ch, int fwd);
 129
 130 /**
 131  * Send an end-to-end ACK message for the most recent in-sequence payload.
 132  *
 133  * If channel is not reliable, do nothing.
 134  *
 135  * @param ch Channel this is about.
 136  * @param fwd Is for FWD traffic? (ACK dest->owner)
 137  */
 138 void
 139 GMCH_send_data_ack (struct MeshChannel *ch, int fwd);
 140
 141 /**
 142  * Notify the destination client that a new incoming channel was created.
 143  *
 144  * @param ch Channel that was created.
 145  */
 146 void
 147 GMCH_send_create (struct MeshChannel *ch);
 148
 149 /**
 150  * Allow a client to send us more data, in case it was choked.
 151  *
 152  * @param ch Channel.
 153  * @param fwd Is this about FWD traffic? (Root client).
 154  */
 155 void
 156 GMCH_allow_client (struct MeshChannel *ch, int fwd);
 157
 158 /**
 159  * Log channel info.
 160  *
 161  * @param ch Channel.
 162  */
 163 void
 164 GMCH_debug (struct MeshChannel *ch);
 165
 166 /**
 167  * Handle an ACK given by a client.
 168  *
 169  * Mark client as ready and send him any buffered data we could have for him.
 170  *
 171  * @param ch Channel.
 172  * @param fwd Is this a "FWD ACK"? (FWD ACKs are sent by root and go BCK)
 173  */
 174 void
 175 GMCH_handle_local_ack (struct MeshChannel *ch, int fwd);
 176
 177 /**
 178  * Handle data given by a client.
 179  *
 180  * Check whether the client is allowed to send in this tunnel, save if channel
 181  * is reliable and send an ACK to the client if there is still buffer space
 182  * in the tunnel.
 183  *
 184  * @param ch Channel.
 185  * @param c Client which sent the data.
 186  * @param message Message.
 187  * @param fwd Is this a FWD data?
 188  *
 189  * @return GNUNET_OK if everything goes well, GNUNET_SYSERR in case of en error.
 190  */
 191 int
 192 GMCH_handle_local_data (struct MeshChannel *ch,
 193                         struct MeshClient *c,
 194                         struct GNUNET_MessageHeader *message,
 195                         int fwd);
 196
 197 /**
 198  * Handle a channel destroy requested by a client.
 199  *
 200  * Destroy the channel and the tunnel in case this was the last channel.
 201  *
 202  * @param ch Channel.
 203  * @param c Client that requested the destruction (to avoid notifying him).
 204  * @param is_root Is the request coming from root?
 205  */
 206 void
 207 GMCH_handle_local_destroy (struct MeshChannel *ch,
 208                            struct MeshClient *c,
 209                            int is_root);
 210
 211 /**
 212  * Handle a channel create requested by a client.
 213  *
 214  * Create the channel and the tunnel in case this was the first0 channel.
 215  *
 216  * @param c Client that requested the creation (will be the root).
 217  * @param msg Create Channel message.
 218  *
 219  * @return GNUNET_OK if everything went fine, GNUNET_SYSERR otherwise.
 220  */
 221 int
 222 GMCH_handle_local_create (struct MeshClient *c,
 223                           struct GNUNET_MESH_ChannelMessage *msg);
 224
 225 /**
 226  * Handler for mesh network payload traffic.
 227  *
 228  * @param ch Channel for the message.
 229  * @param msg Unencryted data message.
 230  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 231  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 232  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 233  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 234  */
 235 void
 236 GMCH_handle_data (struct MeshChannel *ch,
 237                   const struct GNUNET_MESH_Data *msg,
 238                   int fwd);
 239
 240 /**
 241  * Handler for mesh network traffic end-to-end ACKs.
 242  *
 243  * @param ch Channel on which we got this message.
 244  * @param msg Data message.
 245  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 246  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 247  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 248  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 249  */
 250 void
 251 GMCH_handle_data_ack (struct MeshChannel *ch,
 252                       const struct GNUNET_MESH_DataACK *msg,
 253                       int fwd);
 254
 255 /**
 256  * Handler for channel create messages.
 257  *
 258  * Does not have fwd parameter because it's always 'FWD': channel is incoming.
 259  *
 260  * @param t Tunnel this channel will be in.
 261  * @param msg Channel crate message.
 262  */
 263 struct MeshChannel *
 264 GMCH_handle_create (struct MeshTunnel3 *t,
 265                     const struct GNUNET_MESH_ChannelCreate *msg);
 266
 267 /**
 268  * Handler for channel NACK messages.
 269  *
 270  * NACK messages always go dest -> root, no need for 'fwd' or 'msg' parameter.
 271  *
 272  * @param ch Channel.
 273  */
 274 void
 275 GMCH_handle_nack (struct MeshChannel *ch);
 276
 277 /**
 278  * Handler for channel ack messages.
 279  *
 280  * @param ch Channel this channel is to be created in.
 281  * @param msg Message.
 282  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 283  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 284  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 285  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 286  */
 287 void
 288 GMCH_handle_ack (struct MeshChannel *ch,
 289                  const struct GNUNET_MESH_ChannelManage *msg,
 290                  int fwd);
 291
 292 /**
 293  * Handler for channel destroy messages.
 294  *
 295  * @param ch Channel this channel is to be destroyed of.
 296  * @param msg Message.
 297  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 298  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 299  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 300  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 301  */
 302 void
 303 GMCH_handle_destroy (struct MeshChannel *ch,
 304                      const struct GNUNET_MESH_ChannelManage *msg,
 305                      int fwd);
 306
 307 /**
 308  * Sends an already built message on a channel.
 309  *
 310  * If the channel is on a loopback tunnel, notifies the appropriate destination
 311  * client locally.
 312  *
 313  * On a normal channel passes the message to the tunnel for encryption and
 314  * sending on a connection.
 315  *
 316  * @param message Message to send. Function makes a copy of it.
 317  * @param ch Channel on which this message is transmitted.
 318  * @param fwd Is this a fwd message?
 319  * @param retransmission Is this a retransmission? (Don't save a copy)
 320  */
 321 void
 322 GMCH_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
 323                             struct MeshChannel *ch, int fwd,
 324                             int retransmission);
 325
 326 /**
 327  * Get the static string for identification of the channel.
 328  *
 329  * @param ch Channel.i
 330  *
 331  * @return Static string with the channel IDs.
 332  */
 333 const char *
 334 GMCH_2s (const struct MeshChannel *ch);
 335
 336
 337 #if 0                           /* keep Emacsens' auto-indent happy */
 338 {
 339 #endif
 340 #ifdef __cplusplus
 341 }
 342 #endif
 343
 344 /* ifndef GNUNET_SERVICE_MESH_CHANNEL_H */
 345 #endif
 346 /* end of gnunet-service-mesh_channel.h */