src/mesh/gnunet-service-mesh_tunnel.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_tunnel.h
  23  * @brief mesh service; dealing with tunnels and crypto
  24  * @author Bartlomiej Polot
  25  *
  26  * All functions in this file should use the prefix GMT (Gnunet Mesh Tunnel)
  27  */
  28
  29 #ifndef GNUNET_SERVICE_MESH_TUNNEL_H
  30 #define GNUNET_SERVICE_MESH_TUNNEL_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 "gnunet-service-mesh_channel.h"
  44 #include "gnunet-service-mesh_connection.h"
  45
  46 /**
  47  * All the states a tunnel can be in.
  48  */
  49 enum MeshTunnelState
  50 {
  51     /**
  52      * Uninitialized status, should never appear in operation.
  53      */
  54   MESH_TUNNEL_NEW,
  55
  56     /**
  57      * Path to the peer not known yet
  58      */
  59   MESH_TUNNEL_SEARCHING,
  60
  61     /**
  62      * Request sent, not yet answered.
  63      */
  64   MESH_TUNNEL_WAITING,
  65
  66     /**
  67      * Peer connected and ready to accept data
  68      */
  69   MESH_TUNNEL_READY,
  70
  71     /**
  72      * Peer connected previosly but not responding
  73      */
  74   MESH_TUNNEL_RECONNECTING
  75 };
  76
  77 /**
  78  * Struct containing all information regarding a given peer
  79  */
  80 struct MeshTunnel3;
  81
  82 /******************************************************************************/
  83 /********************************    API    ***********************************/
  84 /******************************************************************************/
  85
  86 /**
  87  * Initialize tunnel subsystem.
  88  *
  89  * @param c Configuration handle.
  90  * @param id Peer identity.
  91  * @param key ECC private key, to derive all other keys and do crypto.
  92  */
  93 void
  94 GMT_init (const struct GNUNET_CONFIGURATION_Handle *c,
  95           const struct GNUNET_PeerIdentity *id,
  96           const struct GNUNET_CRYPTO_EccPrivateKey *key);
  97
  98 /**
  99  * Shut down the tunnel subsystem.
 100  */
 101 void
 102 GMT_shutdown (void);
 103
 104 /**
 105  * Tunnel is empty: destroy it.
 106  *
 107  * Notifies all connections about the destruction.
 108  *
 109  * @param t Tunnel to destroy.
 110  */
 111 void
 112 GMT_destroy_empty (struct MeshTunnel3 *t);
 113
 114 /**
 115  * Destroy tunnel if empty (no more channels).
 116  *
 117  * @param t Tunnel to destroy if empty.
 118  */
 119 void
 120 GMT_destroy_if_empty (struct MeshTunnel3 *t);
 121
 122 /**
 123  * Destroy the tunnel.
 124  *
 125  * This function does not generate any warning traffic to clients or peers.
 126  *
 127  * Tasks:
 128  * Cancel messages belonging to this tunnel queued to neighbors.
 129  * Free any allocated resources linked to the tunnel.
 130  *
 131  * @param t The tunnel to destroy.
 132  */
 133 void
 134 GMT_destroy (struct MeshTunnel3 *t);
 135
 136 /**
 137  * Change the tunnel state.
 138  *
 139  * @param t Tunnel whose state to change.
 140  * @param state New state.
 141  */
 142 void
 143 GMT_change_state (struct MeshTunnel3* t, enum MeshTunnelState state);
 144
 145 /**
 146  * Add a connection to a tunnel.
 147  *
 148  * @param t Tunnel.
 149  * @param c Connection.
 150  */
 151 void
 152 GMT_add_connection (struct MeshTunnel3 *t, struct MeshConnection *c);
 153
 154
 155 /**
 156  * Remove a connection from a tunnel.
 157  *
 158  * @param t Tunnel.
 159  * @param c Connection.
 160  */
 161 void
 162 GMT_remove_connection (struct MeshTunnel3 *t, struct MeshConnection *c);
 163
 164 /**
 165  * Cache a message to be sent once tunnel is online.
 166  *
 167  * @param t Tunnel to hold the message.
 168  * @param ch Channel the message is about.
 169  * @param msg Message itself (copy will be made).
 170  * @param fwd Is this fwd?
 171  */
 172 void
 173 GMT_queue_data (struct MeshTunnel3 *t,
 174                 struct MeshChannel *ch,
 175                 struct GNUNET_MessageHeader *msg,
 176                 int fwd);
 177
 178 /**
 179  * Count established (ready) connections of a tunnel.
 180  *
 181  * @param t Tunnel on which to count.
 182  *
 183  * @return Number of connections.
 184  */
 185 unsigned int
 186 GMT_count_connections (struct MeshTunnel3 *t);
 187
 188 /**
 189  * Count channels of a tunnel.
 190  *
 191  * @param t Tunnel on which to count.
 192  *
 193  * @return Number of channels.
 194  */
 195 unsigned int
 196 GMT_count_channels (struct MeshTunnel3 *t);
 197
 198 /**
 199  * Get the total buffer space for a tunnel.
 200  *
 201  * @param t Tunnel.
 202  * @param fwd Is this for FWD traffic?
 203  *
 204  * @return Buffer space offered by all connections in the tunnel.
 205  */
 206 unsigned int
 207 GMT_get_buffer (struct MeshTunnel3 *t, int fwd);
 208
 209 #if 0                           /* keep Emacsens' auto-indent happy */
 210 {
 211 #endif
 212 #ifdef __cplusplus
 213 }
 214 #endif
 215
 216 /* ifndef GNUNET_MESH_SERVICE_TUNNEL_H */
 217 #endif
 218 /* end of gnunet-mesh-service_tunnel.h */