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      You should have received a copy of the GNU Affero General Public License
  16      along with this program.  If not, see <http://www.gnu.org/licenses/>.
  17 */
  18 /**
  19  * @file ats/ats.h
  20  * @brief automatic transport selection messages
  21  * @author Christian Grothoff
  22  * @author Matthias Wachs
  23  */
  24 #ifndef ATS_H
  25 #define ATS_H
  26
  27 #include "gnunet_util_lib.h"
  28 #include "gnunet_ats_service.h"
  29
  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  * Connectivity 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    * How "strong" is our need for an address for this peer?
  97    */
  98   uint32_t strength 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: 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    * Number of bytes in the address that follows this struct.
 119    */
 120   uint16_t address_length GNUNET_PACKED;
 121
 122   /**
 123    * Number of bytes in the plugin name that follows this struct.
 124    */
 125   uint16_t plugin_name_length GNUNET_PACKED;
 126
 127   /**
 128    * Identity of the peer that this address is for.
 129    */
 130   struct GNUNET_PeerIdentity peer;
 131
 132   /**
 133    * Internal number this client will henceforth use to
 134    * refer to this address.
 135    */
 136   uint32_t session_id GNUNET_PACKED;
 137
 138   /**
 139    * Local-only information of the address, see
 140    * `enum GNUNET_HELLO_AddressInfo`.
 141    */
 142   uint32_t address_local_info GNUNET_PACKED;
 143
 144   /**
 145    * Performance properties of the address.
 146    */
 147   struct GNUNET_ATS_PropertiesNBO properties;
 148
 149   /* followed by:
 150    * - char address[address_length]
 151    * - char plugin_name[plugin_name_length] (including '\0'-termination).
 152    */
 153
 154 };
 155
 156
 157 /**
 158  * Message used to notify ATS that the performance
 159  * characteristics for an address have changed.
 160  */
 161 struct AddressUpdateMessage
 162 {
 163   /**
 164    * Message of type #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_UPDATE.
 165    */
 166   struct GNUNET_MessageHeader header;
 167
 168   /**
 169    * Internal number this client uses to refer to this address.
 170    */
 171   uint32_t session_id GNUNET_PACKED;
 172
 173   /**
 174    * Which peer is this about? (Technically redundant, as the
 175    * @e session_id should be sufficient, but enables ATS service
 176    * to find the session faster).
 177    */
 178   struct GNUNET_PeerIdentity peer;
 179
 180   /**
 181    * Performance properties of the address.
 182    */
 183   struct GNUNET_ATS_PropertiesNBO properties;
 184
 185 };
 186
 187
 188 /**
 189  * Message sent by ATS client to ATS service when an address
 190  * was destroyed and must thus henceforth no longer be considered
 191  * for scheduling.
 192  */
 193 struct AddressDestroyedMessage
 194 {
 195   /**
 196    * Type is #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_DESTROYED.
 197    */
 198   struct GNUNET_MessageHeader header;
 199
 200   /**
 201    * Internal number this client uses to refer to this address.
 202    */
 203   uint32_t session_id GNUNET_PACKED;
 204
 205   /**
 206    * Which peer is this about? (Technically redundant, as the
 207    * @e session_id should be sufficient, but enables ATS service
 208    * to find the session faster).
 209    */
 210   struct GNUNET_PeerIdentity peer;
 211
 212 };
 213
 214
 215 /**
 216  * Message sent by ATS service to client to confirm that it is done
 217  * using the given session ID.
 218  */
 219 struct GNUNET_ATS_SessionReleaseMessage
 220 {
 221   /**
 222    * Type is #GNUNET_MESSAGE_TYPE_ATS_SESSION_RELEASE.
 223    */
 224   struct GNUNET_MessageHeader header;
 225
 226   /**
 227    * Number the client used to identify the session.
 228    */
 229   uint32_t session_id GNUNET_PACKED;
 230
 231   /**
 232    * Which peer is this about? (Technically redundant, as the
 233    * @e session_id should be sufficient, but may enable client
 234    * to find the session faster).
 235    */
 236   struct GNUNET_PeerIdentity peer;
 237 };
 238
 239
 240
 241 /**
 242  * ATS Service suggests to the transport service to use the address
 243  * identified by the given @e session_id for the given @e peer with
 244  * the given @e bandwidth_in and @e bandwidth_out limits from now on.
 245  */
 246 struct AddressSuggestionMessage
 247 {
 248   /**
 249    * A message of type #GNUNET_MESSAGE_TYPE_ATS_ADDRESS_SUGGESTION.
 250    */
 251   struct GNUNET_MessageHeader header;
 252
 253   /**
 254    * Internal number this client uses to refer to the address this
 255    * suggestion is about.
 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 may enable client
 262    * to find the session faster and/or check consistency).
 263    */
 264   struct GNUNET_PeerIdentity peer;
 265
 266   /**
 267    * How much bandwidth we are allowed for sending.
 268    */
 269   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out;
 270
 271   /**
 272    * How much bandwidth we are allowed for receiving.
 273    */
 274   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in;
 275
 276 };
 277
 278
 279 /**
 280  *
 281  */
 282 struct PeerInformationMessage
 283 {
 284   /**
 285    * Type is #GNUNET_MESSAGE_TYPE_ATS_PEER_INFORMATION
 286    */
 287   struct GNUNET_MessageHeader header;
 288
 289   /**
 290    *
 291    */
 292   uint16_t address_length GNUNET_PACKED;
 293
 294   /**
 295    *
 296    */
 297   uint16_t plugin_name_length GNUNET_PACKED;
 298
 299   /**
 300    *
 301    */
 302   struct GNUNET_PeerIdentity peer;
 303
 304   /**
 305    *
 306    */
 307   uint32_t address_active GNUNET_PACKED;
 308
 309   /**
 310    *
 311    */
 312   uint32_t id GNUNET_PACKED;
 313
 314   /**
 315    *
 316    */
 317   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out;
 318
 319   /**
 320    *
 321    */
 322   struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in;
 323
 324   /**
 325    * Performance properties of the address.
 326    */
 327   struct GNUNET_ATS_PropertiesNBO properties;
 328
 329   /**
 330    * Local-only information of the address, see
 331    * `enum GNUNET_HELLO_AddressInfo`.
 332    */
 333   uint32_t address_local_info GNUNET_PACKED;
 334
 335   /* followed by:
 336    * - char address[address_length]
 337    * - char plugin_name[plugin_name_length] (including '\0'-termination).
 338    */
 339
 340 };
 341
 342
 343 /**
 344  * Client to service: please give us an overview of the addresses.
 345  */
 346 struct AddressListRequestMessage
 347 {
 348   /**
 349    * Type is #GNUNET_MESSAGE_TYPE_ATS_ADDRESSLIST_REQUEST
 350    */
 351   struct GNUNET_MessageHeader header;
 352
 353   /**
 354    * ID used to match replies to this request.
 355    */
 356   uint32_t id GNUNET_PACKED;
 357
 358   /**
 359    * Which peer do we care about? All zeros for all.
 360    */
 361   struct GNUNET_PeerIdentity peer;
 362
 363   /**
 364    * #GNUNET_YES to get information about all addresses,
 365    * #GNUNET_NO to only return addresses that are in use.
 366    */
 367   int32_t all GNUNET_PACKED;
 368
 369 };
 370
 371
 372 /**
 373  *
 374  */
 375 struct ReservationRequestMessage
 376 {
 377   /**
 378    * Type is #GNUNET_MESSAGE_TYPE_ATS_RESERVATION_REQUEST
 379    */
 380   struct GNUNET_MessageHeader header;
 381
 382   /**
 383    *
 384    */
 385   int32_t amount GNUNET_PACKED;
 386
 387   /**
 388    *
 389    */
 390   struct GNUNET_PeerIdentity peer;
 391 };
 392
 393
 394 /**
 395  *
 396  */
 397 struct ReservationResultMessage
 398 {
 399   /**
 400    * Type is #GNUNET_MESSAGE_TYPE_ATS_RESERVATION_RESULT
 401    */
 402   struct GNUNET_MessageHeader header;
 403
 404   /**
 405    *
 406    */
 407   int32_t amount GNUNET_PACKED;
 408
 409   /**
 410    *
 411    */
 412   struct GNUNET_PeerIdentity peer;
 413
 414   /**
 415    *
 416    */
 417   struct GNUNET_TIME_RelativeNBO res_delay;
 418 };
 419
 420
 421 /**
 422  * Variable-size entry in a `struct ChangePreferenceMessage` or
 423  * `struct FeedbackPreferenceMessage`.
 424  */
 425 struct PreferenceInformation
 426 {
 427
 428   /**
 429    * An `enum GNUNET_ATS_PreferenceKind` in NBO.
 430    */
 431   uint32_t preference_kind GNUNET_PACKED;
 432
 433   /**
 434    * Degree of preference (or appreciation) for this @e
 435    * preference_kind being expressed.
 436    */
 437   float preference_value GNUNET_PACKED;
 438
 439 };
 440
 441
 442 /**
 443  * Client to ATS: I have a performance preference for a peer.
 444  */
 445 struct ChangePreferenceMessage
 446 {
 447   /**
 448    * Type is #GNUNET_MESSAGE_TYPE_ATS_PREFERENCE_CHANGE.
 449    */
 450   struct GNUNET_MessageHeader header;
 451
 452   /**
 453    * How many `struct PreferenceInformation` entries follow
 454    * this struct?
 455    */
 456   uint32_t num_preferences GNUNET_PACKED;
 457
 458   /**
 459    * Which peer is the preference being expressed for?
 460    */
 461   struct GNUNET_PeerIdentity peer;
 462
 463   /* followed by 'num_preferences'
 464    * struct PreferenceInformation values */
 465 };
 466
 467
 468 /**
 469  * Message containing application feedback for a peer
 470  */
 471 struct FeedbackPreferenceMessage
 472 {
 473   /**
 474    * Type is #GNUNET_MESSAGE_TYPE_ATS_PREFERENCE_FEEDBACK.
 475    */
 476   struct GNUNET_MessageHeader header;
 477
 478   /**
 479    * Number of feedback values included
 480    */
 481   uint32_t num_feedback GNUNET_PACKED;
 482
 483   /**
 484    * Relative time describing for which time interval this feedback is
 485    */
 486   struct GNUNET_TIME_RelativeNBO scope;
 487
 488   /**
 489    * Peer this feedback is for
 490    */
 491   struct GNUNET_PeerIdentity peer;
 492
 493   /* followed by 'num_feedback'
 494    * struct PreferenceInformation values */
 495 };
 496
 497 GNUNET_NETWORK_STRUCT_END
 498
 499
 500
 501 #endif