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