src/include/gnunet_ats_service.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 include/gnunet_ats_service.h
  22  * @brief automatic transport selection and outbound bandwidth determination
  23  * @author Christian Grothoff
  24  * @author Matthias Wachs
  25  */
  26 #ifndef GNUNET_ATS_SERVICE_H
  27 #define GNUNET_ATS_SERVICE_H
  28
  29 #include "gnunet_constants.h"
  30 #include "gnunet_util_lib.h"
  31 #include "gnunet_hello_lib.h"
  32
  33 /**
  34  * Number of network types supported by ATS
  35  */
  36 #define GNUNET_ATS_NetworkTypeCount 6
  37
  38 /**
  39  * ATS network types as array initializer
  40  */
  41 #define GNUNET_ATS_NetworkType { GNUNET_ATS_NET_UNSPECIFIED, GNUNET_ATS_NET_LOOPBACK, GNUNET_ATS_NET_LAN, GNUNET_ATS_NET_WAN, GNUNET_ATS_NET_WLAN, GNUNET_ATS_NET_BT }
  42
  43
  44 /**
  45  * Types of networks (with separate quotas) we support.
  46  */
  47 enum GNUNET_ATS_Network_Type
  48 {
  49   /**
  50    * Category of last resort.
  51    */
  52   GNUNET_ATS_NET_UNSPECIFIED = 0,
  53
  54   /**
  55    * Loopback (same host).
  56    */
  57   GNUNET_ATS_NET_LOOPBACK = 1,
  58
  59   /**
  60    * Local area network.
  61    */
  62   GNUNET_ATS_NET_LAN = 2,
  63
  64   /**
  65    * Wide area network (i.e. Internet)
  66    */
  67   GNUNET_ATS_NET_WAN = 3,
  68
  69   /**
  70    * Wireless LAN (i.e. 802.11abgn)
  71    */
  72   GNUNET_ATS_NET_WLAN = 4,
  73
  74   /**
  75    * Bluetooth LAN
  76    */
  77   GNUNET_ATS_NET_BT = 5
  78 };
  79
  80
  81 /**
  82  * Default bandwidth assigned to a network : 64 KB/s
  83  */
  84 #define GNUNET_ATS_DefaultBandwidth 65536
  85
  86 /**
  87  * Undefined value for an `enum GNUNET_ATS_Property`
  88  */
  89 #define GNUNET_ATS_VALUE_UNDEFINED UINT32_MAX
  90
  91 /**
  92  * String representation for GNUNET_ATS_VALUE_UNDEFINED
  93  */
  94 #define GNUNET_ATS_VALUE_UNDEFINED_STR "undefined"
  95
  96 /**
  97  * Maximum bandwidth assigned to a network : 4095 MB/s
  98  */
  99 #define GNUNET_ATS_MaxBandwidth UINT32_MAX
 100
 101 /**
 102  * Textual equivalent for GNUNET_ATS_MaxBandwidth
 103  */
 104 #define GNUNET_ATS_MaxBandwidthString "unlimited"
 105
 106 /**
 107  * Number of property types supported by ATS
 108  */
 109 #define GNUNET_ATS_PropertyCount 11
 110
 111
 112 /**
 113  * Enum defining all known property types for ATS Enum values are used
 114  * in the GNUNET_ATS_Information struct as
 115  * (key,value)-pairs.
 116  *
 117  * Cost are always stored in uint32_t, so all units used to define costs
 118  * have to be normalized to fit in uint32_t [0 .. UINT32_MAX-1]
 119  *
 120  * UINT32_MAX is reserved for uninitialized values #GNUNET_ATS_VALUE_UNDEFINED
 121  */
 122 enum GNUNET_ATS_Property
 123 {
 124
 125   /**
 126    * End of the array.
 127    * @deprecated
 128    */
 129   GNUNET_ATS_ARRAY_TERMINATOR = 0,
 130
 131   /**
 132    * Actual traffic on this connection from this peer to the other peer.
 133    * Includes transport overhead
 134    *
 135    * Unit: [bytes/second]
 136    */
 137   GNUNET_ATS_UTILIZATION_OUT,
 138
 139   /**
 140    * Actual traffic on this connection from the other peer to this peer.
 141    * Includes transport overhead
 142    *
 143    * Unit: [bytes/second]
 144    */
 145   GNUNET_ATS_UTILIZATION_IN,
 146
 147   /**
 148    * Actual traffic on this connection from this peer to the other peer.
 149    * Only payload from layers > transport
 150    *
 151    * Unit: [bytes/second]
 152    */
 153   GNUNET_ATS_UTILIZATION_PAYLOAD_OUT,
 154
 155   /**
 156    * Actual traffic on this connection from the other peer to this peer.
 157    * Only payload from layers > transport
 158    *
 159    * Unit: [bytes/second]
 160    */
 161   GNUNET_ATS_UTILIZATION_PAYLOAD_IN,
 162
 163   /**
 164    * Is this address located in WAN, LAN or a loopback address
 165    * Value is element of GNUNET_ATS_Network_Type
 166    */
 167   GNUNET_ATS_NETWORK_TYPE,
 168
 169   /**
 170    * Delay
 171    * Time between when the time packet is sent and the packet arrives
 172    *
 173    * Unit: [microseconds]
 174    *
 175    * Examples:
 176    *
 177    * LAN   :    1
 178    * WLAN  :    2
 179    * Dialup:  500
 180    */
 181   GNUNET_ATS_QUALITY_NET_DELAY,
 182
 183   /**
 184    * Distance on network layer (required for distance-vector routing).
 185    *
 186    * Unit: [DV-hops]
 187    */
 188   GNUNET_ATS_QUALITY_NET_DISTANCE,
 189
 190   /**
 191    * Network overhead on WAN (Wide-Area Network)
 192    *
 193    * How many bytes are sent on the WAN when 1 kilobyte (1024 bytes)
 194    * of application data is transmitted?
 195    * A factor used with connect cost, bandwidth cost and energy cost
 196    * to describe the overhead produced by the transport protocol
 197    *
 198    * Unit: [bytes/kb]
 199    *
 200    * Interpretation: less is better
 201    *
 202    * Examples:
 203    *
 204    * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb]
 205    * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb]
 206    * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8  = 1090 [bytes/kb]
 207    * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8  = 1110 [bytes/kb]
 208    */
 209   GNUNET_ATS_COST_WAN,
 210
 211   /**
 212    * Network overhead on LAN (Local-Area Network)
 213    *
 214    * How many bytes are sent on the LAN when 1 kilobyte (1024 bytes)
 215    * of application data is transmitted?
 216    * A factor used with connect cost, bandwidth cost and energy cost
 217    * to describe the overhead produced by the transport protocol
 218    *
 219    * Unit: [bytes/kb]
 220    *
 221    * Interpretation: less is better
 222    *
 223    * Examples:
 224    *
 225    * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb]
 226    * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb]
 227    * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8  = 1090 [bytes/kb]
 228    * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8  = 1110 [bytes/kb]
 229    */
 230   GNUNET_ATS_COST_LAN,
 231
 232   /**
 233    * Network overhead on WLAN (Wireless Local Area Network)
 234    *
 235    * How many bytes are sent on the LAN when 1 kilobyte (1024 bytes)
 236    * of application data is transmitted?
 237    * A factor used with connect cost, bandwidth cost and energy cost
 238    * to describe the overhead produced by the transport protocol
 239    *
 240    * Unit: [bytes/kb]
 241    *
 242    * Interpretation: less is better
 243    *
 244    * Examples:
 245    *
 246    * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb]
 247    * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb]
 248    * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8  = 1090 [bytes/kb]
 249    * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8  = 1110 [bytes/kb]
 250    */
 251   GNUNET_ATS_COST_WLAN
 252
 253 };
 254
 255
 256 /**
 257  * Number of ATS quality properties
 258  */
 259 #define GNUNET_ATS_QualityPropertiesCount 2
 260
 261 /**
 262  * ATS quality properties as array initializer
 263  */
 264 #define GNUNET_ATS_QualityProperties { GNUNET_ATS_QUALITY_NET_DELAY, GNUNET_ATS_QUALITY_NET_DISTANCE }
 265
 266 /**
 267  * ATS quality properties as string array initializer
 268  */
 269 #define GNUNET_ATS_QualityPropertiesString {"Delay", "Distance"}
 270
 271 GNUNET_NETWORK_STRUCT_BEGIN
 272
 273 /**
 274  * struct used to communicate the transport's properties like cost and
 275  * quality of service as well as high-level constraints on resource
 276  * consumption.
 277  *
 278  *                             +---+
 279  *  +-----------+ Constraints  |   |  Plugin properties +---------+
 280  *  | Highlevel |------------> |ATS| <------------------|Transport|
 281  *  | Component | ATS struct   |   |    ATS struct      | Plugin  |
 282  *  +-----------+              |   |                    +---------+
 283  *                             +---+
 284  *
 285  * This structure will be used by transport plugins to communicate
 286  * costs to ATS or by higher level components to tell ATS their
 287  * constraints.  Always a pair of (GNUNET_ATS_Property,
 288  * uint32_t value).  Value is always uint32_t, so all units used to
 289  * define costs have to be normalized to fit uint32_t.
 290  */
 291 struct GNUNET_ATS_Information
 292 {
 293   /**
 294    * ATS property type, in network byte order.
 295    */
 296   uint32_t type GNUNET_PACKED;
 297
 298   /**
 299    * ATS property value, in network byte order.
 300    */
 301   uint32_t value GNUNET_PACKED;
 302 };
 303 GNUNET_NETWORK_STRUCT_END
 304
 305 /* ******************************** Scheduling API ***************************** */
 306
 307 /**
 308  * Handle to the ATS subsystem for bandwidth/transport scheduling information.
 309  */
 310 struct GNUNET_ATS_SchedulingHandle;
 311
 312 /**
 313  * Handle for address suggestion requests
 314  */
 315 struct GNUNET_ATS_SuggestHandle;
 316
 317 /**
 318  * Opaque session handle, defined by plugins.  Contents not known to ATS.
 319  */
 320 struct Session;
 321
 322 /**
 323  * Signature of a function called by ATS with the current bandwidth
 324  * and address preferences as determined by ATS.
 325  *
 326  * If an address is available immediately the address will be included. If no
 327  * address can be suggested, address, session, bandwidth and ATS information will
 328  * be NULL/0. ATS will suggest an address as soon as it can provide such an
 329  * address
 330  *
 331  * @param cls closure
 332  * @param address suggested address (including peer identity of the peer)
 333  * @param session session to use
 334  * @param bandwidth_out assigned outbound bandwidth for the connection
 335  * @param bandwidth_in assigned inbound bandwidth for the connection
 336  * @param ats performance data for the address (as far as known)
 337  * @param ats_count number of performance records in @a ats
 338  */
 339 typedef void
 340 (*GNUNET_ATS_AddressSuggestionCallback) (void *cls,
 341     const struct GNUNET_PeerIdentity *peer,
 342     const struct GNUNET_HELLO_Address *address,
 343     struct Session *session,
 344     struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out,
 345     struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in,
 346     const struct GNUNET_ATS_Information *ats, uint32_t ats_count);
 347
 348
 349 /**
 350  * Initialize the ATS subsystem.
 351  *
 352  * @param cfg configuration to use
 353  * @param suggest_cb notification to call whenever the suggestation changed
 354  * @param suggest_cb_cls closure for @a suggest_cb
 355  * @return ats context
 356  */
 357 struct GNUNET_ATS_SchedulingHandle *
 358 GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
 359     GNUNET_ATS_AddressSuggestionCallback suggest_cb, void *suggest_cb_cls);
 360
 361
 362 /**
 363  * Client is done with ATS scheduling, release resources.
 364  *
 365  * @param sh handle to release
 366  */
 367 void
 368 GNUNET_ATS_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh);
 369
 370
 371 /**
 372  * We would like to reset the address suggestion block time for this
 373  * peer.
 374  *
 375  * @param sh handle
 376  * @param peer identity of the peer we want to reset
 377  */
 378 void
 379 GNUNET_ATS_reset_backoff (struct GNUNET_ATS_SchedulingHandle *sh,
 380                           const struct GNUNET_PeerIdentity *peer);
 381
 382
 383 /**
 384  * We would like to establish a new connection with a peer.  ATS
 385  * should suggest a good address to begin with.
 386  *
 387  * @param sh handle
 388  * @param peer identity of the peer we need an address for
 389  * @return suggestion handle
 390  */
 391 struct GNUNET_ATS_SuggestHandle *
 392 GNUNET_ATS_suggest_address (struct GNUNET_ATS_SchedulingHandle *sh,
 393                             const struct GNUNET_PeerIdentity *peer);
 394
 395
 396 /**
 397  * We want to cancel ATS suggesting addresses for a peer.
 398  *
 399  * @param sh handle
 400  * @param peer identity of the peer
 401  */
 402 void
 403 GNUNET_ATS_suggest_address_cancel (struct GNUNET_ATS_SchedulingHandle *sh,
 404                                    const struct GNUNET_PeerIdentity *peer);
 405
 406
 407 /**
 408  * Convert a ATS property to a string
 409  *
 410  * @param type the property type
 411  * @return a string or NULL if invalid
 412  */
 413 const char *
 414 GNUNET_ATS_print_property_type (enum GNUNET_ATS_Property type);
 415
 416
 417 /**
 418  * Convert a `enum GNUNET_ATS_Network_Type` to a string
 419  *
 420  * @param net the network type
 421  * @return a string or NULL if invalid
 422  */
 423 const char *
 424 GNUNET_ATS_print_network_type (enum GNUNET_ATS_Network_Type net);
 425
 426
 427 /**
 428  * Returns where the address is located: LAN or WAN or ...
 429  *
 430  * @param sh the `struct GNUNET_ATS_SchedulingHandle` handle
 431  * @param addr address
 432  * @param addrlen address length
 433  * @return location as `struct GNUNET_ATS_Information`
 434  */
 435 struct GNUNET_ATS_Information
 436 GNUNET_ATS_address_get_type (struct GNUNET_ATS_SchedulingHandle *sh,
 437                              const struct sockaddr *addr,
 438                              socklen_t addrlen);
 439
 440
 441 /**
 442  * Test if a address and a session is known to ATS.
 443  *
 444  * @param sh the scheduling handle
 445  * @param address the address
 446  * @param session the session
 447  * @return #GNUNET_YES or #GNUNET_NO
 448  */
 449 int
 450 GNUNET_ATS_session_known (struct GNUNET_ATS_SchedulingHandle *sh,
 451                           const struct GNUNET_HELLO_Address *address,
 452                           struct Session *session);
 453
 454
 455 /**
 456  * We have a new address ATS should know. Addresses have to be added with this
 457  * function before they can be: updated, set in use and destroyed
 458  *
 459  * @param sh handle
 460  * @param address the address
 461  * @param session session handle (if available)
 462  * @param ats performance data for the address
 463  * @param ats_count number of performance records in @a ats
 464  */
 465 int
 466 GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh,
 467                         const struct GNUNET_HELLO_Address *address,
 468                         struct Session *session,
 469                         const struct GNUNET_ATS_Information *ats,
 470                         uint32_t ats_count);
 471
 472
 473 /**
 474  * We have updated performance statistics for a given address.  Note
 475  * that this function can be called for addresses that are currently
 476  * in use as well as addresses that are valid but not actively in use.
 477  * Furthermore, the peer may not even be connected to us right now (in
 478  * which case the call may be ignored or the information may be stored
 479  * for later use).  Update bandwidth assignments.
 480  *
 481  * @param sh handle
 482  * @param address updated address
 483  * @param session session handle (if available)
 484  * @param ats performance data for the address
 485  * @param ats_count number of performance records in @a ats
 486  * @return #GNUNET_OK or #GNUNET_SYSERR
 487  */
 488 int
 489 GNUNET_ATS_address_update (struct GNUNET_ATS_SchedulingHandle *sh,
 490                            const struct GNUNET_HELLO_Address *address,
 491                            struct Session *session,
 492                            const struct GNUNET_ATS_Information *ats,
 493                            uint32_t ats_count);
 494
 495
 496 /**
 497  * An address is now in use or not used any more.
 498  *
 499  * @param sh handle
 500  * @param address the address
 501  * @param session session handle
 502  * @param in_use #GNUNET_YES if this address is now used, #GNUNET_NO
 503  * if address is not used any more
 504  */
 505 void
 506 GNUNET_ATS_address_in_use (struct GNUNET_ATS_SchedulingHandle *sh,
 507                            const struct GNUNET_HELLO_Address *address,
 508                            struct Session *session,
 509                            int in_use);
 510
 511
 512 /**
 513  * An address got destroyed, stop including it as a valid address.
 514  *
 515  * If a session is given, only the session will be removed, if no session is
 516  * given the full address will be deleted.
 517  *
 518  * @param sh handle
 519  * @param address the address
 520  * @param session session handle that is no longer valid (if available)
 521  */
 522 void
 523 GNUNET_ATS_address_destroyed (struct GNUNET_ATS_SchedulingHandle *sh,
 524                               const struct GNUNET_HELLO_Address *address,
 525                               struct Session *session);
 526
 527
 528 /* ******************************** Performance API ***************************** */
 529
 530 /**
 531  * ATS Handle to obtain and/or modify performance information.
 532  */
 533 struct GNUNET_ATS_PerformanceHandle;
 534
 535 /**
 536  * Signature of a function that is called with QoS information about an address.
 537  *
 538  * @param cls closure
 539  * @param address the address, NULL if ATS service was disconnected
 540  * @param address_active #GNUNET_YES if this address is actively used
 541  *        to maintain a connection to a peer;
 542  *        #GNUNET_NO if the address is not actively used;
 543  *        #GNUNET_SYSERR if this address is no longer available for ATS
 544  * @param bandwidth_out assigned outbound bandwidth for the connection
 545  * @param bandwidth_in assigned inbound bandwidth for the connection
 546  * @param ats performance data for the address (as far as known)
 547  * @param ats_count number of performance records in @a ats
 548  */
 549 typedef void
 550 (*GNUNET_ATS_AddressInformationCallback) (void *cls,
 551                                           const struct GNUNET_HELLO_Address *address,
 552                                           int address_active,
 553                                           struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out,
 554                                           struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in,
 555                                           const struct GNUNET_ATS_Information *ats,
 556                                           uint32_t ats_count);
 557
 558
 559 /**
 560  * Handle for an address listing operation
 561  */
 562 struct GNUNET_ATS_AddressListHandle;
 563
 564
 565 /**
 566  * Get handle to access performance API of the ATS subsystem.
 567  *
 568  * @param cfg configuration to use
 569  * @param addr_info_cb callback called when performance characteristics for
 570  *      an address change
 571  * @param addr_info_cb_cls closure for @a addr_info_cb
 572  * @return ats performance context
 573  */
 574 struct GNUNET_ATS_PerformanceHandle *
 575 GNUNET_ATS_performance_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
 576                              GNUNET_ATS_AddressInformationCallback addr_info_cb,
 577                              void *addr_info_cb_cls);
 578
 579
 580
 581 /**
 582  * Get information about addresses known to the ATS subsystem.
 583  *
 584  * @param handle the performance handle to use
 585  * @param peer peer idm can be NULL for all peers
 586  * @param all GNUNET_YES to get information about all addresses or GNUNET_NO to
 587  *        get only address currently used
 588  * @param infocb callback to call with the addresses,
 589  *        will callback with address == NULL when done
 590  * @param infocb_cls closure for @a infocb
 591  * @return ats performance context
 592  */
 593 struct GNUNET_ATS_AddressListHandle *
 594 GNUNET_ATS_performance_list_addresses (struct GNUNET_ATS_PerformanceHandle *handle,
 595                                        const struct GNUNET_PeerIdentity *peer,
 596                                        int all,
 597                                        GNUNET_ATS_AddressInformationCallback infocb,
 598                                        void *infocb_cls);
 599
 600
 601 /**
 602  * Cancel a pending address listing operation
 603  *
 604  * @param handle the `struct GNUNET_ATS_AddressListHandle` handle to cancel
 605  */
 606 void
 607 GNUNET_ATS_performance_list_addresses_cancel (struct GNUNET_ATS_AddressListHandle *handle);
 608
 609
 610 /**
 611  * Client is done using the ATS performance subsystem, release resources.
 612  *
 613  * @param ph handle
 614  */
 615 void
 616 GNUNET_ATS_performance_done (struct GNUNET_ATS_PerformanceHandle *ph);
 617
 618
 619 /**
 620  * Function called with reservation result.
 621  *
 622  * @param cls closure
 623  * @param peer identifies the peer
 624  * @param amount set to the amount that was actually reserved or unreserved;
 625  *               either the full requested amount or zero (no partial reservations)
 626  * @param res_delay if the reservation could not be satisfied (amount was 0), how
 627  *        long should the client wait until re-trying?
 628  */
 629 typedef void
 630 (*GNUNET_ATS_ReservationCallback) (void *cls,
 631                                    const struct GNUNET_PeerIdentity * peer,
 632                                    int32_t amount,
 633                                    struct GNUNET_TIME_Relative res_delay);
 634
 635
 636 /**
 637  * Context that can be used to cancel a peer information request.
 638  */
 639 struct GNUNET_ATS_ReservationContext;
 640
 641
 642 /**
 643  * Reserve inbound bandwidth from the given peer.  ATS will look at
 644  * the current amount of traffic we receive from the peer and ensure
 645  * that the peer could add 'amount' of data to its stream.
 646  *
 647  * @param ph performance handle
 648  * @param peer identifies the peer
 649  * @param amount reserve N bytes for receiving, negative
 650  *                amounts can be used to undo a (recent) reservation;
 651  * @param rcb function to call with the resulting reservation information
 652  * @param rcb_cls closure for info
 653  * @return NULL on error
 654  * @deprecated will be replaced soon
 655  */
 656 struct GNUNET_ATS_ReservationContext *
 657 GNUNET_ATS_reserve_bandwidth (struct GNUNET_ATS_PerformanceHandle *ph,
 658     const struct GNUNET_PeerIdentity *peer, int32_t amount,
 659     GNUNET_ATS_ReservationCallback rcb, void *rcb_cls);
 660
 661
 662 /**
 663  * Cancel request for reserving bandwidth.
 664  *
 665  * @param rc context returned by the original GNUNET_ATS_reserve_bandwidth call
 666  */
 667 void
 668 GNUNET_ATS_reserve_bandwidth_cancel (struct GNUNET_ATS_ReservationContext *rc);
 669
 670 /**
 671  * Number of preference types supported by ATS
 672  */
 673 #define GNUNET_ATS_PreferenceCount 3
 674
 675 /**
 676  * ATS preference types as array initializer
 677  */
 678 #define GNUNET_ATS_PreferenceType {GNUNET_ATS_PREFERENCE_END, GNUNET_ATS_PREFERENCE_BANDWIDTH, GNUNET_ATS_PREFERENCE_LATENCY}
 679
 680 /**
 681  * ATS preference types as string array initializer
 682  */
 683 #define GNUNET_ATS_PreferenceTypeString {"END", "BANDWIDTH", "LATENCY"}
 684
 685 /**
 686  * Enum defining all known preference categories.
 687  */
 688 enum GNUNET_ATS_PreferenceKind
 689 {
 690
 691   /**
 692    * End of preference list.
 693    */
 694   GNUNET_ATS_PREFERENCE_END = 0,
 695
 696   /**
 697    * Change the peer's bandwidth value (value per byte of bandwidth in
 698    * the goal function) to the given amount.  The argument is followed
 699    * by a double value giving the desired value (can be negative).
 700    * Preference changes are forgotten if peers disconnect.
 701    */
 702   GNUNET_ATS_PREFERENCE_BANDWIDTH,
 703
 704   /**
 705    * Change the peer's latency value to the given amount.  The
 706    * argument is followed by a double value giving the desired value
 707    * (can be negative).  The absolute score in the goal function is
 708    * the inverse of the latency in microseconds (minimum: 1
 709    * microsecond) multiplied by the latency preferences.
 710    */
 711   GNUNET_ATS_PREFERENCE_LATENCY
 712 };
 713
 714 /**
 715  * Convert a GNUNET_ATS_PreferenceType to a string
 716  *
 717  * @param type the preference type
 718  * @return a string or NULL if invalid
 719  */
 720 const char *
 721 GNUNET_ATS_print_preference_type (uint32_t type);
 722
 723
 724 /**
 725  * Change preferences for the given peer. Preference changes are forgotten if peers
 726  * disconnect.
 727  *
 728  * @param ph performance handle
 729  * @param peer identifies the peer
 730  * @param ... 0-terminated specification of the desired changes
 731  */
 732 void
 733 GNUNET_ATS_performance_change_preference (struct GNUNET_ATS_PerformanceHandle *ph,
 734                                           const struct GNUNET_PeerIdentity *peer, ...);
 735
 736
 737 /**
 738  * Application feedback on how good preference requirements are fulfilled
 739  * for the preferences included in the given time scope [now - scope .. now]
 740  *
 741  * An application notifies ATS if (and only if) it has feedback information
 742  * for specific properties. This values are valid until the feedback scores are
 743  * updated by the application.
 744  *
 745  * If the application has no feedback for this preference kind the application
 746  * will not explicitly call for this property and will not include it in this
 747  * function call.
 748  *
 749  * @param ph performance handle
 750  * @param scope the time interval this valid for: [now - scope .. now]
 751  * @param peer identifies the peer
 752  * @param ... 0-terminated specification of the desired changes
 753  */
 754 void
 755 GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph,
 756     const struct GNUNET_PeerIdentity *peer,
 757     const struct GNUNET_TIME_Relative scope, ...);
 758
 759 #endif
 760 /* end of file gnunet-service-transport_ats.h */