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