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