src/transport/transport.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-2014 GNUnet e.V.
   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., 51 Franklin Street, Fifth Floor,
  18      Boston, MA 02110-1301, USA.
  19 */
  20
  21 /**
  22  * @file transport/transport.h
  23  * @brief common internal definitions for transport service
  24  * @author Christian Grothoff
  25  */
  26 #ifndef TRANSPORT_H
  27 #define TRANSPORT_H
  28
  29 #include "gnunet_crypto_lib.h"
  30 #include "gnunet_time_lib.h"
  31 #include "gnunet_transport_service.h"
  32 #include "gnunet_constants.h"
  33
  34 #define DEBUG_TRANSPORT GNUNET_EXTRA_LOGGING
  35
  36
  37 /**
  38  * For how long do we allow unused bandwidth
  39  * from the past to carry over into the future? (in seconds)
  40  */
  41 #define MAX_BANDWIDTH_CARRY_S GNUNET_CONSTANTS_MAX_BANDWIDTH_CARRY_S
  42
  43 /**
  44  * How often do we (at most) do a full quota
  45  * recalculation? (in ms)
  46  */
  47 #define MIN_QUOTA_REFRESH_TIME 2000
  48
  49 /**
  50  * What's the maximum number of sockets transport uses for validation and
  51  * neighbors
  52  */
  53 #define DEFAULT_MAX_FDS 256
  54
  55 /**
  56  * Maximum frequency for re-evaluating latencies for all transport addresses.
  57  */
  58 #define LATENCY_EVALUATION_MAX_DELAY GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_HOURS, 1)
  59
  60 /**
  61  * Maximum frequency for re-evaluating latencies for connected addresses.
  62  */
  63 #define CONNECTED_LATENCY_EVALUATION_MAX_DELAY GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_MINUTES, 1)
  64
  65 /**
  66  * Similiar to GNUNET_TRANSPORT_NotifyDisconnect but in and out quotas are
  67  * included here. These values are not required outside transport_api
  68  *
  69  * @param cls closure
  70  * @param peer the peer that connected
  71  * @param bandwidth_in inbound bandwidth in NBO
  72  * @param bandwidth_out outbound bandwidth in NBO
  73  *
  74  */
  75 typedef void
  76 (*NotifyConnect) (void *cls,
  77                   const struct GNUNET_PeerIdentity *peer,
  78                   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in,
  79                   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out);
  80
  81
  82 GNUNET_NETWORK_STRUCT_BEGIN
  83
  84 /**
  85  * Message from the transport service to the library
  86  * asking to check if both processes agree about this
  87  * peers identity.
  88  */
  89 struct StartMessage
  90 {
  91
  92   /**
  93    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_START
  94    */
  95   struct GNUNET_MessageHeader header;
  96
  97   /**
  98    * 0: no options
  99    * 1: The 'self' field should be checked
 100    * 2: this client is interested in payload traffic
 101    */
 102   uint32_t options;
 103
 104   /**
 105    * Identity we think we have.  If it does not match, the
 106    * receiver should print out an error message and disconnect.
 107    */
 108   struct GNUNET_PeerIdentity self;
 109
 110 };
 111
 112
 113 /**
 114  * Message from the transport service to the library
 115  * informing about neighbors.
 116  */
 117 struct ConnectInfoMessage
 118 {
 119
 120   /**
 121    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_CONNECT
 122    */
 123   struct GNUNET_MessageHeader header;
 124
 125   /**
 126    * Identity of the new neighbour.
 127    */
 128   struct GNUNET_PeerIdentity id;
 129
 130   /**
 131    * Current inbound quota for this peer
 132    */
 133   struct GNUNET_BANDWIDTH_Value32NBO quota_in;
 134
 135   /**
 136    * Current outbound quota for this peer
 137    */
 138   struct GNUNET_BANDWIDTH_Value32NBO quota_out;
 139 };
 140
 141
 142 /**
 143  * Message from the transport service to the library
 144  * informing about disconnects.
 145  */
 146 struct DisconnectInfoMessage
 147 {
 148
 149   /**
 150    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_DISCONNECT
 151    */
 152   struct GNUNET_MessageHeader header;
 153
 154   /**
 155    * Reserved, always zero.
 156    */
 157   uint32_t reserved GNUNET_PACKED;
 158
 159   /**
 160    * Who got disconnected?
 161    */
 162   struct GNUNET_PeerIdentity peer;
 163
 164 };
 165
 166
 167 /**
 168  * Message used to set a particular bandwidth quota.  Sent TO the
 169  * service to set an incoming quota, sent FROM the service to update
 170  * an outgoing quota.
 171  */
 172 struct QuotaSetMessage
 173 {
 174
 175   /**
 176    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_SET_QUOTA
 177    */
 178   struct GNUNET_MessageHeader header;
 179
 180   /**
 181    * Quota.
 182    */
 183   struct GNUNET_BANDWIDTH_Value32NBO quota;
 184
 185   /**
 186    * About which peer are we talking here?
 187    */
 188   struct GNUNET_PeerIdentity peer;
 189
 190 };
 191
 192
 193 /**
 194  * Message used to notify the transport API about a message
 195  * received from the network.  The actual message follows.
 196  */
 197 struct InboundMessage
 198 {
 199
 200   /**
 201    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_RECV
 202    */
 203   struct GNUNET_MessageHeader header;
 204
 205   /**
 206    * Which peer sent the message?
 207    */
 208   struct GNUNET_PeerIdentity peer;
 209
 210 };
 211
 212
 213 /**
 214  * Message used to notify the transport API that it can
 215  * send another message to the transport service.
 216  */
 217 struct SendOkMessage
 218 {
 219
 220   /**
 221    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_SEND_OK
 222    */
 223   struct GNUNET_MessageHeader header;
 224
 225   /**
 226    * #GNUNET_OK if the transmission succeeded,
 227    * #GNUNET_SYSERR if it failed (i.e. network disconnect);
 228    * in either case, it is now OK for this client to
 229    * send us another message for the given peer.
 230    */
 231   uint32_t success GNUNET_PACKED;
 232
 233   /**
 234    * Size of message sent
 235    */
 236   uint32_t bytes_msg GNUNET_PACKED;
 237
 238   /**
 239    * Size of message sent over wire
 240    * Includes plugin and protocol specific overhead
 241    */
 242   uint32_t bytes_physical GNUNET_PACKED;
 243
 244   /**
 245    * Which peer can send more now?
 246    */
 247   struct GNUNET_PeerIdentity peer;
 248
 249 };
 250
 251 /**
 252  * Message used to notify the transport API about an address to string
 253  * conversion. Message is followed by the string with the humand-readable
 254  * address.  For each lookup, multiple results may be returned.  The
 255  * last message must have a @e res of #GNUNET_OK and an @e addr_len
 256  * of zero.
 257  */
 258 struct AddressToStringResultMessage
 259 {
 260
 261   /**
 262    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_TO_STRING_REPLY
 263    */
 264   struct GNUNET_MessageHeader header;
 265
 266   /**
 267    * #GNUNET_OK if the conversion succeeded,
 268    * #GNUNET_SYSERR if it failed
 269    */
 270   uint32_t res GNUNET_PACKED;
 271
 272   /**
 273    * Length of the following string, zero if @e is #GNUNET_SYSERR
 274    */
 275   uint32_t addr_len GNUNET_PACKED;
 276 };
 277
 278
 279 /**
 280  * Message used to notify the transport service about a message
 281  * to be transmitted to another peer.  The actual message follows.
 282  */
 283 struct OutboundMessage
 284 {
 285
 286   /**
 287    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_SEND
 288    */
 289   struct GNUNET_MessageHeader header;
 290
 291   /**
 292    * Always zero.
 293    */
 294   uint32_t reserved GNUNET_PACKED;
 295
 296   /**
 297    * Allowed delay.
 298    */
 299   struct GNUNET_TIME_RelativeNBO timeout;
 300
 301   /**
 302    * Which peer should receive the message?
 303    */
 304   struct GNUNET_PeerIdentity peer;
 305
 306 };
 307
 308
 309 /**
 310  * Message from the library to the transport service
 311  * asking for converting a transport address to a
 312  * human-readable UTF-8 string.
 313  */
 314 struct AddressLookupMessage
 315 {
 316
 317   /**
 318    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_TO_STRING
 319    */
 320   struct GNUNET_MessageHeader header;
 321
 322   /**
 323    * Should the conversion use numeric IP addresses (otherwise
 324    * a reverse DNS lookup is OK -- if applicable).
 325    */
 326   int16_t numeric_only GNUNET_PACKED;
 327
 328   /**
 329    * Length of the (binary) address in bytes, in big-endian.
 330    */
 331   uint16_t addrlen GNUNET_PACKED;
 332
 333   /**
 334    * timeout to give up (for DNS resolution timeout mostly)
 335    */
 336   struct GNUNET_TIME_RelativeNBO timeout;
 337
 338   /* followed by @e addrlen bytes of the actual address, then
 339    * followed by the 0-terminated name of the transport */
 340 };
 341
 342
 343 /**
 344  * Message from the transport service to the library containing information
 345  * about a peer. Information contained are:
 346  * - current address used to communicate with this peer
 347  * - state
 348  * - state timeout
 349  *
 350  * Memory layout:
 351  * [AddressIterateResponseMessage][address[addrlen]][transportname[pluginlen]]
 352  */
 353 struct ValidationIterateResponseMessage
 354 {
 355   /**
 356    * Type is #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_VALIDATION_RESPONSE
 357    */
 358   struct GNUNET_MessageHeader header;
 359
 360   /**
 361    * For alignment.
 362    */
 363   uint32_t reserved;
 364
 365   /**
 366    * Peer identity
 367    */
 368   struct GNUNET_PeerIdentity peer;
 369
 370   /**
 371    * Local info about the address
 372    */
 373   uint32_t local_address_info GNUNET_PACKED;
 374
 375   /**
 376    * Address length
 377    */
 378   uint32_t addrlen GNUNET_PACKED;
 379
 380   /**
 381    * Length of the plugin name
 382    */
 383   uint32_t pluginlen GNUNET_PACKED;
 384
 385   /**
 386    * State
 387    */
 388   uint32_t state GNUNET_PACKED;
 389
 390   /**
 391    * At what time did we successfully validate the address last.
 392    * Will be NEVER if the address failed validation.
 393    */
 394   struct GNUNET_TIME_AbsoluteNBO last_validation;
 395
 396   /**
 397    * Until when is the address believed to be valid.
 398    * Will be ZERO if the address is not belived to be valid.
 399    */
 400   struct GNUNET_TIME_AbsoluteNBO valid_until;
 401
 402   /**
 403    * When will we next try to validate the address (typically
 404    * done before @e valid_until happens).
 405    */
 406   struct GNUNET_TIME_AbsoluteNBO next_validation;
 407 };
 408
 409 /**
 410  * Message from the library to the transport service
 411  * asking for binary addresses known for a peer.
 412  */
 413 struct ValidationMonitorMessage
 414 {
 415   /**
 416    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_VALIDATION_REQUEST
 417    */
 418   struct GNUNET_MessageHeader header;
 419
 420   /**
 421    * One shot call or continous replies?
 422    */
 423   uint32_t one_shot GNUNET_PACKED;
 424
 425   /**
 426    * The identity of the peer to look up.
 427    */
 428   struct GNUNET_PeerIdentity peer;
 429
 430 };
 431
 432
 433 /**
 434  * Message from the library to the transport service
 435  * asking for binary addresses known for a peer.
 436  */
 437 struct PeerMonitorMessage
 438 {
 439   /**
 440    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_PEER_REQUEST
 441    */
 442   struct GNUNET_MessageHeader header;
 443
 444   /**
 445    * One shot call or continous replies?
 446    */
 447   uint32_t one_shot GNUNET_PACKED;
 448
 449   /**
 450    * The identity of the peer to look up.
 451    */
 452   struct GNUNET_PeerIdentity peer;
 453
 454 };
 455
 456
 457 /**
 458  * Message from the library to the transport service
 459  * asking for binary addresses known for a peer.
 460  */
 461 struct TrafficMetricMessage
 462 {
 463   /**
 464    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_TRAFFIC_METRIC
 465    */
 466   struct GNUNET_MessageHeader header;
 467
 468   /**
 469    * Always zero.
 470    */
 471   uint32_t reserved GNUNET_PACKED;
 472
 473   /**
 474    * The identity of the peer to look up.
 475    */
 476   struct GNUNET_PeerIdentity peer;
 477
 478   /**
 479    * Fake properties to generate.
 480    */
 481   struct GNUNET_ATS_PropertiesNBO properties;
 482
 483   /**
 484    * Fake delay to add on inbound traffic.
 485    */
 486   struct GNUNET_TIME_RelativeNBO delay_in;
 487
 488   /**
 489    * Fake delay to add on outbound traffic.
 490    */
 491   struct GNUNET_TIME_RelativeNBO delay_out;
 492 };
 493
 494
 495 /**
 496  * Message from the transport service to the library containing information
 497  * about a peer. Information contained are:
 498  * - current address used to communicate with this peer
 499  * - state
 500  * - state timeout
 501  *
 502  * Memory layout:
 503  * [AddressIterateResponseMessage][address[addrlen]][transportname[pluginlen]]
 504  */
 505 struct PeerIterateResponseMessage
 506 {
 507   /**
 508    * Type is #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_PEER_RESPONSE
 509    */
 510   struct GNUNET_MessageHeader header;
 511
 512   /**
 513    * For alignment.
 514    */
 515   uint32_t reserved;
 516
 517   /**
 518    * Peer identity
 519    */
 520   struct GNUNET_PeerIdentity peer;
 521
 522   /**
 523    * Timeout for the state this peer is in
 524    */
 525   struct GNUNET_TIME_AbsoluteNBO state_timeout;
 526
 527   /**
 528    * Local info about the address
 529    */
 530   uint32_t local_address_info GNUNET_PACKED;
 531
 532   /**
 533    * State this peer is in as an `enum GNUNET_TRANSPORT_PeerState`
 534    */
 535   uint32_t state GNUNET_PACKED;
 536
 537   /**
 538    * Address length
 539    */
 540   uint32_t addrlen GNUNET_PACKED;
 541
 542   /**
 543    * Length of the plugin name
 544    */
 545   uint32_t pluginlen GNUNET_PACKED;
 546
 547 };
 548
 549
 550 /**
 551  * Change in blacklisting (either request or notification,
 552  * depending on which direction it is going).
 553  */
 554 struct BlacklistMessage
 555 {
 556
 557   /**
 558    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_BLACKLIST_QUERY or
 559    * #GNUNET_MESSAGE_TYPE_TRANSPORT_BLACKLIST_REPLY.
 560    */
 561   struct GNUNET_MessageHeader header;
 562
 563   /**
 564    * 0 for the query, #GNUNET_OK (allowed) or #GNUNET_SYSERR (disallowed)
 565    * for the response.
 566    */
 567   uint32_t is_allowed GNUNET_PACKED;
 568
 569   /**
 570    * Which peer is being blacklisted or queried?
 571    */
 572   struct GNUNET_PeerIdentity peer;
 573
 574 };
 575
 576
 577 /**
 578  * Transport-level connection status update.
 579  */
 580 struct TransportPluginMonitorMessage
 581 {
 582
 583   /**
 584    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_PLUGIN_EVENT.
 585    */
 586   struct GNUNET_MessageHeader header;
 587
 588   /**
 589    * An `enum GNUNET_TRANSPORT_SessionState` in NBO.
 590    */
 591   uint16_t session_state GNUNET_PACKED;
 592
 593   /**
 594    * #GNUNET_YES if this is an inbound connection,
 595    * #GNUNET_NO if this is an outbound connection,
 596    * #GNUNET_SYSERR if connections of this plugin
 597    *             are so fundamentally bidirectional
 598    *             that they have no 'initiator'
 599    * Value given in NBO.
 600    */
 601   int16_t is_inbound GNUNET_PACKED;
 602
 603   /**
 604    * Number of messages waiting transmission.
 605    */
 606   uint32_t msgs_pending GNUNET_PACKED;
 607
 608   /**
 609    * Number of bytes waiting for transmission.
 610    */
 611   uint32_t bytes_pending GNUNET_PACKED;
 612
 613   /**
 614    * When will this transport plugin session time out?
 615    */
 616   struct GNUNET_TIME_AbsoluteNBO timeout;
 617
 618   /**
 619    * Until how long is this plugin currently blocked from reading?
 620    */
 621   struct GNUNET_TIME_AbsoluteNBO delay;
 622
 623   /**
 624    * Which peer is this connection for?
 625    */
 626   struct GNUNET_PeerIdentity peer;
 627
 628   /**
 629    * Unique identifier for the session.
 630    */
 631   uint64_t session_id;
 632
 633   /**
 634    * Length of the plugin name in bytes, including 0-termination.
 635    */
 636   uint16_t plugin_name_len GNUNET_PACKED;
 637
 638   /**
 639    * Length of the plugin address in bytes.
 640    */
 641   uint16_t plugin_address_len GNUNET_PACKED;
 642
 643   /* followed by 0-terminated plugin name and
 644      @e plugin_address_len bytes of plugin address */
 645
 646 };
 647
 648
 649 GNUNET_NETWORK_STRUCT_END
 650
 651 /* end of transport.h */
 652 #endif