src/ats/ats.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2010-2015 Christian Grothoff (and other contributing authors)
   4
   5      GNUnet is free software; you can redistribute it and/or modify
   6      it under the terms of the GNU General Public License as published
   7      by the Free Software Foundation; either version 3, or (at your
   8      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      General Public License for more details.
  14
  15      You should have received a copy of the GNU General Public License
  16      along with GNUnet; see the file COPYING.  If not, write to the
  17      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  18      Boston, MA 02111-1307, USA.
  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  * Scheduling 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    * Always zero.
  99    */
 100   uint32_t reserved GNUNET_PACKED;
 101
 102   /**
 103    * Peer to get address suggestions for.
 104    */
 105   struct GNUNET_PeerIdentity peer;
 106 };
 107
 108
 109 /**
 110  * ATS 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 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   /* followed by:
 332    * - char address[address_length]
 333    * - char plugin_name[plugin_name_length] (including '\0'-termination).
 334    */
 335
 336 };
 337
 338
 339 /**
 340  * Client to service: please give us an overview of the addresses.
 341  */
 342 struct AddressListRequestMessage
 343 {
 344   /**
 345    * Type is #GNUNET_MESSAGE_TYPE_ATS_ADDRESSLIST_REQUEST
 346    */
 347   struct GNUNET_MessageHeader header;
 348
 349   /**
 350    * ID used to match replies to this request.
 351    */
 352   uint32_t id GNUNET_PACKED;
 353
 354   /**
 355    * Which peer do we care about? All zeros for all.
 356    */
 357   struct GNUNET_PeerIdentity peer;
 358
 359   /**
 360    * #GNUNET_YES to get information about all addresses,
 361    * #GNUNET_NO to only return addresses that are in use.
 362    */
 363   int32_t all GNUNET_PACKED;
 364
 365 };
 366
 367
 368 /**
 369  *
 370  */
 371 struct ReservationRequestMessage
 372 {
 373   /**
 374    * Type is #GNUNET_MESSAGE_TYPE_ATS_RESERVATION_REQUEST
 375    */
 376   struct GNUNET_MessageHeader header;
 377
 378   /**
 379    *
 380    */
 381   int32_t amount GNUNET_PACKED;
 382
 383   /**
 384    *
 385    */
 386   struct GNUNET_PeerIdentity peer;
 387 };
 388
 389
 390 /**
 391  *
 392  */
 393 struct ReservationResultMessage
 394 {
 395   /**
 396    * Type is #GNUNET_MESSAGE_TYPE_ATS_RESERVATION_RESULT
 397    */
 398   struct GNUNET_MessageHeader header;
 399
 400   /**
 401    *
 402    */
 403   int32_t amount GNUNET_PACKED;
 404
 405   /**
 406    *
 407    */
 408   struct GNUNET_PeerIdentity peer;
 409
 410   /**
 411    *
 412    */
 413   struct GNUNET_TIME_RelativeNBO res_delay;
 414 };
 415
 416
 417 /**
 418  * Variable-size entry in a `struct ChangePreferenceMessage` or
 419  * `struct FeedbackPreferenceMessage`.
 420  */
 421 struct PreferenceInformation
 422 {
 423
 424   /**
 425    * An `enum GNUNET_ATS_PreferenceKind` in NBO.
 426    */
 427   uint32_t preference_kind GNUNET_PACKED;
 428
 429   /**
 430    * Degree of preference (or appreciation) for this @e
 431    * preference_kind being expressed.
 432    */
 433   float preference_value GNUNET_PACKED;
 434
 435 };
 436
 437
 438 /**
 439  * Client to ATS: I have a performance preference for a peer.
 440  */
 441 struct ChangePreferenceMessage
 442 {
 443   /**
 444    * Type is #GNUNET_MESSAGE_TYPE_ATS_PREFERENCE_CHANGE.
 445    */
 446   struct GNUNET_MessageHeader header;
 447
 448   /**
 449    * How many `struct PreferenceInformation` entries follow
 450    * this struct?
 451    */
 452   uint32_t num_preferences GNUNET_PACKED;
 453
 454   /**
 455    * Which peer is the preference being expressed for?
 456    */
 457   struct GNUNET_PeerIdentity peer;
 458
 459   /* followed by 'num_preferences'
 460    * struct PreferenceInformation values */
 461 };
 462
 463
 464 /**
 465  * Message containing application feedback for a peer
 466  */
 467 struct FeedbackPreferenceMessage
 468 {
 469   /**
 470    * Type is #GNUNET_MESSAGE_TYPE_ATS_PREFERENCE_FEEDBACK.
 471    */
 472   struct GNUNET_MessageHeader header;
 473
 474   /**
 475    * Number of feedback values included
 476    */
 477   uint32_t num_feedback GNUNET_PACKED;
 478
 479   /**
 480    * Relative time describing for which time interval this feedback is
 481    */
 482   struct GNUNET_TIME_RelativeNBO scope;
 483
 484   /**
 485    * Peer this feedback is for
 486    */
 487   struct GNUNET_PeerIdentity peer;
 488
 489   /* followed by 'num_feedback'
 490    * struct PreferenceInformation values */
 491 };
 492
 493 GNUNET_NETWORK_STRUCT_END
 494
 495
 496
 497 #endif