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