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  * @param cont the continuation to indicate success to call with the address
 390  * @param cont_cls the closure for the @a cont
 391  * @return suggestion handle
 392  */
 393 struct GNUNET_ATS_SuggestHandle *
 394 GNUNET_ATS_suggest_address (struct GNUNET_ATS_SchedulingHandle *sh,
 395                             const struct GNUNET_PeerIdentity *peer,
 396                             GNUNET_ATS_AddressSuggestionCallback cont,
 397                             void *cont_cls);
 398
 399
 400 /**
 401  * We want to cancel ATS suggesting addresses for a peer.
 402  *
 403  * @param sh handle
 404  * @param peer identity of the peer
 405  */
 406 void
 407 GNUNET_ATS_suggest_address_cancel (struct GNUNET_ATS_SchedulingHandle *sh,
 408                                    const struct GNUNET_PeerIdentity *peer);
 409
 410
 411 /**
 412  * Convert a ATS property to a string
 413  *
 414  * @param type the property type
 415  * @return a string or NULL if invalid
 416  */
 417 const char *
 418 GNUNET_ATS_print_property_type (enum GNUNET_ATS_Property type);
 419
 420
 421 /**
 422  * Convert a `enum GNUNET_ATS_Network_Type` to a string
 423  *
 424  * @param net the network type
 425  * @return a string or NULL if invalid
 426  */
 427 const char *
 428 GNUNET_ATS_print_network_type (enum GNUNET_ATS_Network_Type net);
 429
 430
 431 /**
 432  * Returns where the address is located: LAN or WAN or ...
 433  *
 434  * @param sh the `struct GNUNET_ATS_SchedulingHandle` handle
 435  * @param addr address
 436  * @param addrlen address length
 437  * @return location as `struct GNUNET_ATS_Information`
 438  */
 439 struct GNUNET_ATS_Information
 440 GNUNET_ATS_address_get_type (struct GNUNET_ATS_SchedulingHandle *sh,
 441                              const struct sockaddr *addr,
 442                              socklen_t addrlen);
 443
 444
 445 /**
 446  * Test if a address and a session is known to ATS.
 447  *
 448  * @param sh the scheduling handle
 449  * @param address the address
 450  * @param session the session
 451  * @return #GNUNET_YES or #GNUNET_NO
 452  */
 453 int
 454 GNUNET_ATS_session_known (struct GNUNET_ATS_SchedulingHandle *sh,
 455                           const struct GNUNET_HELLO_Address *address,
 456                           struct Session *session);
 457
 458
 459 /**
 460  * We have a new address ATS should know. Addresses have to be added with this
 461  * function before they can be: updated, set in use and destroyed
 462  *
 463  * @param sh handle
 464  * @param address the address
 465  * @param session session handle (if available)
 466  * @param ats performance data for the address
 467  * @param ats_count number of performance records in @a ats
 468  */
 469 int
 470 GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh,
 471                         const struct GNUNET_HELLO_Address *address,
 472                         struct Session *session,
 473                         const struct GNUNET_ATS_Information *ats,
 474                         uint32_t ats_count);
 475
 476
 477 /**
 478  * We have updated performance statistics for a given address.  Note
 479  * that this function can be called for addresses that are currently
 480  * in use as well as addresses that are valid but not actively in use.
 481  * Furthermore, the peer may not even be connected to us right now (in
 482  * which case the call may be ignored or the information may be stored
 483  * for later use).  Update bandwidth assignments.
 484  *
 485  * @param sh handle
 486  * @param address updated address
 487  * @param session session handle (if available)
 488  * @param ats performance data for the address
 489  * @param ats_count number of performance records in @a ats
 490  * @return #GNUNET_OK or #GNUNET_SYSERR
 491  */
 492 int
 493 GNUNET_ATS_address_update (struct GNUNET_ATS_SchedulingHandle *sh,
 494                            const struct GNUNET_HELLO_Address *address,
 495                            struct Session *session,
 496                            const struct GNUNET_ATS_Information *ats,
 497                            uint32_t ats_count);
 498
 499
 500 /**
 501  * An address is now in use or not used any more.
 502  *
 503  * @param sh handle
 504  * @param address the address
 505  * @param session session handle
 506  * @param in_use #GNUNET_YES if this address is now used, #GNUNET_NO
 507  * if address is not used any more
 508  */
 509 void
 510 GNUNET_ATS_address_in_use (struct GNUNET_ATS_SchedulingHandle *sh,
 511                            const struct GNUNET_HELLO_Address *address,
 512                            struct Session *session,
 513                            int in_use);
 514
 515
 516 /**
 517  * An address got destroyed, stop including it as a valid address.
 518  *
 519  * If a session is given, only the session will be removed, if no session is
 520  * given the full address will be deleted.
 521  *
 522  * @param sh handle
 523  * @param address the address
 524  * @param session session handle that is no longer valid (if available)
 525  */
 526 void
 527 GNUNET_ATS_address_destroyed (struct GNUNET_ATS_SchedulingHandle *sh,
 528                               const struct GNUNET_HELLO_Address *address,
 529                               struct Session *session);
 530
 531
 532 /* ******************************** Performance API ***************************** */
 533
 534 /**
 535  * ATS Handle to obtain and/or modify performance information.
 536  */
 537 struct GNUNET_ATS_PerformanceHandle;
 538
 539 /**
 540  * Signature of a function that is called with QoS information about an address.
 541  *
 542  * @param cls closure
 543  * @param address the address, NULL if ATS service was disconnected
 544  * @param address_active #GNUNET_YES if this address is actively used
 545  *        to maintain a connection to a peer;
 546  *        #GNUNET_NO if the address is not actively used;
 547  *        #GNUNET_SYSERR if this address is no longer available for ATS
 548  * @param bandwidth_out assigned outbound bandwidth for the connection
 549  * @param bandwidth_in assigned inbound bandwidth for the connection
 550  * @param ats performance data for the address (as far as known)
 551  * @param ats_count number of performance records in @a ats
 552  */
 553 typedef void
 554 (*GNUNET_ATS_AddressInformationCallback) (void *cls,
 555                                           const struct GNUNET_HELLO_Address *address,
 556                                           int address_active,
 557                                           struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out,
 558                                           struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in,
 559                                           const struct GNUNET_ATS_Information *ats,
 560                                           uint32_t ats_count);
 561
 562
 563 /**
 564  * Handle for an address listing operation
 565  */
 566 struct GNUNET_ATS_AddressListHandle;
 567
 568
 569 /**
 570  * Get handle to access performance API of the ATS subsystem.
 571  *
 572  * @param cfg configuration to use
 573  * @param addr_info_cb callback called when performance characteristics for
 574  *      an address change
 575  * @param addr_info_cb_cls closure for @a addr_info_cb
 576  * @return ats performance context
 577  */
 578 struct GNUNET_ATS_PerformanceHandle *
 579 GNUNET_ATS_performance_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
 580                              GNUNET_ATS_AddressInformationCallback addr_info_cb,
 581                              void *addr_info_cb_cls);
 582
 583
 584
 585 /**
 586  * Get information about addresses known to the ATS subsystem.
 587  *
 588  * @param handle the performance handle to use
 589  * @param peer peer idm can be NULL for all peers
 590  * @param all GNUNET_YES to get information about all addresses or GNUNET_NO to
 591  *        get only address currently used
 592  * @param infocb callback to call with the addresses,
 593  *        will callback with address == NULL when done
 594  * @param infocb_cls closure for @a infocb
 595  * @return ats performance context
 596  */
 597 struct GNUNET_ATS_AddressListHandle *
 598 GNUNET_ATS_performance_list_addresses (struct GNUNET_ATS_PerformanceHandle *handle,
 599                                        const struct GNUNET_PeerIdentity *peer,
 600                                        int all,
 601                                        GNUNET_ATS_AddressInformationCallback infocb,
 602                                        void *infocb_cls);
 603
 604
 605 /**
 606  * Cancel a pending address listing operation
 607  *
 608  * @param handle the `struct GNUNET_ATS_AddressListHandle` handle to cancel
 609  */
 610 void
 611 GNUNET_ATS_performance_list_addresses_cancel (struct GNUNET_ATS_AddressListHandle *handle);
 612
 613
 614 /**
 615  * Client is done using the ATS performance subsystem, release resources.
 616  *
 617  * @param ph handle
 618  */
 619 void
 620 GNUNET_ATS_performance_done (struct GNUNET_ATS_PerformanceHandle *ph);
 621
 622
 623 /**
 624  * Function called with reservation result.
 625  *
 626  * @param cls closure
 627  * @param peer identifies the peer
 628  * @param amount set to the amount that was actually reserved or unreserved;
 629  *               either the full requested amount or zero (no partial reservations)
 630  * @param res_delay if the reservation could not be satisfied (amount was 0), how
 631  *        long should the client wait until re-trying?
 632  */
 633 typedef void
 634 (*GNUNET_ATS_ReservationCallback) (void *cls,
 635                                    const struct GNUNET_PeerIdentity * peer,
 636                                    int32_t amount,
 637                                    struct GNUNET_TIME_Relative res_delay);
 638
 639
 640 /**
 641  * Context that can be used to cancel a peer information request.
 642  */
 643 struct GNUNET_ATS_ReservationContext;
 644
 645
 646 /**
 647  * Reserve inbound bandwidth from the given peer.  ATS will look at
 648  * the current amount of traffic we receive from the peer and ensure
 649  * that the peer could add 'amount' of data to its stream.
 650  *
 651  * @param ph performance handle
 652  * @param peer identifies the peer
 653  * @param amount reserve N bytes for receiving, negative
 654  *                amounts can be used to undo a (recent) reservation;
 655  * @param rcb function to call with the resulting reservation information
 656  * @param rcb_cls closure for info
 657  * @return NULL on error
 658  * @deprecated will be replaced soon
 659  */
 660 struct GNUNET_ATS_ReservationContext *
 661 GNUNET_ATS_reserve_bandwidth (struct GNUNET_ATS_PerformanceHandle *ph,
 662     const struct GNUNET_PeerIdentity *peer, int32_t amount,
 663     GNUNET_ATS_ReservationCallback rcb, void *rcb_cls);
 664
 665
 666 /**
 667  * Cancel request for reserving bandwidth.
 668  *
 669  * @param rc context returned by the original GNUNET_ATS_reserve_bandwidth call
 670  */
 671 void
 672 GNUNET_ATS_reserve_bandwidth_cancel (struct GNUNET_ATS_ReservationContext *rc);
 673
 674 /**
 675  * Number of preference types supported by ATS
 676  */
 677 #define GNUNET_ATS_PreferenceCount 3
 678
 679 /**
 680  * ATS preference types as array initializer
 681  */
 682 #define GNUNET_ATS_PreferenceType {GNUNET_ATS_PREFERENCE_END, GNUNET_ATS_PREFERENCE_BANDWIDTH, GNUNET_ATS_PREFERENCE_LATENCY}
 683
 684 /**
 685  * ATS preference types as string array initializer
 686  */
 687 #define GNUNET_ATS_PreferenceTypeString {"END", "BANDWIDTH", "LATENCY"}
 688
 689 /**
 690  * Enum defining all known preference categories.
 691  */
 692 enum GNUNET_ATS_PreferenceKind
 693 {
 694
 695   /**
 696    * End of preference list.
 697    */
 698   GNUNET_ATS_PREFERENCE_END = 0,
 699
 700   /**
 701    * Change the peer's bandwidth value (value per byte of bandwidth in
 702    * the goal function) to the given amount.  The argument is followed
 703    * by a double value giving the desired value (can be negative).
 704    * Preference changes are forgotten if peers disconnect.
 705    */
 706   GNUNET_ATS_PREFERENCE_BANDWIDTH,
 707
 708   /**
 709    * Change the peer's latency value to the given amount.  The
 710    * argument is followed by a double value giving the desired value
 711    * (can be negative).  The absolute score in the goal function is
 712    * the inverse of the latency in microseconds (minimum: 1
 713    * microsecond) multiplied by the latency preferences.
 714    */
 715   GNUNET_ATS_PREFERENCE_LATENCY
 716 };
 717
 718 /**
 719  * Convert a GNUNET_ATS_PreferenceType to a string
 720  *
 721  * @param type the preference type
 722  * @return a string or NULL if invalid
 723  */
 724 const char *
 725 GNUNET_ATS_print_preference_type (uint32_t type);
 726
 727
 728 /**
 729  * Change preferences for the given peer. Preference changes are forgotten if peers
 730  * disconnect.
 731  *
 732  * @param ph performance handle
 733  * @param peer identifies the peer
 734  * @param ... 0-terminated specification of the desired changes
 735  */
 736 void
 737 GNUNET_ATS_performance_change_preference (struct GNUNET_ATS_PerformanceHandle *ph,
 738                                           const struct GNUNET_PeerIdentity *peer, ...);
 739
 740
 741 /**
 742  * Application feedback on how good preference requirements are fulfilled
 743  * for the preferences included in the given time scope [now - scope .. now]
 744  *
 745  * An application notifies ATS if (and only if) it has feedback information
 746  * for specific properties. This values are valid until the feedback scores are
 747  * updated by the application.
 748  *
 749  * If the application has no feedback for this preference kind the application
 750  * will not explicitly call for this property and will not include it in this
 751  * function call.
 752  *
 753  * @param ph performance handle
 754  * @param scope the time interval this valid for: [now - scope .. now]
 755  * @param peer identifies the peer
 756  * @param ... 0-terminated specification of the desired changes
 757  */
 758 void
 759 GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph,
 760     const struct GNUNET_PeerIdentity *peer,
 761     const struct GNUNET_TIME_Relative scope, ...);
 762
 763 #endif
 764 /* end of file gnunet-service-transport_ats.h */