src/transport/transport.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-2014 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., 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 type for sending a request connect message
 169  * to the transport service.  Must be done before transport
 170  * api will allow messages to be queued/sent to transport
 171  * service for transmission to a peer.
 172  */
 173 struct TransportRequestConnectMessage
 174 {
 175   /**
 176    *  Message header with type #GNUNET_MESSAGE_TYPE_TRANSPORT_REQUEST_CONNECT
 177    */
 178   struct GNUNET_MessageHeader header;
 179
 180   /**
 181    * Reserved (0).
 182    */
 183   uint32_t reserved GNUNET_PACKED;
 184
 185   /**
 186    * Identity of the peer we would like to connect to.
 187    */
 188   struct GNUNET_PeerIdentity peer;
 189 };
 190
 191
 192 /**
 193  * Message used to set a particular bandwidth quota.  Sent TO the
 194  * service to set an incoming quota, sent FROM the service to update
 195  * an outgoing quota.
 196  */
 197 struct QuotaSetMessage
 198 {
 199
 200   /**
 201    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_SET_QUOTA
 202    */
 203   struct GNUNET_MessageHeader header;
 204
 205   /**
 206    * Quota.
 207    */
 208   struct GNUNET_BANDWIDTH_Value32NBO quota;
 209
 210   /**
 211    * About which peer are we talking here?
 212    */
 213   struct GNUNET_PeerIdentity peer;
 214
 215 };
 216
 217
 218 /**
 219  * Message used to notify the transport API about a message
 220  * received from the network.  The actual message follows.
 221  */
 222 struct InboundMessage
 223 {
 224
 225   /**
 226    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_RECV
 227    */
 228   struct GNUNET_MessageHeader header;
 229
 230   /**
 231    * Which peer sent the message?
 232    */
 233   struct GNUNET_PeerIdentity peer;
 234
 235 };
 236
 237
 238 /**
 239  * Message used to notify the transport API that it can
 240  * send another message to the transport service.
 241  */
 242 struct SendOkMessage
 243 {
 244
 245   /**
 246    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_SEND_OK
 247    */
 248   struct GNUNET_MessageHeader header;
 249
 250   /**
 251    * #GNUNET_OK if the transmission succeeded,
 252    * #GNUNET_SYSERR if it failed (i.e. network disconnect);
 253    * in either case, it is now OK for this client to
 254    * send us another message for the given peer.
 255    */
 256   uint32_t success GNUNET_PACKED;
 257
 258   /**
 259    * Size of message sent
 260    */
 261   uint32_t bytes_msg GNUNET_PACKED;
 262
 263   /**
 264    * Size of message sent over wire
 265    * Includes plugin and protocol specific overhead
 266    */
 267   uint32_t bytes_physical GNUNET_PACKED;
 268
 269   /**
 270    * Which peer can send more now?
 271    */
 272   struct GNUNET_PeerIdentity peer;
 273
 274 };
 275
 276 /**
 277  * Message used to notify the transport API about an address to string
 278  * conversion. Message is followed by the string with the humand-readable
 279  * address.  For each lookup, multiple results may be returned.  The
 280  * last message must have a @e res of #GNUNET_OK and an @e addr_len
 281  * of zero.
 282  */
 283 struct AddressToStringResultMessage
 284 {
 285
 286   /**
 287    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_TO_STRING_REPLY
 288    */
 289   struct GNUNET_MessageHeader header;
 290
 291   /**
 292    * #GNUNET_OK if the conversion succeeded,
 293    * #GNUNET_SYSERR if it failed
 294    */
 295   uint32_t res GNUNET_PACKED;
 296
 297   /**
 298    * Length of the following string, zero if @e is #GNUNET_SYSERR
 299    */
 300   uint32_t addr_len GNUNET_PACKED;
 301 };
 302
 303
 304 /**
 305  * Message used to notify the transport service about a message
 306  * to be transmitted to another peer.  The actual message follows.
 307  */
 308 struct OutboundMessage
 309 {
 310
 311   /**
 312    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_SEND
 313    */
 314   struct GNUNET_MessageHeader header;
 315
 316   /**
 317    * Always zero.
 318    */
 319   uint32_t reserved GNUNET_PACKED;
 320
 321   /**
 322    * Allowed delay.
 323    */
 324   struct GNUNET_TIME_RelativeNBO timeout;
 325
 326   /**
 327    * Which peer should receive the message?
 328    */
 329   struct GNUNET_PeerIdentity peer;
 330
 331 };
 332
 333
 334 /**
 335  * Message from the library to the transport service
 336  * asking for converting a transport address to a
 337  * human-readable UTF-8 string.
 338  */
 339 struct AddressLookupMessage
 340 {
 341
 342   /**
 343    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_ADDRESS_TO_STRING
 344    */
 345   struct GNUNET_MessageHeader header;
 346
 347   /**
 348    * Should the conversion use numeric IP addresses (otherwise
 349    * a reverse DNS lookup is OK -- if applicable).
 350    */
 351   int16_t numeric_only GNUNET_PACKED;
 352
 353   /**
 354    * Length of the (binary) address in bytes, in big-endian.
 355    */
 356   uint16_t addrlen GNUNET_PACKED;
 357
 358   /**
 359    * timeout to give up (for DNS resolution timeout mostly)
 360    */
 361   struct GNUNET_TIME_RelativeNBO timeout;
 362
 363   /* followed by @e addrlen bytes of the actual address, then
 364    * followed by the 0-terminated name of the transport */
 365 };
 366
 367
 368 /**
 369  * Message from the transport service to the library containing information
 370  * about a peer. Information contained are:
 371  * - current address used to communicate with this peer
 372  * - state
 373  * - state timeout
 374  *
 375  * Memory layout:
 376  * [AddressIterateResponseMessage][address[addrlen]][transportname[pluginlen]]
 377  */
 378 struct ValidationIterateResponseMessage
 379 {
 380   /**
 381    * Type is #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_VALIDATION_RESPONSE
 382    */
 383   struct GNUNET_MessageHeader header;
 384
 385   /**
 386    * For alignment.
 387    */
 388   uint32_t reserved;
 389
 390   /**
 391    * Peer identity
 392    */
 393   struct GNUNET_PeerIdentity peer;
 394
 395   /**
 396    * Local info about the address
 397    */
 398   uint32_t local_address_info GNUNET_PACKED;
 399
 400   /**
 401    * Address length
 402    */
 403   uint32_t addrlen GNUNET_PACKED;
 404
 405   /**
 406    * Length of the plugin name
 407    */
 408   uint32_t pluginlen GNUNET_PACKED;
 409
 410   /**
 411    * State
 412    */
 413   uint32_t state GNUNET_PACKED;
 414
 415   /**
 416    * At what time did we successfully validate the address last.
 417    * Will be NEVER if the address failed validation.
 418    */
 419   struct GNUNET_TIME_AbsoluteNBO last_validation;
 420
 421   /**
 422    * Until when is the address believed to be valid.
 423    * Will be ZERO if the address is not belived to be valid.
 424    */
 425   struct GNUNET_TIME_AbsoluteNBO valid_until;
 426
 427   /**
 428    * When will we next try to validate the address (typically
 429    * done before @e valid_until happens).
 430    */
 431   struct GNUNET_TIME_AbsoluteNBO next_validation;
 432 };
 433
 434 /**
 435  * Message from the library to the transport service
 436  * asking for binary addresses known for a peer.
 437  */
 438 struct ValidationMonitorMessage
 439 {
 440   /**
 441    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_VALIDATION_REQUEST
 442    */
 443   struct GNUNET_MessageHeader header;
 444
 445   /**
 446    * One shot call or continous replies?
 447    */
 448   uint32_t one_shot GNUNET_PACKED;
 449
 450   /**
 451    * The identity of the peer to look up.
 452    */
 453   struct GNUNET_PeerIdentity peer;
 454
 455 };
 456
 457
 458 /**
 459  * Message from the library to the transport service
 460  * asking for binary addresses known for a peer.
 461  */
 462 struct PeerMonitorMessage
 463 {
 464   /**
 465    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_PEER_REQUEST
 466    */
 467   struct GNUNET_MessageHeader header;
 468
 469   /**
 470    * One shot call or continous replies?
 471    */
 472   uint32_t one_shot GNUNET_PACKED;
 473
 474   /**
 475    * The identity of the peer to look up.
 476    */
 477   struct GNUNET_PeerIdentity peer;
 478
 479 };
 480
 481
 482 /**
 483  * Message from the library to the transport service
 484  * asking for binary addresses known for a peer.
 485  */
 486 struct TrafficMetricMessage
 487 {
 488   /**
 489    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_TRAFFIC_METRIC
 490    */
 491   struct GNUNET_MessageHeader header;
 492
 493   /**
 494    * Always zero.
 495    */
 496   uint32_t reserved GNUNET_PACKED;
 497
 498   /**
 499    * The identity of the peer to look up.
 500    */
 501   struct GNUNET_PeerIdentity peer;
 502
 503   /**
 504    * Fake properties to generate.
 505    */
 506   struct GNUNET_ATS_PropertiesNBO properties;
 507
 508   /**
 509    * Fake delay to add on inbound traffic.
 510    */
 511   struct GNUNET_TIME_RelativeNBO delay_in;
 512
 513   /**
 514    * Fake delay to add on outbound traffic.
 515    */
 516   struct GNUNET_TIME_RelativeNBO delay_out;
 517 };
 518
 519
 520 /**
 521  * Message from the transport service to the library containing information
 522  * about a peer. Information contained are:
 523  * - current address used to communicate with this peer
 524  * - state
 525  * - state timeout
 526  *
 527  * Memory layout:
 528  * [AddressIterateResponseMessage][address[addrlen]][transportname[pluginlen]]
 529  */
 530 struct PeerIterateResponseMessage
 531 {
 532   /**
 533    * Type is #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_PEER_RESPONSE
 534    */
 535   struct GNUNET_MessageHeader header;
 536
 537   /**
 538    * For alignment.
 539    */
 540   uint32_t reserved;
 541
 542   /**
 543    * Peer identity
 544    */
 545   struct GNUNET_PeerIdentity peer;
 546
 547   /**
 548    * Timeout for the state this peer is in
 549    */
 550   struct GNUNET_TIME_AbsoluteNBO state_timeout;
 551
 552   /**
 553    * Local info about the address
 554    */
 555   uint32_t local_address_info GNUNET_PACKED;
 556
 557   /**
 558    * State this peer is in as an `enum GNUNET_TRANSPORT_PeerState`
 559    */
 560   uint32_t state GNUNET_PACKED;
 561
 562   /**
 563    * Address length
 564    */
 565   uint32_t addrlen GNUNET_PACKED;
 566
 567   /**
 568    * Length of the plugin name
 569    */
 570   uint32_t pluginlen GNUNET_PACKED;
 571
 572 };
 573
 574
 575 /**
 576  * Change in blacklisting (either request or notification,
 577  * depending on which direction it is going).
 578  */
 579 struct BlacklistMessage
 580 {
 581
 582   /**
 583    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_BLACKLIST_QUERY or
 584    * #GNUNET_MESSAGE_TYPE_TRANSPORT_BLACKLIST_REPLY.
 585    */
 586   struct GNUNET_MessageHeader header;
 587
 588   /**
 589    * 0 for the query, #GNUNET_OK (allowed) or #GNUNET_SYSERR (disallowed)
 590    * for the response.
 591    */
 592   uint32_t is_allowed GNUNET_PACKED;
 593
 594   /**
 595    * Which peer is being blacklisted or queried?
 596    */
 597   struct GNUNET_PeerIdentity peer;
 598
 599 };
 600
 601
 602 /**
 603  * Transport-level connection status update.
 604  */
 605 struct TransportPluginMonitorMessage
 606 {
 607
 608   /**
 609    * Type will be #GNUNET_MESSAGE_TYPE_TRANSPORT_MONITOR_PLUGIN_EVENT.
 610    */
 611   struct GNUNET_MessageHeader header;
 612
 613   /**
 614    * An `enum GNUNET_TRANSPORT_SessionState` in NBO.
 615    */
 616   uint16_t session_state GNUNET_PACKED;
 617
 618   /**
 619    * #GNUNET_YES if this is an inbound connection,
 620    * #GNUNET_NO if this is an outbound connection,
 621    * #GNUNET_SYSERR if connections of this plugin
 622    *             are so fundamentally bidirectional
 623    *             that they have no 'initiator'
 624    * Value given in NBO.
 625    */
 626   int16_t is_inbound GNUNET_PACKED;
 627
 628   /**
 629    * Number of messages waiting transmission.
 630    */
 631   uint32_t msgs_pending GNUNET_PACKED;
 632
 633   /**
 634    * Number of bytes waiting for transmission.
 635    */
 636   uint32_t bytes_pending GNUNET_PACKED;
 637
 638   /**
 639    * When will this transport plugin session time out?
 640    */
 641   struct GNUNET_TIME_AbsoluteNBO timeout;
 642
 643   /**
 644    * Until how long is this plugin currently blocked from reading?
 645    */
 646   struct GNUNET_TIME_AbsoluteNBO delay;
 647
 648   /**
 649    * Which peer is this connection for?
 650    */
 651   struct GNUNET_PeerIdentity peer;
 652
 653   /**
 654    * Unique identifier for the session.
 655    */
 656   uint64_t session_id;
 657
 658   /**
 659    * Length of the plugin name in bytes, including 0-termination.
 660    */
 661   uint16_t plugin_name_len GNUNET_PACKED;
 662
 663   /**
 664    * Length of the plugin address in bytes.
 665    */
 666   uint16_t plugin_address_len GNUNET_PACKED;
 667
 668   /* followed by 0-terminated plugin name and
 669      @e plugin_address_len bytes of plugin address */
 670
 671 };
 672
 673
 674 GNUNET_NETWORK_STRUCT_END
 675
 676 /* end of transport.h */
 677 #endif