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