src/ats/ats.h

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