src/ats/ats.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/ats.h
  22  * @brief automatic transport selection messages
  23  * @author Christian Grothoff
  24  * @author Matthias Wachs
  25  */
  26 #ifndef ATS_H
  27 #define ATS_H
  28
  29 #include "gnunet_util_lib.h"
  30 #include "gnunet_ats_service.h"
  31
  32
  33 /**
  34  * Flag used to indicate which type of client is connecting
  35  * to the ATS service.
  36  */
  37 enum StartFlag {
  38   /**
  39    * This is a scheduling client (aka transport service)
  40    */
  41   START_FLAG_SCHEDULING = 0,
  42
  43   /**
  44    * Performance monitoring client that wants to learn about
  45    * changes in performance characteristics.
  46    */
  47   START_FLAG_PERFORMANCE_WITH_PIC = 1,
  48
  49   /**
  50    * Performance monitoring client that does NOT want to learn
  51    * about changes in performance characteristics.
  52    */
  53   START_FLAG_PERFORMANCE_NO_PIC = 2,
  54
  55   /**
  56    * Connection suggestion handle.
  57    */
  58   START_FLAG_CONNECTION_SUGGESTION = 3
  59 };
  60
  61
  62 GNUNET_NETWORK_STRUCT_BEGIN
  63
  64 /**
  65  * First message any client sends to ATS, used to self-identify
  66  * (what type of client this is).
  67  */
  68 struct ClientStartMessage {
  69   /**
  70    * Type is #GNUNET_MESSAGE_TYPE_ATS_START.
  71    */
  72   struct GNUNET_MessageHeader header;
  73
  74   /**
  75    * NBO value of an `enum StartFlag`.
  76    */
  77   uint32_t start_flag GNUNET_PACKED;
  78 };
  79
  80
  81 /**
  82  * Connectivity client to ATS service: we would like to have
  83  * address suggestions for this peer.
  84  */
  85 struct RequestAddressMessage {
  86   /**
  87    * Type is #GNUNET_MESSAGE_TYPE_ATS_REQUEST_ADDRESS or
  88    * #GNUNET_MESSAGE_TYPE_ATS_REQUEST_ADDRESS_CANCEL to stop
  89    * suggestions.
  90    */
  91   struct GNUNET_MessageHeader header;
  92
  93   /**
  94    * How "strong" is our need for an address for this peer?
  95    */
  96   uint32_t strength GNUNET_PACKED;
  97
  98   /**
  99    * Peer to get address suggestions for.
 100    */
 101   struct GNUNET_PeerIdentity peer;
 102 };
 103
 104
 105 /**
 106  * Scheduling client to ATS service: here is another address you can use.
 107  */
 108 struct AddressAddMessage {
 109   /**
 110    * Type is #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_ADD.
 111    */
 112   struct GNUNET_MessageHeader header;
 113
 114   /**
 115    * Number of bytes in the address that follows this struct.
 116    */
 117   uint16_t address_length GNUNET_PACKED;
 118
 119   /**
 120    * Number of bytes in the plugin name that follows this struct.
 121    */
 122   uint16_t plugin_name_length GNUNET_PACKED;
 123
 124   /**
 125    * Identity of the peer that this address is for.
 126    */
 127   struct GNUNET_PeerIdentity peer;
 128
 129   /**
 130    * Internal number this client will henceforth use to
 131    * refer to this address.
 132    */
 133   uint32_t session_id GNUNET_PACKED;
 134
 135   /**
 136    * Local-only information of the address, see
 137    * `enum GNUNET_HELLO_AddressInfo`.
 138    */
 139   uint32_t address_local_info GNUNET_PACKED;
 140
 141   /**
 142    * Performance properties of the address.
 143    */
 144   struct GNUNET_ATS_PropertiesNBO properties;
 145
 146   /* followed by:
 147    * - char address[address_length]
 148    * - char plugin_name[plugin_name_length] (including '\0'-termination).
 149    */
 150 };
 151
 152
 153 /**
 154  * Message used to notify ATS that the performance
 155  * characteristics for an address have changed.
 156  */
 157 struct AddressUpdateMessage {
 158   /**
 159    * Message of type #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_UPDATE.
 160    */
 161   struct GNUNET_MessageHeader header;
 162
 163   /**
 164    * Internal number this client uses to refer to this address.
 165    */
 166   uint32_t session_id GNUNET_PACKED;
 167
 168   /**
 169    * Which peer is this about? (Technically redundant, as the
 170    * @e session_id should be sufficient, but enables ATS service
 171    * to find the session faster).
 172    */
 173   struct GNUNET_PeerIdentity peer;
 174
 175   /**
 176    * Performance properties of the address.
 177    */
 178   struct GNUNET_ATS_PropertiesNBO properties;
 179 };
 180
 181
 182 /**
 183  * Message sent by ATS client to ATS service when an address
 184  * was destroyed and must thus henceforth no longer be considered
 185  * for scheduling.
 186  */
 187 struct AddressDestroyedMessage {
 188   /**
 189    * Type is #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_DESTROYED.
 190    */
 191   struct GNUNET_MessageHeader header;
 192
 193   /**
 194    * Internal number this client uses to refer to this address.
 195    */
 196   uint32_t session_id GNUNET_PACKED;
 197
 198   /**
 199    * Which peer is this about? (Technically redundant, as the
 200    * @e session_id should be sufficient, but enables ATS service
 201    * to find the session faster).
 202    */
 203   struct GNUNET_PeerIdentity peer;
 204 };
 205
 206
 207 /**
 208  * Message sent by ATS service to client to confirm that it is done
 209  * using the given session ID.
 210  */
 211 struct GNUNET_ATS_SessionReleaseMessage {
 212   /**
 213    * Type is #GNUNET_MESSAGE_TYPE_ATS_SESSION_RELEASE.
 214    */
 215   struct GNUNET_MessageHeader header;
 216
 217   /**
 218    * Number the client used to identify the 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 may enable client
 225    * to find the session faster).
 226    */
 227   struct GNUNET_PeerIdentity peer;
 228 };
 229
 230
 231
 232 /**
 233  * ATS Service suggests to the transport service to use the address
 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 AddressSuggestionMessage {
 238   /**
 239    * A message of type #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_SUGGESTION.
 240    */
 241   struct GNUNET_MessageHeader header;
 242
 243   /**
 244    * Internal number this client uses to refer to the address this
 245    * suggestion is about.
 246    */
 247   uint32_t session_id GNUNET_PACKED;
 248
 249   /**
 250    * Which peer is this about? (Technically redundant, as the
 251    * @e session_id should be sufficient, but may enable client
 252    * to find the session faster and/or check consistency).
 253    */
 254   struct GNUNET_PeerIdentity peer;
 255
 256   /**
 257    * How much bandwidth we are allowed for sending.
 258    */
 259   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out;
 260
 261   /**
 262    * How much bandwidth we are allowed for receiving.
 263    */
 264   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in;
 265 };
 266
 267
 268 /**
 269  *
 270  */
 271 struct PeerInformationMessage {
 272   /**
 273    * Type is #GNUNET_MESSAGE_TYPE_ATS_PEER_INFORMATION
 274    */
 275   struct GNUNET_MessageHeader header;
 276
 277   /**
 278    *
 279    */
 280   uint16_t address_length GNUNET_PACKED;
 281
 282   /**
 283    *
 284    */
 285   uint16_t plugin_name_length GNUNET_PACKED;
 286
 287   /**
 288    *
 289    */
 290   struct GNUNET_PeerIdentity peer;
 291
 292   /**
 293    *
 294    */
 295   uint32_t address_active GNUNET_PACKED;
 296
 297   /**
 298    *
 299    */
 300   uint32_t id GNUNET_PACKED;
 301
 302   /**
 303    *
 304    */
 305   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out;
 306
 307   /**
 308    *
 309    */
 310   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in;
 311
 312   /**
 313    * Performance properties of the address.
 314    */
 315   struct GNUNET_ATS_PropertiesNBO properties;
 316
 317   /**
 318    * Local-only information of the address, see
 319    * `enum GNUNET_HELLO_AddressInfo`.
 320    */
 321   uint32_t address_local_info GNUNET_PACKED;
 322
 323   /* followed by:
 324    * - char address[address_length]
 325    * - char plugin_name[plugin_name_length] (including '\0'-termination).
 326    */
 327 };
 328
 329
 330 /**
 331  * Client to service: please give us an overview of the addresses.
 332  */
 333 struct AddressListRequestMessage {
 334   /**
 335    * Type is #GNUNET_MESSAGE_TYPE_ATS_ADDRESSLIST_REQUEST
 336    */
 337   struct GNUNET_MessageHeader header;
 338
 339   /**
 340    * ID used to match replies to this request.
 341    */
 342   uint32_t id GNUNET_PACKED;
 343
 344   /**
 345    * Which peer do we care about? All zeros for all.
 346    */
 347   struct GNUNET_PeerIdentity peer;
 348
 349   /**
 350    * #GNUNET_YES to get information about all addresses,
 351    * #GNUNET_NO to only return addresses that are in use.
 352    */
 353   int32_t all GNUNET_PACKED;
 354 };
 355
 356
 357 /**
 358  *
 359  */
 360 struct ReservationRequestMessage {
 361   /**
 362    * Type is #GNUNET_MESSAGE_TYPE_ATS_RESERVATION_REQUEST
 363    */
 364   struct GNUNET_MessageHeader header;
 365
 366   /**
 367    *
 368    */
 369   int32_t amount GNUNET_PACKED;
 370
 371   /**
 372    *
 373    */
 374   struct GNUNET_PeerIdentity peer;
 375 };
 376
 377
 378 /**
 379  *
 380  */
 381 struct ReservationResultMessage {
 382   /**
 383    * Type is #GNUNET_MESSAGE_TYPE_ATS_RESERVATION_RESULT
 384    */
 385   struct GNUNET_MessageHeader header;
 386
 387   /**
 388    *
 389    */
 390   int32_t amount GNUNET_PACKED;
 391
 392   /**
 393    *
 394    */
 395   struct GNUNET_PeerIdentity peer;
 396
 397   /**
 398    *
 399    */
 400   struct GNUNET_TIME_RelativeNBO res_delay;
 401 };
 402
 403
 404 /**
 405  * Variable-size entry in a `struct ChangePreferenceMessage` or
 406  * `struct FeedbackPreferenceMessage`.
 407  */
 408 struct PreferenceInformation {
 409   /**
 410    * An `enum GNUNET_ATS_PreferenceKind` in NBO.
 411    */
 412   uint32_t preference_kind GNUNET_PACKED;
 413
 414   /**
 415    * Degree of preference (or appreciation) for this @e
 416    * preference_kind being expressed.
 417    */
 418   float preference_value GNUNET_PACKED;
 419 };
 420
 421
 422 /**
 423  * Client to ATS: I have a performance preference for a peer.
 424  */
 425 struct ChangePreferenceMessage {
 426   /**
 427    * Type is #GNUNET_MESSAGE_TYPE_ATS_PREFERENCE_CHANGE.
 428    */
 429   struct GNUNET_MessageHeader header;
 430
 431   /**
 432    * How many `struct PreferenceInformation` entries follow
 433    * this struct?
 434    */
 435   uint32_t num_preferences GNUNET_PACKED;
 436
 437   /**
 438    * Which peer is the preference being expressed for?
 439    */
 440   struct GNUNET_PeerIdentity peer;
 441
 442   /* followed by 'num_preferences'
 443    * struct PreferenceInformation values */
 444 };
 445
 446
 447 /**
 448  * Message containing application feedback for a peer
 449  */
 450 struct FeedbackPreferenceMessage {
 451   /**
 452    * Type is #GNUNET_MESSAGE_TYPE_ATS_PREFERENCE_FEEDBACK.
 453    */
 454   struct GNUNET_MessageHeader header;
 455
 456   /**
 457    * Number of feedback values included
 458    */
 459   uint32_t num_feedback GNUNET_PACKED;
 460
 461   /**
 462    * Relative time describing for which time interval this feedback is
 463    */
 464   struct GNUNET_TIME_RelativeNBO scope;
 465
 466   /**
 467    * Peer this feedback is for
 468    */
 469   struct GNUNET_PeerIdentity peer;
 470
 471   /* followed by 'num_feedback'
 472    * struct PreferenceInformation values */
 473 };
 474
 475 GNUNET_NETWORK_STRUCT_END
 476
 477
 478
 479 #endif