src/mesh/mesh.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2001 - 2011 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  * @author Bartlomiej Polot
  23  * @file mesh/mesh.h
  24  */
  25
  26 #ifndef MESH_H_
  27 #define MESH_H_
  28 #include <stdint.h>
  29
  30 #define MESH_DEBUG              GNUNET_YES
  31
  32 #define INITIAL_WINDOW_SIZE     8
  33 #define ACK_THRESHOLD           INITIAL_WINDOW_SIZE / 2
  34
  35 #include "platform.h"
  36 #include "gnunet_common.h"
  37 #include "gnunet_util_lib.h"
  38 #include "gnunet_peer_lib.h"
  39 #include "gnunet_core_service.h"
  40 #include "gnunet_protocols.h"
  41 #include <gnunet_mesh_service.h>
  42
  43 /******************************************************************************/
  44 /********************        MESH LOCAL MESSAGES      *************************/
  45 /******************************************************************************/
  46 /*  Any API call should be documented in the folowing table under API CALL.
  47  *  Also, any message type should be documented in the following table, with the
  48  * associated event.
  49  *
  50  * API CALL (GNUNET_MESH_*)             MESSAGE USED
  51  * ------------------------             ------------
  52  * connect                              GNUNET_MESH_ClientConnect
  53  * disconnect                           None (network level disconnect)
  54  *
  55  * tunnel_create                        GNUNET_MESH_TunnelMessage
  56  * tunnel_destroy                       GNUNET_MESH_TunnelMessage
  57  *
  58  * peer_request_connect_add             GNUNET_MESH_PeerControl
  59  * peer_request_connect_del             GNUNET_MESH_PeerControl
  60  * peer_request_connect_by_type         GNUNET_MESH_ConnectPeerByType
  61  *
  62  * notify_transmit_ready                *GNUNET_MESH_TransmitReady?*
  63  * notify_transmit_ready_cancel         None (clear of internal data structures)
  64  *
  65  *
  66  *
  67  * EVENT                                MESSAGE USED
  68  * -----                                ------------
  69  * data                                 GNUNET_MESH_Data OR
  70  *                                      GNUNET_MESH_DataBroadcast
  71  * new incoming tunnel                  GNUNET_MESH_PeerControl
  72  * peer connects to a tunnel            GNUNET_MESH_PeerControl
  73  * peer disconnects from a tunnel       GNUNET_MESH_PeerControl
  74  */
  75
  76 /******************************************************************************/
  77 /**************************       CONSTANTS      ******************************/
  78 /******************************************************************************/
  79
  80 #define GNUNET_MESH_LOCAL_TUNNEL_ID_CLI         0x80000000
  81 #define GNUNET_MESH_LOCAL_TUNNEL_ID_SERV        0xB0000000
  82
  83 #define HIGH_PID                                0xFFFF0000
  84 #define LOW_PID                                 0x0000FFFF
  85
  86 #define PID_OVERFLOW(pid, max) (pid > HIGH_PID && max < LOW_PID)
  87
  88 /******************************************************************************/
  89 /**************************        MESSAGES      ******************************/
  90 /******************************************************************************/
  91
  92 GNUNET_NETWORK_STRUCT_BEGIN
  93
  94 /**
  95  * Message for a client to register to the service
  96  */
  97 struct GNUNET_MESH_ClientConnect
  98 {
  99     /**
 100      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_CONNECT
 101      *
 102      * Size: sizeof(struct GNUNET_MESH_ClientConnect) +
 103      *       sizeof(MESH_ApplicationType) * applications +
 104      *       sizeof(uint16_t) * types
 105      */
 106   struct GNUNET_MessageHeader header;
 107   uint16_t applications GNUNET_PACKED;
 108   uint16_t types GNUNET_PACKED;
 109   /* uint16_t                 list_apps[applications]     */
 110   /* uint16_t                 list_types[types]           */
 111 };
 112
 113
 114 /**
 115  * Type for tunnel numbering.
 116  * - Local tunnel numbers given by the service (incoming) are >= 0xB0000000
 117  * - Local tunnel numbers given by the client (created) are >= 0x80000000
 118  * - Global tunnel numbers are < 0x80000000
 119  */
 120 typedef uint32_t MESH_TunnelNumber;
 121
 122 /**
 123  * Message for a client to create and destroy tunnels.
 124  */
 125 struct GNUNET_MESH_TunnelMessage
 126 {
 127     /**
 128      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_TUNNEL_[CREATE|DESTROY]
 129      *       GNUNET_MESSAGE_TYPE_MESH_LOCAL_TUNNEL_[MAX|MIN]
 130      *
 131      * Size: sizeof(struct GNUNET_MESH_TunnelMessage)
 132      */
 133   struct GNUNET_MessageHeader header;
 134
 135     /**
 136      * ID of a tunnel controlled by this client.
 137      */
 138   MESH_TunnelNumber tunnel_id GNUNET_PACKED;
 139 };
 140
 141
 142 /**
 143  * Message for the service to let a client know about created tunnels.
 144  */
 145 struct GNUNET_MESH_TunnelNotification
 146 {
 147     /**
 148      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_TUNNEL_CREATE
 149      *
 150      * Size: sizeof(struct GNUNET_MESH_TunnelMessage)
 151      */
 152   struct GNUNET_MessageHeader header;
 153
 154     /**
 155      * ID of a tunnel controlled by this client.
 156      */
 157   MESH_TunnelNumber tunnel_id GNUNET_PACKED;
 158
 159     /**
 160      * Peer at the other end, if any
 161      */
 162   struct GNUNET_PeerIdentity peer;
 163 };
 164
 165 /**
 166  * Message for:
 167  * - request adding and deleting peers from a tunnel
 168  * - notify the client that peers have connected:
 169  *   -- requested
 170  *   -- unrequested (new incoming tunnels)
 171  * - notify the client that peers have disconnected
 172  */
 173 struct GNUNET_MESH_PeerControl
 174 {
 175
 176     /**
 177      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_CONNECT_PEER_[ADD|DEL|[UN]BLACKLIST]
 178      *       (client to service, client created tunnel)
 179      *       GNUNET_MESSAGE_TYPE_MESH_LOCAL_PEER_[CONNECTED|DISCONNECTED]
 180      *       (service to client)
 181      *
 182      * Size: sizeof(struct GNUNET_MESH_PeerControl)
 183      */
 184   struct GNUNET_MessageHeader header;
 185
 186     /**
 187      * ID of a tunnel controlled by this client.
 188      */
 189   MESH_TunnelNumber tunnel_id GNUNET_PACKED;
 190
 191     /**
 192      * Peer to connect/disconnect.
 193      */
 194   struct GNUNET_PeerIdentity peer;
 195 };
 196
 197
 198 /**
 199  * Message for connecting to peers offering a service, by service number.
 200  */
 201 struct GNUNET_MESH_ConnectPeerByType
 202 {
 203     /**
 204      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_CONNECT_PEER_BY_TYPE |
 205      *       GNUNET_MESSAGE_TYPE_MESH_LOCAL_DISCONNECT_PEER_BY_TYPE
 206      *
 207      * Size: sizeof(struct GNUNET_MESH_ConnectPeerByType)
 208      */
 209   struct GNUNET_MessageHeader header;
 210
 211     /**
 212      * ID of a tunnel controlled by this client.
 213      */
 214   MESH_TunnelNumber tunnel_id GNUNET_PACKED;
 215
 216     /**
 217      * Type specification
 218      */
 219   GNUNET_MESH_ApplicationType type GNUNET_PACKED;
 220 };
 221
 222
 223 /**
 224  * Message for connecting to peers offering a service, by service string.
 225  */
 226 struct GNUNET_MESH_ConnectPeerByString
 227 {
 228     /**
 229      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_PEER_ADD_BY_STRING
 230      *
 231      * Size: sizeof(struct GNUNET_MESH_ConnectPeerByString) + strlen (string)
 232      */
 233   struct GNUNET_MessageHeader header;
 234
 235     /**
 236      * ID of a tunnel controlled by this client.
 237      */
 238   MESH_TunnelNumber tunnel_id GNUNET_PACKED;
 239
 240   /* String describing the service */
 241 };
 242
 243
 244 /**
 245  * Message to allow the client send more data to the service
 246  * (always service -> client).
 247  */
 248 struct GNUNET_MESH_LocalAck
 249 {
 250     /**
 251      * Type: GNUNET_MESSAGE_TYPE_MESH_LOCAL_ACK
 252      */
 253   struct GNUNET_MessageHeader header;
 254
 255     /**
 256      * ID of the tunnel allowed to send more data.
 257      */
 258   MESH_TunnelNumber tunnel_id GNUNET_PACKED;
 259
 260     /**
 261      * ID of the last packet allowed.
 262      */
 263   uint32_t max_pid GNUNET_PACKED;
 264 };
 265
 266
 267 GNUNET_NETWORK_STRUCT_END
 268
 269 /******************************************************************************/
 270 /************************        ENUMERATIONS      ****************************/
 271 /******************************************************************************/
 272
 273 /**
 274  * All the states a peer participating in a tunnel can be in.
 275  */
 276 enum MeshPeerState
 277 {
 278     /**
 279      * Uninitialized status, should never appear in operation.
 280      */
 281   MESH_PEER_INVALID,
 282
 283     /**
 284      * Peer is the root and owner of the tree
 285      */
 286   MESH_PEER_ROOT,
 287
 288     /**
 289      * Peer only retransmits traffic, is not a final destination
 290      */
 291   MESH_PEER_RELAY,
 292
 293     /**
 294      * Path to the peer not known yet
 295      */
 296   MESH_PEER_SEARCHING,
 297
 298     /**
 299      * Request sent, not yet answered.
 300      */
 301   MESH_PEER_WAITING,
 302
 303     /**
 304      * Peer connected and ready to accept data
 305      */
 306   MESH_PEER_READY,
 307
 308     /**
 309      * Peer connected previosly but not responding
 310      */
 311   MESH_PEER_RECONNECTING
 312 };
 313
 314
 315 /**
 316  * Check if one pid is bigger than other, accounting for overflow.
 317  *
 318  * @param bigger Argument that should be bigger.
 319  * @param smaller Argument that should be smaller.
 320  *
 321  * @return True if bigger (arg1) has a higher value than smaller (arg 2).
 322  */
 323 int
 324 GMC_is_pid_bigger (uint32_t bigger, uint32_t smaller);
 325
 326
 327 /**
 328  * Get the higher ACK value out of two values, taking in account overflow.
 329  *
 330  * @param a First ACK value.
 331  * @param b Second ACK value.
 332  *
 333  * @return Highest ACK value from the two.
 334  */
 335 uint32_t
 336 GMC_max_pid (uint32_t a, uint32_t b);
 337
 338
 339 /**
 340  * Get the lower ACK value out of two values, taking in account overflow.
 341  *
 342  * @param a First ACK value.
 343  * @param b Second ACK value.
 344  *
 345  * @return Lowest ACK value from the two.
 346  */
 347 uint32_t
 348 GMC_min_pid (uint32_t a, uint32_t b);
 349
 350
 351 /**
 352  * Convert a message type into a string to help debug
 353  * Generated with:
 354  * FIND:        "#define ([^ ]+)[ ]*([0-9]+)"
 355  * REPLACE:     "    case \2: return "\1"; break;"
 356  *
 357  * @param m Message type.
 358  *
 359  * @return Human readable string description.
 360  */
 361 const char *
 362 GNUNET_MESH_DEBUG_M2S (uint16_t m);
 363
 364 #endif