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  * ATS client to ATS service: here is another address you can use.
 109  */
 110 struct AddressAddMessage
 111 {
 112   /**
 113    * Type is #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_ADD.
 114    */
 115   struct GNUNET_MessageHeader header;
 116
 117   /**
 118    * Length of the `struct GNUNET_ATS_Information` array that follows this struct.
 119    */
 120   uint32_t ats_count GNUNET_PACKED;
 121
 122   /**
 123    * Identity of the peer that this address is for.
 124    */
 125   struct GNUNET_PeerIdentity peer;
 126
 127   /**
 128    * Number of bytes in the address that follows this struct.
 129    */
 130   uint16_t address_length GNUNET_PACKED;
 131
 132   /**
 133    * Number of bytes in the plugin name that follows this struct.
 134    */
 135   uint16_t plugin_name_length GNUNET_PACKED;
 136
 137   /**
 138    * Internal number this client will henceforth use to
 139    * refer to this address.
 140    */
 141   uint32_t session_id GNUNET_PACKED;
 142
 143   /**
 144    * Local-only information of the address, see
 145    * `enum GNUNET_HELLO_AddressInfo`.
 146    */
 147   uint32_t address_local_info GNUNET_PACKED;
 148
 149   /* followed by:
 150    * - struct GNUNET_ATS_Information [ats_count];
 151    * - char address[address_length]
 152    * - char plugin_name[plugin_name_length] (including '\0'-termination).
 153    */
 154
 155 };
 156
 157
 158 /**
 159  * Message used to notify ATS that the performance
 160  * characteristics for an address have changed.
 161  */
 162 struct AddressUpdateMessage
 163 {
 164   /**
 165    * Message of type #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_UPDATE.
 166    */
 167   struct GNUNET_MessageHeader header;
 168
 169   /**
 170    * Length of the `struct GNUNET_ATS_Information` array that follows.
 171    */
 172   uint32_t ats_count GNUNET_PACKED;
 173
 174   /**
 175    * Which peer is this about? (Technically redundant, as the
 176    * @e session_id should be sufficient, but enables ATS service
 177    * to find the session faster).
 178    */
 179   struct GNUNET_PeerIdentity peer;
 180
 181   /**
 182    * Internal number this client uses to refer to this address.
 183    */
 184   uint32_t session_id GNUNET_PACKED;
 185
 186   /* followed by:
 187    * - struct GNUNET_ATS_Information [ats_count];
 188    */
 189
 190 };
 191
 192
 193 /**
 194  * Message sent by ATS client to ATS service when an address
 195  * was destroyed and must thus henceforth no longer be considered
 196  * for scheduling.
 197  */
 198 struct AddressDestroyedMessage
 199 {
 200   /**
 201    * Type is #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_DESTROYED.
 202    */
 203   struct GNUNET_MessageHeader header;
 204
 205   /**
 206    * Internal number this client uses to refer to this address.
 207    */
 208   uint32_t session_id GNUNET_PACKED;
 209
 210   /**
 211    * Which peer is this about? (Technically redundant, as the
 212    * @e session_id should be sufficient, but enables ATS service
 213    * to find the session faster).
 214    */
 215   struct GNUNET_PeerIdentity peer;
 216
 217 };
 218
 219
 220 /**
 221  * Message sent by ATS service to client to confirm that it is done
 222  * using the given session ID.
 223  */
 224 struct SessionReleaseMessage
 225 {
 226   /**
 227    * Type is #GNUNET_MESSAGE_TYPE_ATS_SESSION_RELEASE.
 228    */
 229   struct GNUNET_MessageHeader header;
 230
 231   /**
 232    * Number the client used to identify the session.
 233    */
 234   uint32_t session_id GNUNET_PACKED;
 235
 236   /**
 237    * Which peer is this about? (Technically redundant, as the
 238    * @e session_id should be sufficient, but may enable client
 239    * to find the session faster).
 240    */
 241   struct GNUNET_PeerIdentity peer;
 242 };
 243
 244
 245
 246 /**
 247  * ATS Service suggests to the transport service to use the address
 248  * identified by the given @e session_id for the given @e peer with
 249  * the given @e bandwidth_in and @e bandwidth_out limits from now on.
 250  */
 251 struct AddressSuggestionMessage
 252 {
 253   /**
 254    * A message of type #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_SUGGESTION.
 255    */
 256   struct GNUNET_MessageHeader header;
 257
 258   /**
 259    * Internal number this client uses to refer to the address this
 260    * suggestion is about.
 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 may enable client
 267    * to find the session faster and/or check consistency).
 268    */
 269   struct GNUNET_PeerIdentity peer;
 270
 271   /**
 272    * How much bandwidth we are allowed for sending.
 273    */
 274   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out;
 275
 276   /**
 277    * How much bandwidth we are allowed for receiving.
 278    */
 279   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in;
 280
 281 };
 282
 283
 284
 285
 286 struct PeerInformationMessage
 287 {
 288   struct GNUNET_MessageHeader header;
 289
 290   uint32_t ats_count GNUNET_PACKED;
 291
 292   uint32_t address_active GNUNET_PACKED;
 293
 294   uint32_t id GNUNET_PACKED;
 295
 296   struct GNUNET_PeerIdentity peer;
 297
 298   uint16_t address_length GNUNET_PACKED;
 299
 300   uint16_t plugin_name_length GNUNET_PACKED;
 301
 302   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out;
 303
 304   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in;
 305
 306   /* followed by:
 307    * - struct GNUNET_ATS_Information [ats_count];
 308    * - char address[address_length]
 309    * - char plugin_name[plugin_name_length] (including '\0'-termination).
 310    */
 311
 312 };
 313
 314
 315 /**
 316  * Client to service: please give us an overview of the addresses.
 317  */
 318 struct AddressListRequestMessage
 319 {
 320   /**
 321    * Type is #GNUNET_MESSAGE_TYPE_ATS_ADDRESSLIST_REQUEST
 322    */
 323   struct GNUNET_MessageHeader header;
 324
 325   /**
 326    * ID used to match replies to this request.
 327    */
 328   uint32_t id GNUNET_PACKED;
 329
 330   /**
 331    * Which peer do we care about? All zeros for all.
 332    */
 333   struct GNUNET_PeerIdentity peer;
 334
 335   /**
 336    * #GNUNET_YES to get information about all addresses,
 337    * #GNUNET_NO to only return addresses that are in use.
 338    */
 339   int32_t all GNUNET_PACKED;
 340
 341 };
 342
 343
 344 struct ReservationRequestMessage
 345 {
 346   struct GNUNET_MessageHeader header;
 347
 348   int32_t amount GNUNET_PACKED;
 349
 350   struct GNUNET_PeerIdentity peer;
 351 };
 352
 353
 354
 355 struct ReservationResultMessage
 356 {
 357   struct GNUNET_MessageHeader header;
 358
 359   int32_t amount GNUNET_PACKED;
 360
 361   struct GNUNET_PeerIdentity peer;
 362
 363   struct GNUNET_TIME_RelativeNBO res_delay;
 364 };
 365
 366 struct PreferenceInformation
 367 {
 368
 369   uint32_t preference_kind GNUNET_PACKED;
 370
 371   float preference_value GNUNET_PACKED;
 372
 373 };
 374
 375
 376 struct ChangePreferenceMessage
 377 {
 378   struct GNUNET_MessageHeader header;
 379
 380   uint32_t num_preferences GNUNET_PACKED;
 381
 382   struct GNUNET_PeerIdentity peer;
 383
 384   /* followed by 'num_preferences'
 385    * struct PreferenceInformation values */
 386 };
 387
 388
 389 /**
 390  * Message containing application feedback for a peer
 391  */
 392 struct FeedbackPreferenceMessage
 393 {
 394   struct GNUNET_MessageHeader header;
 395
 396   /**
 397    * Number of feedback values included
 398    */
 399   uint32_t num_feedback GNUNET_PACKED;
 400
 401   /**
 402    * Relative time describing for which time interval this feedback is
 403    */
 404   struct GNUNET_TIME_RelativeNBO scope;
 405
 406   /**
 407    * Peer this feedback is for
 408    */
 409   struct GNUNET_PeerIdentity peer;
 410
 411   /* followed by 'num_feedback'
 412    * struct PreferenceInformation values */
 413 };
 414
 415 GNUNET_NETWORK_STRUCT_END
 416
 417
 418
 419 #endif