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 /**
  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 MESH_ChannelNumber
  73 GMCH_get_id (const struct MeshChannel *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 MeshTunnel3 *
  83 GMCH_get_tunnel (const struct MeshChannel *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 GMCH_get_buffer (struct MeshChannel *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 GMCH_get_allowed (struct MeshChannel *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 GMCH_is_origin (struct MeshChannel *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 GMCH_is_terminal (struct MeshChannel *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 GMCH_send_data_ack (struct MeshChannel *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 GMCH_send_create (struct MeshChannel *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 GMCH_allow_client (struct MeshChannel *ch, int fwd);
 158
 159 /**
 160  * Log channel info.
 161  *
 162  * @param ch Channel.
 163  */
 164 void
 165 GMCH_debug (struct MeshChannel *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 GMCH_handle_local_ack (struct MeshChannel *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 message Message.
 188  * @param fwd Is this a FWD data?
 189  *
 190  * @return GNUNET_OK if everything goes well, GNUNET_SYSERR in case of en error.
 191  */
 192 int
 193 GMCH_handle_local_data (struct MeshChannel *ch,
 194                         struct MeshClient *c,
 195                         struct GNUNET_MessageHeader *message,
 196                         int fwd);
 197
 198 /**
 199  * Handle a channel destroy requested by a client.
 200  *
 201  * Destroy the channel and the tunnel in case this was the last channel.
 202  *
 203  * @param ch Channel.
 204  * @param c Client that requested the destruction (to avoid notifying him).
 205  * @param is_root Is the request coming from root?
 206  */
 207 void
 208 GMCH_handle_local_destroy (struct MeshChannel *ch,
 209                            struct MeshClient *c,
 210                            int is_root);
 211
 212 /**
 213  * Handle a channel create requested by a client.
 214  *
 215  * Create the channel and the tunnel in case this was the first0 channel.
 216  *
 217  * @param c Client that requested the creation (will be the root).
 218  * @param msg Create Channel message.
 219  *
 220  * @return GNUNET_OK if everything went fine, GNUNET_SYSERR otherwise.
 221  */
 222 int
 223 GMCH_handle_local_create (struct MeshClient *c,
 224                           struct GNUNET_MESH_ChannelMessage *msg);
 225
 226 /**
 227  * Handler for mesh network payload traffic.
 228  *
 229  * @param ch Channel for the message.
 230  * @param msg Unencryted data message.
 231  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 232  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 233  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 234  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 235  */
 236 void
 237 GMCH_handle_data (struct MeshChannel *ch,
 238                   const struct GNUNET_MESH_Data *msg,
 239                   int fwd);
 240
 241 /**
 242  * Handler for mesh network traffic end-to-end ACKs.
 243  *
 244  * @param ch Channel on which we got this message.
 245  * @param msg Data message.
 246  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 247  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 248  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 249  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 250  */
 251 void
 252 GMCH_handle_data_ack (struct MeshChannel *ch,
 253                       const struct GNUNET_MESH_DataACK *msg,
 254                       int fwd);
 255
 256 /**
 257  * Handler for channel create messages.
 258  *
 259  * Does not have fwd parameter because it's always 'FWD': channel is incoming.
 260  *
 261  * @param t Tunnel this channel will be in.
 262  * @param msg Channel crate message.
 263  */
 264 struct MeshChannel *
 265 GMCH_handle_create (struct MeshTunnel3 *t,
 266                     const struct GNUNET_MESH_ChannelCreate *msg);
 267
 268 /**
 269  * Handler for channel NACK messages.
 270  *
 271  * NACK messages always go dest -> root, no need for 'fwd' or 'msg' parameter.
 272  *
 273  * @param ch Channel.
 274  */
 275 void
 276 GMCH_handle_nack (struct MeshChannel *ch);
 277
 278 /**
 279  * Handler for channel ack messages.
 280  *
 281  * @param ch Channel this channel is to be created in.
 282  * @param msg Message.
 283  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 284  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 285  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 286  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 287  */
 288 void
 289 GMCH_handle_ack (struct MeshChannel *ch,
 290                  const struct GNUNET_MESH_ChannelManage *msg,
 291                  int fwd);
 292
 293 /**
 294  * Handler for channel destroy messages.
 295  *
 296  * @param ch Channel this channel is to be destroyed of.
 297  * @param msg Message.
 298  * @param fwd Is this message fwd? This only is meaningful in loopback channels.
 299  *            #GNUNET_YES if message is FWD on the respective channel (loopback)
 300  *            #GNUNET_NO if message is BCK on the respective channel (loopback)
 301  *            #GNUNET_SYSERR if message on a one-ended channel (remote)
 302  */
 303 void
 304 GMCH_handle_destroy (struct MeshChannel *ch,
 305                      const struct GNUNET_MESH_ChannelManage *msg,
 306                      int fwd);
 307
 308 /**
 309  * Sends an already built message on a channel.
 310  *
 311  * If the channel is on a loopback tunnel, notifies the appropriate destination
 312  * client locally.
 313  *
 314  * On a normal channel passes the message to the tunnel for encryption and
 315  * sending on a connection.
 316  *
 317  * This function DOES NOT save the message for retransmission.
 318  *
 319  * @param message Message to send. Function makes a copy of it.
 320  * @param ch Channel on which this message is transmitted.
 321  * @param fwd Is this a fwd message?
 322  * @param existing_copy This is a retransmission, don't save a copy.
 323  */
 324 void
 325 GMCH_send_prebuilt_message (const struct GNUNET_MessageHeader *message,
 326                             struct MeshChannel *ch, int fwd,
 327                             void *existing_copy);
 328
 329 /**
 330  * Get the static string for identification of the channel.
 331  *
 332  * @param ch Channel.i
 333  *
 334  * @return Static string with the channel IDs.
 335  */
 336 const char *
 337 GMCH_2s (const struct MeshChannel *ch);
 338
 339
 340 #if 0                           /* keep Emacsens' auto-indent happy */
 341 {
 342 #endif
 343 #ifdef __cplusplus
 344 }
 345 #endif
 346
 347 /* ifndef GNUNET_SERVICE_MESH_CHANNEL_H */
 348 #endif
 349 /* end of gnunet-service-mesh_channel.h */