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