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