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