src/ats/ats2.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2010-2015 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      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17
  18      SPDX-License-Identifier: AGPL3.0-or-later
  19  */
  20 /**
  21  * @file ats/ats2.h
  22  * @brief automatic transport selection messages
  23  * @author Christian Grothoff
  24  * @author Matthias Wachs
  25  */
  26 #ifndef ATS2_H
  27 #define ATS2_H
  28
  29 #include "gnunet_util_lib.h"
  30 #include "gnunet_ats_transport_service.h"
  31
  32
  33 GNUNET_NETWORK_STRUCT_BEGIN
  34
  35
  36 /**
  37  * ATS performance characteristics for an address.
  38  */
  39 struct PropertiesNBO {
  40   /**
  41    * Delay.  Time between when the time packet is sent and the packet
  42    * arrives.  FOREVER if we did not (successfully) measure yet.
  43    */
  44   struct GNUNET_TIME_RelativeNBO delay;
  45
  46   /**
  47    * Confirmed successful payload on this connection from this peer to
  48    * the other peer. In NBO.
  49    *
  50    * Unit: [bytes/second]
  51    */
  52   uint32_t goodput_out;
  53
  54   /**
  55    * Confirmed useful payload on this connection to this peer from
  56    * the other peer. In NBO.
  57    *
  58    * Unit: [bytes/second]
  59    */
  60   uint32_t goodput_in;
  61
  62   /**
  63    * Actual traffic on this connection from this peer to the other peer.
  64    * Includes transport overhead. In NBO.
  65    *
  66    * Unit: [bytes/second]
  67    */
  68   uint32_t utilization_out;
  69
  70   /**
  71    * Actual traffic on this connection from the other peer to this peer.
  72    * Includes transport overhead. In NBO.
  73    *
  74    * Unit: [bytes/second]
  75    */
  76   uint32_t utilization_in;
  77
  78   /**
  79    * Distance on network layer (required for distance-vector routing)
  80    * in hops.  Zero for direct connections (i.e. plain TCP/UDP). In NBO.
  81    */
  82   uint32_t distance;
  83
  84   /**
  85    * MTU of the network layer, UINT32_MAX for no MTU (stream).
  86    *
  87    * Unit: [bytes]. In NBO.
  88    */
  89   uint32_t mtu;
  90
  91   /**
  92    * Which network scope does the respective address belong to?
  93    * A `enum GNUNET_NetworkType nt` in NBO.
  94    */
  95   uint32_t nt;
  96
  97   /**
  98    * What characteristics does this communicator have?
  99    * A `enum GNUNET_TRANSPORT_CommunicatorCharacteristics` in NBO.
 100    */
 101   uint32_t cc;
 102 };
 103
 104
 105 /**
 106  * Application client to ATS service: we would like to have
 107  * address suggestions for this peer.
 108  */
 109 struct ExpressPreferenceMessage {
 110   /**
 111    * Type is #GNUNET_MESSAGE_TYPE_ATS_SUGGEST or
 112    * #GNUNET_MESSAGE_TYPE_ATS_SUGGEST_CANCEL to stop
 113    * suggestions.
 114    */
 115   struct GNUNET_MessageHeader header;
 116
 117   /**
 118    * What type of performance preference does the client have?
 119    * A `enum GNUNET_MQ_PreferenceKind` in NBO.
 120    */
 121   uint32_t pk GNUNET_PACKED;
 122
 123   /**
 124    * Peer to get address suggestions for.
 125    */
 126   struct GNUNET_PeerIdentity peer;
 127
 128   /**
 129    * How much bandwidth in bytes/second does the application expect?
 130    */
 131   struct GNUNET_BANDWIDTH_Value32NBO bw;
 132 };
 133
 134
 135 /**
 136  * Transport client to ATS service: here is another session you can use.
 137  */
 138 struct SessionAddMessage {
 139   /**
 140    * Type is #GNUNET_MESSAGE_TYPE_ATS_SESSION_ADD or
 141    * #GNUNET_MESSAGE_TYPE_ATS_SESSION_ADD_INBOUND_ONLY
 142    */
 143   struct GNUNET_MessageHeader header;
 144
 145   /**
 146    * Internal number this client will henceforth use to
 147    * refer to this session.
 148    */
 149   uint32_t session_id GNUNET_PACKED;
 150
 151   /**
 152    * Identity of the peer that this session is for.
 153    */
 154   struct GNUNET_PeerIdentity peer;
 155
 156   /**
 157    * Performance properties of the session.
 158    */
 159   struct PropertiesNBO properties;
 160
 161   /* followed by:
 162    * - char * address (including '\0'-termination).
 163    */
 164 };
 165
 166
 167 /**
 168  * Message used to notify ATS that the performance
 169  * characteristics for an session have changed.
 170  */
 171 struct SessionUpdateMessage {
 172   /**
 173    * Message of type #GNUNET_MESSAGE_TYPE_ATS_SESSION_UPDATE.
 174    */
 175   struct GNUNET_MessageHeader header;
 176
 177   /**
 178    * Internal number this client uses to refer to this session.
 179    */
 180   uint32_t session_id GNUNET_PACKED;
 181
 182   /**
 183    * Which peer is this about? (Technically redundant, as the
 184    * @e session_id should be sufficient, but enables ATS service
 185    * to find the session faster).
 186    */
 187   struct GNUNET_PeerIdentity peer;
 188
 189   /**
 190    * Performance properties of the session.
 191    */
 192   struct PropertiesNBO properties;
 193 };
 194
 195
 196 /**
 197  * Message sent by ATS client to ATS service when an session
 198  * was destroyed and must thus henceforth no longer be considered
 199  * for scheduling.
 200  */
 201 struct SessionDelMessage {
 202   /**
 203    * Type is #GNUNET_MESSAGE_TYPE_ATS_SESSION_DEL.
 204    */
 205   struct GNUNET_MessageHeader header;
 206
 207   /**
 208    * Internal number this client uses to refer to this session.
 209    */
 210   uint32_t session_id GNUNET_PACKED;
 211
 212   /**
 213    * Which peer is this about? (Technically redundant, as the
 214    * @e session_id should be sufficient, but enables ATS service
 215    * to find the session faster).
 216    */
 217   struct GNUNET_PeerIdentity peer;
 218 };
 219
 220
 221 /**
 222  * ATS Service allocates resources to an session
 223  * identified by the given @e session_id for the given @e peer with
 224  * the given @e bandwidth_in and @e bandwidth_out limits from now on.
 225  */
 226 struct SessionAllocationMessage {
 227   /**
 228    * A message of type #GNUNET_MESSAGE_TYPE_ATS_SESSION_ALLOCATION.
 229    */
 230   struct GNUNET_MessageHeader header;
 231
 232   /**
 233    * Internal number this client uses to refer to the session this
 234    * suggestion is about.
 235    */
 236   uint32_t session_id GNUNET_PACKED;
 237
 238   /**
 239    * Which peer is this about? (Technically redundant, as the
 240    * @e session_id should be sufficient, but may enable client
 241    * to find the session faster and/or check consistency).
 242    */
 243   struct GNUNET_PeerIdentity peer;
 244
 245   /**
 246    * How much bandwidth we are allowed for sending.
 247    */
 248   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out;
 249
 250   /**
 251    * How much bandwidth we are allowed for receiving.
 252    */
 253   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in;
 254 };
 255
 256
 257 /**
 258  * ATS Service suggests to the transport service to try the address
 259  * for the given @e peer.
 260  */
 261 struct AddressSuggestionMessage {
 262   /**
 263    * A message of type #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_SUGGESTION.
 264    */
 265   struct GNUNET_MessageHeader header;
 266
 267   /**
 268    * Zero.
 269    */
 270   uint32_t reserved GNUNET_PACKED;
 271
 272   /**
 273    * Which peer is this about? (Technically redundant, as the
 274    * @e session_id should be sufficient, but may enable client
 275    * to find the session faster and/or check consistency).
 276    */
 277   struct GNUNET_PeerIdentity peer;
 278
 279   /* Followed by 0-terminated address */
 280 };
 281
 282
 283 GNUNET_NETWORK_STRUCT_END
 284
 285
 286
 287 #endif