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 /**
  19  * @file ats/ats2.h
  20  * @brief automatic transport selection messages
  21  * @author Christian Grothoff
  22  * @author Matthias Wachs
  23  */
  24 #ifndef ATS2_H
  25 #define ATS2_H
  26
  27 #include "gnunet_util_lib.h"
  28 #include "gnunet_ats_transport_service.h"
  29
  30
  31 GNUNET_NETWORK_STRUCT_BEGIN
  32
  33
  34 /**
  35  * ATS performance characteristics for an address.
  36  */
  37 struct PropertiesNBO
  38 {
  39
  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 /**
 107  * Application client to ATS service: we would like to have
 108  * address suggestions for this peer.
 109  */
 110 struct ExpressPreferenceMessage
 111 {
 112   /**
 113    * Type is #GNUNET_MESSAGE_TYPE_ATS_SUGGEST or
 114    * #GNUNET_MESSAGE_TYPE_ATS_SUGGEST_CANCEL to stop
 115    * suggestions.
 116    */
 117   struct GNUNET_MessageHeader header;
 118
 119   /**
 120    * What type of performance preference does the client have?
 121    * A `enum GNUNET_MQ_PreferenceKind` in NBO.
 122    */
 123   uint32_t pk GNUNET_PACKED;
 124
 125   /**
 126    * Peer to get address suggestions for.
 127    */
 128   struct GNUNET_PeerIdentity peer;
 129
 130   /**
 131    * How much bandwidth in bytes/second does the application expect?
 132    */
 133   struct GNUNET_BANDWIDTH_Value32NBO bw;
 134
 135 };
 136
 137
 138 /**
 139  * Transport client to ATS service: here is another session you can use.
 140  */
 141 struct SessionAddMessage
 142 {
 143   /**
 144    * Type is #GNUNET_MESSAGE_TYPE_ATS_SESSION_ADD or
 145    * #GNUNET_MESSAGE_TYPE_ATS_SESSION_ADD_INBOUND_ONLY
 146    */
 147   struct GNUNET_MessageHeader header;
 148
 149   /**
 150    * Internal number this client will henceforth use to
 151    * refer to this session.
 152    */
 153   uint32_t session_id GNUNET_PACKED;
 154
 155   /**
 156    * Identity of the peer that this session is for.
 157    */
 158   struct GNUNET_PeerIdentity peer;
 159
 160   /**
 161    * Performance properties of the session.
 162    */
 163   struct PropertiesNBO properties;
 164
 165   /* followed by:
 166    * - char * address (including '\0'-termination).
 167    */
 168
 169 };
 170
 171
 172 /**
 173  * Message used to notify ATS that the performance
 174  * characteristics for an session have changed.
 175  */
 176 struct SessionUpdateMessage
 177 {
 178   /**
 179    * Message of type #GNUNET_MESSAGE_TYPE_ATS_SESSION_UPDATE.
 180    */
 181   struct GNUNET_MessageHeader header;
 182
 183   /**
 184    * Internal number this client uses to refer to this session.
 185    */
 186   uint32_t session_id GNUNET_PACKED;
 187
 188   /**
 189    * Which peer is this about? (Technically redundant, as the
 190    * @e session_id should be sufficient, but enables ATS service
 191    * to find the session faster).
 192    */
 193   struct GNUNET_PeerIdentity peer;
 194
 195   /**
 196    * Performance properties of the session.
 197    */
 198   struct PropertiesNBO properties;
 199
 200 };
 201
 202
 203 /**
 204  * Message sent by ATS client to ATS service when an session
 205  * was destroyed and must thus henceforth no longer be considered
 206  * for scheduling.
 207  */
 208 struct SessionDelMessage
 209 {
 210   /**
 211    * Type is #GNUNET_MESSAGE_TYPE_ATS_SESSION_DEL.
 212    */
 213   struct GNUNET_MessageHeader header;
 214
 215   /**
 216    * Internal number this client uses to refer to this session.
 217    */
 218   uint32_t session_id GNUNET_PACKED;
 219
 220   /**
 221    * Which peer is this about? (Technically redundant, as the
 222    * @e session_id should be sufficient, but enables ATS service
 223    * to find the session faster).
 224    */
 225   struct GNUNET_PeerIdentity peer;
 226
 227 };
 228
 229
 230 /**
 231  * ATS Service allocates resources to an session
 232  * identified by the given @e session_id for the given @e peer with
 233  * the given @e bandwidth_in and @e bandwidth_out limits from now on.
 234  */
 235 struct SessionAllocationMessage
 236 {
 237   /**
 238    * A message of type #GNUNET_MESSAGE_TYPE_ATS_SESSION_ALLOCATION.
 239    */
 240   struct GNUNET_MessageHeader header;
 241
 242   /**
 243    * Internal number this client uses to refer to the session this
 244    * suggestion is about.
 245    */
 246   uint32_t session_id GNUNET_PACKED;
 247
 248   /**
 249    * Which peer is this about? (Technically redundant, as the
 250    * @e session_id should be sufficient, but may enable client
 251    * to find the session faster and/or check consistency).
 252    */
 253   struct GNUNET_PeerIdentity peer;
 254
 255   /**
 256    * How much bandwidth we are allowed for sending.
 257    */
 258   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out;
 259
 260   /**
 261    * How much bandwidth we are allowed for receiving.
 262    */
 263   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in;
 264
 265 };
 266
 267
 268 /**
 269  * ATS Service suggests to the transport service to try the address
 270  * for the given @e peer.
 271  */
 272 struct AddressSuggestionMessage
 273 {
 274   /**
 275    * A message of type #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_SUGGESTION.
 276    */
 277   struct GNUNET_MessageHeader header;
 278
 279   /**
 280    * Zero.
 281    */
 282   uint32_t reserved GNUNET_PACKED;
 283
 284   /**
 285    * Which peer is this about? (Technically redundant, as the
 286    * @e session_id should be sufficient, but may enable client
 287    * to find the session faster and/or check consistency).
 288    */
 289   struct GNUNET_PeerIdentity peer;
 290
 291   /* Followed by 0-terminated address */
 292 };
 293
 294
 295 GNUNET_NETWORK_STRUCT_END
 296
 297
 298
 299 #endif