src/include/gnunet_ats_service.h

   1 /*
   2      This file is part of GNUnet.
   3      (C) 2010,2011 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 enum GNUNET_ATS_Network_Type
  35 {
  36   GNUNET_ATS_NET_UNSPECIFIED,
  37   GNUNET_ATS_NET_LOOPBACK,
  38   GNUNET_ATS_NET_LAN,
  39   GNUNET_ATS_NET_WAN
  40 };
  41
  42 /**
  43  * Enum defining all known property types for ATS Enum values are used
  44  * in the GNUNET_ATS_Information struct as
  45  * (key,value)-pairs.
  46  *
  47  * Cost are always stored in uint32_t, so all units used to define costs
  48  * have to be normalized to fit in uint32_t [0 .. 4.294.967.295]
  49  */
  50 enum GNUNET_ATS_Property
  51 {
  52
  53   /**
  54    * End of the array.
  55    * @deprecated
  56    */
  57   GNUNET_ATS_ARRAY_TERMINATOR = 0,
  58
  59   /**
  60    * Actual traffic on this connection from the other peer to this peer.
  61    *
  62    * Unit: [bytes/second]
  63    */
  64   GNUNET_ATS_UTILIZATION_UP,
  65
  66   /**
  67    * Actual traffic on this connection from this peer to the other peer.
  68    *
  69    * Unit: [bytes/second]
  70    */
  71   GNUNET_ATS_UTILIZATION_DOWN,
  72
  73   /**
  74    * Is this address located in WAN, LAN or a loopback address
  75    * Value is element of GNUNET_ATS_Network_Type
  76    */
  77   GNUNET_ATS_NETWORK_TYPE,
  78
  79   /**
  80    * Delay
  81    * Time between when the time packet is sent and the packet arrives
  82    *
  83    * Unit: [ms]
  84    *
  85    * Examples:
  86    *
  87    * LAN   :    1
  88    * WLAN  :    2
  89    * Dialup:  500
  90    */
  91   GNUNET_ATS_QUALITY_NET_DELAY,
  92
  93   /**
  94    * Distance on network layer (required for distance-vector routing).
  95    *
  96    * Unit: [DV-hops]
  97    */
  98   GNUNET_ATS_QUALITY_NET_DISTANCE,
  99
 100   /**
 101    * Network overhead on WAN (Wide-Area Network)
 102    *
 103    * How many bytes are sent on the WAN when 1 kilobyte (1024 bytes)
 104    * of application data is transmitted?
 105    * A factor used with connect cost, bandwidth cost and energy cost
 106    * to describe the overhead produced by the transport protocol
 107    *
 108    * Unit: [bytes/kb]
 109    *
 110    * Interpretation: less is better
 111    *
 112    * Examples:
 113    *
 114    * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb]
 115    * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb]
 116    * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8  = 1090 [bytes/kb]
 117    * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8  = 1110 [bytes/kb]
 118    */
 119   GNUNET_ATS_COST_WAN,
 120
 121   /**
 122    * Network overhead on LAN (Local-Area Network)
 123    *
 124    * How many bytes are sent on the LAN when 1 kilobyte (1024 bytes)
 125    * of application data is transmitted?
 126    * A factor used with connect cost, bandwidth cost and energy cost
 127    * to describe the overhead produced by the transport protocol
 128    *
 129    * Unit: [bytes/kb]
 130    *
 131    * Interpretation: less is better
 132    *
 133    * Examples:
 134    *
 135    * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb]
 136    * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb]
 137    * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8  = 1090 [bytes/kb]
 138    * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8  = 1110 [bytes/kb]
 139    */
 140   GNUNET_ATS_COST_LAN,
 141
 142   /**
 143    * Network overhead on WLAN (Wireless Local Area Network)
 144    *
 145    * How many bytes are sent on the LAN when 1 kilobyte (1024 bytes)
 146    * of application data is transmitted?
 147    * A factor used with connect cost, bandwidth cost and energy cost
 148    * to describe the overhead produced by the transport protocol
 149    *
 150    * Unit: [bytes/kb]
 151    *
 152    * Interpretation: less is better
 153    *
 154    * Examples:
 155    *
 156    * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb]
 157    * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb]
 158    * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8  = 1090 [bytes/kb]
 159    * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8  = 1110 [bytes/kb]
 160    */
 161   GNUNET_ATS_COST_WLAN
 162       /* Cost related values */
 163       /* =================== */
 164   /**
 165    * Volume based cost in financial units to transmit data
 166    *
 167    * Note: This value is not bound to a specific currency or unit and only
 168    * used locally.
 169    * "cent" just refers the smallest amount of money in the respective
 170    * currency.
 171    *
 172    * Unit: [cent/MB]
 173    *
 174    * Interpretation: less is better
 175    *
 176    * Examples:
 177    * LAN:  0 [cent/MB]
 178    * 2G : 10 [cent/MB]
 179    */
 180       // GNUNET_ATS_COST_FINANCIAL_PER_VOLUME = 1,
 181   /**
 182    * Time based cost in financial units to transmit data
 183    *
 184    * Note: This value is not bound to a specific currency or unit and only
 185    * used locally.
 186    * "cent" just refers the smallest amount of money in the respective
 187    * currency.
 188    *
 189    * Unit: [cent/h]
 190    *
 191    * Interpretation: less is better
 192    *
 193    * Examples:
 194    * LAN   :  0 [cent/h]
 195    * Dialup: 10 [cent/h]
 196    */
 197       // GNUNET_ATS_COST_FINANCIAL_PER_TIME = 2,
 198   /**
 199    * Computational costs
 200    *
 201    * Effort of preparing data to be sent with this transport
 202    * Includes encoding, encryption and conversion of data
 203    * Partial values can be summed up: c_sum = c_enc + c_enc + c_conv
 204    * Resulting values depend on local system properties, e.g. CPU
 205    *
 206    * Unit: [ms/GB]
 207    *
 208    * Interpretation: less is better
 209    *
 210    * Examples:
 211    *
 212    * HTTPS with AES CBC-256:    7,382
 213    * HTTPS with AES CBC-128:    5,279
 214    * HTTPS with RC4-1024:       2,652
 215    */
 216       // GNUNET_ATS_COST_COMPUTATIONAL = 3,
 217   /**
 218    * Energy consumption
 219    *
 220    * Energy consumption using this transport when sending with a certain
 221    * power at a certain bitrate. This is only an approximation based on:
 222    * Energy consumption E = P / D
 223    *
 224    * with:
 225    * Power P in Watt (J/s)
 226    * Datarate D in MBit/s
 227    *
 228    * Conversion between power P and dBm used by WLAN in radiotap's dBm TX power:
 229    *
 230    * Lp(dbm) = 10 log10 (P/ 1mW)
 231    *
 232    * => P = 1 mW  * 10^(Lp(dbm)/10)
 233    *
 234    * Unit: [mJ/MB]
 235    *
 236    * Interpretation: less is better
 237    *
 238    * Examples:
 239    *
 240    * LAN:       0
 241    * WLAN:      89 (600 mW @ 802.11g /w 54 MBit/s)
 242    * Bluetooth: 267 (100 mW @ BT2.0 EDR /w 3 MBit/s)
 243    */
 244       // GNUNET_ATS_COST_ENERGY_CONSUMPTION = 4,
 245   /**
 246    * Connect cost
 247    * How many bytes are transmitted to initiate a new connection using
 248    * this transport?
 249    *
 250    * Unit: [bytes]
 251    *
 252    * Interpretation: less is better
 253    *
 254    * Examples:
 255    *
 256    * UDP (No connection)      :
 257    *     0 bytes
 258    * TCP (TCP 3-Way handshake):
 259    *   220 bytes Ethernet,  172 bytes TCP/IP,  122 bytes TCP
 260    * HTTP (TCP + Header)      :
 261    *   477 bytes Ethernet,  429 bytes TCP/IP,  374 bytes TCP,  278 bytes HTTP
 262    * HTTPS  HTTP+TLS Handshake:
 263    *  2129 bytes Ethernet, 1975 bytes TCP/IP, 1755 bytes TCP, 1403 bytes HTTPS
 264    *
 265    * */
 266       // GNUNET_ATS_COST_CONNECT = 5,
 267   /**
 268    * Bandwidth cost
 269    *
 270    * How many bandwidth is available to consume?
 271    * Used to calculate which impact sending data with this transport has
 272    *
 273    * Unit: [kB/s]
 274    *
 275    * Interpretation: more is better
 276    *
 277    * Examples:
 278    * LAN:     12,800  (100 MBit/s)
 279    * WLAN:    6,912   (54 MBit/s)
 280    * Dial-up: 8       (64 Kbit/s)
 281    *
 282    */
 283       // GNUNET_ATS_COST_BANDWITH_AVAILABLE = 6,
 284   /**
 285    *  Network overhead
 286    *
 287    * How many bytes are sent over the wire when 1 kilobyte (1024 bytes)
 288    * of application data is transmitted?
 289    * A factor used with connect cost, bandwidth cost and energy cost
 290    * to describe the overhead produced by the transport protocol
 291    *
 292    * Unit: [bytes/kb]
 293    *
 294    * Interpretation: less is better
 295    *
 296    * Examples:
 297    *
 298    * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb]
 299    * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb]
 300    * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8  = 1090 [bytes/kb]
 301    * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8  = 1110 [bytes/kb]
 302    */
 303       // GNUNET_ATS_COST_NETWORK_OVERHEAD = 7,
 304       /* Quality related values */
 305       /* ====================== */
 306       /* Physical layer quality properties */
 307   /**
 308    * Signal strength on physical layer
 309    *
 310    * Unit: [dBm]
 311    */
 312       // GNUNET_ATS_QUALITY_PHY_SIGNAL_STRENGTH = 1025,
 313   /**
 314    * Collision rate on physical layer
 315    *
 316    * Unit: [B/s]
 317    */
 318       // GNUNET_ATS_QUALITY_PHY_COLLISION_RATE = 1026,
 319   /**
 320    * Error rate on physical layer
 321    *
 322    * Unit: [B/s]
 323    */
 324       // GNUNET_ATS_QUALITY_PHY_ERROR_RATE = 1027,
 325   /**
 326    * Jitter
 327    * Time variations of the delay
 328    * 1st derivative of a delay function
 329    *
 330    * Unit: [ms]
 331    */
 332       // GNUNET_ATS_QUALITY_NET_JITTER = 1029,
 333   /**
 334    * Error rate on network layer
 335    *
 336    * Unit: [B/s]
 337    *
 338    * Examples:
 339    *
 340    * LAN       :    0
 341    * WLAN      :  400
 342    * Bluetooth :  100
 343    * Note: This numbers are just assumptions as an example, not
 344    * measured or somehow determined
 345    */
 346       // GNUNET_ATS_QUALITY_NET_ERRORRATE = 1030,
 347   /**
 348    * Drop rate on network layer
 349    * Bytes actively dismissed by a network component during transmission
 350    * Reasons for dropped data can be full queues, congestion, quota violations...
 351    *
 352    * Unit: [B/s]
 353    *
 354    * Examples:
 355    *
 356    * LAN       :    0
 357    * WLAN      :  400
 358    * Bluetooth :  100
 359    * Note: This numbers are just assumptions as an example, not
 360    * measured or somehow determined
 361    */
 362       // GNUNET_ATS_QUALITY_NET_DROPRATE = 1031,
 363   /**
 364    * Loss rate on network layer
 365    * Bytes lost during transmission
 366    * Reasons can be collisions, ...
 367    *
 368    * Unit: [B/s]
 369    *
 370    * Examples:
 371    *
 372    * LAN       :    0
 373    * WLAN      :   40
 374    * Bluetooth :   10
 375    * Note: This numbers are just assumptions as an example, not measured
 376    * or somehow determined
 377    */
 378       // GNUNET_ATS_QUALITY_NET_LOSSRATE = 1032,
 379   /**
 380    * Throughput on network layer
 381    *
 382    * Unit: [kB/s]
 383    *
 384    * Examples:
 385    *
 386    * LAN   : 3400
 387    * WLAN  : 1200
 388    * Dialup:      4
 389    *
 390    */
 391       // GNUNET_ATS_QUALITY_NET_THROUGHPUT = 1033,
 392       /* Availability related values */
 393       /* =========================== */
 394   /**
 395    * Is a peer reachable?
 396    */
 397       // GNUNET_ATS_AVAILABILITY_REACHABLE = 2048,
 398   /**
 399    * Is there a connection established to a peer using this transport
 400    */
 401       // GNUNET_ATS_AVAILABILITY_CONNECTED = 2049
 402 };
 403
 404
 405 /**
 406  * struct used to communicate the transport's properties like cost and
 407  * quality of service as well as high-level constraints on resource
 408  * consumption.
 409  *
 410  *                             +---+
 411  *  +-----------+ Constraints  |   |  Plugin properties +---------+
 412  *  | Highlevel |------------> |ATS| <------------------|Transport|
 413  *  | Component | ATS struct   |   |    ATS struct      | Plugin  |
 414  *  +-----------+              |   |                    +---------+
 415  *                             +---+
 416  *
 417  * This structure will be used by transport plugins to communicate
 418  * costs to ATS or by higher level components to tell ATS their
 419  * constraints.  Always a pair of (GNUNET_ATS_Property,
 420  * uint32_t value).  Value is always uint32_t, so all units used to
 421  * define costs have to be normalized to fit uint32_t.
 422  */
 423 struct GNUNET_ATS_Information
 424 {
 425   /**
 426    * ATS property type, in network byte order.
 427    */
 428   uint32_t type GNUNET_PACKED;
 429
 430   /**
 431    * ATS property value, in network byte order.
 432    */
 433   uint32_t value GNUNET_PACKED;
 434 };
 435
 436
 437
 438 /* ******************************** Scheduling API ***************************** */
 439
 440 /**
 441  * Handle to the ATS subsystem for bandwidth/transport scheduling information.
 442  */
 443 struct GNUNET_ATS_SchedulingHandle;
 444
 445
 446 /**
 447  * Opaque session handle, defined by plugins.  Contents not known to ATS.
 448  */
 449 struct Session;
 450
 451
 452 /**
 453  * Signature of a function called by ATS with the current bandwidth
 454  * and address preferences as determined by ATS.
 455  *
 456  * @param cls closure
 457  * @param address suggested address (including peer identity of the peer)
 458  * @param session session to use
 459  * @param bandwidth_out assigned outbound bandwidth for the connection
 460  * @param bandwidth_in assigned inbound bandwidth for the connection
 461  * @param ats performance data for the address (as far as known)
 462  * @param ats_count number of performance records in 'ats'
 463  */
 464 typedef void (*GNUNET_ATS_AddressSuggestionCallback) (void *cls,
 465                                                       const struct
 466                                                       GNUNET_HELLO_Address *
 467                                                       address,
 468                                                       struct Session * session,
 469                                                       struct
 470                                                       GNUNET_BANDWIDTH_Value32NBO
 471                                                       bandwidth_out,
 472                                                       struct
 473                                                       GNUNET_BANDWIDTH_Value32NBO
 474                                                       bandwidth_in,
 475                                                       const struct
 476                                                       GNUNET_ATS_Information *
 477                                                       ats, uint32_t ats_count);
 478
 479
 480 /**
 481  * Initialize the ATS subsystem.
 482  *
 483  * @param cfg configuration to use
 484  * @param suggest_cb notification to call whenever the suggestation changed
 485  * @param suggest_cb_cls closure for 'suggest_cb'
 486  * @return ats context
 487  */
 488 struct GNUNET_ATS_SchedulingHandle *
 489 GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
 490                             GNUNET_ATS_AddressSuggestionCallback suggest_cb,
 491                             void *suggest_cb_cls);
 492
 493
 494 /**
 495  * Client is done with ATS scheduling, release resources.
 496  *
 497  * @param sh handle to release
 498  */
 499 void
 500 GNUNET_ATS_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh);
 501
 502
 503 /**
 504  * We would like to establish a new connection with a peer.  ATS
 505  * should suggest a good address to begin with.
 506  *
 507  * @param sh handle
 508  * @param peer identity of the peer we need an address for
 509  */
 510 void
 511 GNUNET_ATS_suggest_address (struct GNUNET_ATS_SchedulingHandle *sh,
 512                             const struct GNUNET_PeerIdentity *peer);
 513
 514
 515 /**
 516  * We want to cancel ATS suggesting addresses for a peer.
 517  *
 518  * @param sh handle
 519  * @param peer identity of the peer
 520  */
 521 void
 522 GNUNET_ATS_suggest_address_cancel (struct GNUNET_ATS_SchedulingHandle *sh,
 523                                    const struct GNUNET_PeerIdentity *peer);
 524
 525
 526 /**
 527  * Returns where the address is located: LAN or WAN or ...
 528  * @param addr address
 529  * @param addrlen address length
 530  * @return location as GNUNET_ATS_Information
 531  */
 532 struct GNUNET_ATS_Information
 533 GNUNET_ATS_address_get_type (struct GNUNET_ATS_SchedulingHandle *sh,
 534                              const struct sockaddr * addr,
 535                              socklen_t addrlen);
 536
 537
 538 /**
 539  * We have updated performance statistics for a given address.  Note
 540  * that this function can be called for addresses that are currently
 541  * in use as well as addresses that are valid but not actively in use.
 542  * Furthermore, the peer may not even be connected to us right now (in
 543  * which case the call may be ignored or the information may be stored
 544  * for later use).  Update bandwidth assignments.
 545  *
 546  * @param sh handle
 547  * @param address updated address
 548  * @param session session handle (if available)
 549  * @param ats performance data for the address
 550  * @param ats_count number of performance records in 'ats'
 551  */
 552 void
 553 GNUNET_ATS_address_update (struct GNUNET_ATS_SchedulingHandle *sh,
 554                            const struct GNUNET_HELLO_Address *address,
 555                            struct Session *session,
 556                            const struct GNUNET_ATS_Information *ats,
 557                            uint32_t ats_count);
 558
 559
 560 /**
 561  * An address is now in use or not used any more.
 562  *
 563  * @param sh handle
 564  * @param address the address
 565  * @param session session handle
 566  * @param in_use GNUNET_YES if this address is now used, GNUNET_NO
 567  * if address is not used any more
 568  */
 569 void
 570 GNUNET_ATS_address_in_use (struct GNUNET_ATS_SchedulingHandle *sh,
 571                            const struct GNUNET_HELLO_Address *address,
 572                            struct Session *session, int in_use);
 573
 574 /**
 575  * A session got destroyed, stop including it as a valid address.
 576  *
 577  * @param sh handle
 578  * @param address the address
 579  * @param session session handle that is no longer valid (if available)
 580  */
 581 void
 582 GNUNET_ATS_address_destroyed (struct GNUNET_ATS_SchedulingHandle *sh,
 583                               const struct GNUNET_HELLO_Address *address,
 584                               struct Session *session);
 585
 586
 587 /* ******************************** Performance API ***************************** */
 588
 589 /**
 590  * ATS Handle to obtain and/or modify performance information.
 591  */
 592 struct GNUNET_ATS_PerformanceHandle;
 593
 594
 595 /**
 596  * Signature of a function that is called with QoS information about a peer.
 597  *
 598  * @param cls closure
 599  * @param address the address
 600  * @param bandwidth_out assigned outbound bandwidth for the connection
 601  * @param bandwidth_in assigned inbound bandwidth for the connection
 602  * @param ats performance data for the address (as far as known)
 603  * @param ats_count number of performance records in 'ats'
 604  */
 605 typedef void (*GNUNET_ATS_PeerInformationCallback) (void *cls,
 606                                                     const struct
 607                                                     GNUNET_HELLO_Address *
 608                                                     address,
 609                                                     struct
 610                                                     GNUNET_BANDWIDTH_Value32NBO
 611                                                     bandwidth_out,
 612                                                     struct
 613                                                     GNUNET_BANDWIDTH_Value32NBO
 614                                                     bandwidth_in,
 615                                                     const struct
 616                                                     GNUNET_ATS_Information *
 617                                                     ats, uint32_t ats_count);
 618
 619
 620 /**
 621  * Get handle to access performance API of the ATS subsystem.
 622  *
 623  * @param cfg configuration to use
 624  * @param infocb function to call on performance changes, can be NULL
 625  * @param infocb_cls closure for infocb
 626  * @return ats performance context
 627  */
 628 struct GNUNET_ATS_PerformanceHandle *
 629 GNUNET_ATS_performance_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
 630                              GNUNET_ATS_PeerInformationCallback infocb,
 631                              void *infocb_cls);
 632
 633
 634 /**
 635  * Client is done using the ATS performance subsystem, release resources.
 636  *
 637  * @param ph handle
 638  */
 639 void
 640 GNUNET_ATS_performance_done (struct GNUNET_ATS_PerformanceHandle *ph);
 641
 642
 643 /**
 644  * Function called with reservation result.
 645  *
 646  * @param cls closure
 647  * @param peer identifies the peer
 648  * @param amount set to the amount that was actually reserved or unreserved;
 649  *               either the full requested amount or zero (no partial reservations)
 650  * @param res_delay if the reservation could not be satisfied (amount was 0), how
 651  *        long should the client wait until re-trying?
 652  */
 653 typedef void (*GNUNET_ATS_ReservationCallback) (void *cls,
 654                                                 const struct GNUNET_PeerIdentity
 655                                                 * peer, int32_t amount,
 656                                                 struct GNUNET_TIME_Relative
 657                                                 res_delay);
 658
 659
 660
 661 /**
 662  * Context that can be used to cancel a peer information request.
 663  */
 664 struct GNUNET_ATS_ReservationContext;
 665
 666
 667 /**
 668  * Reserve inbound bandwidth from the given peer.  ATS will look at
 669  * the current amount of traffic we receive from the peer and ensure
 670  * that the peer could add 'amount' of data to its stream.
 671  *
 672  * @param ph performance handle
 673  * @param peer identifies the peer
 674  * @param amount reserve N bytes for receiving, negative
 675  *                amounts can be used to undo a (recent) reservation;
 676  * @param rcb function to call with the resulting reservation information
 677  * @param rcb_cls closure for info
 678  * @return NULL on error
 679  * @deprecated will be replaced soon
 680  */
 681 struct GNUNET_ATS_ReservationContext *
 682 GNUNET_ATS_reserve_bandwidth (struct GNUNET_ATS_PerformanceHandle *ph,
 683                               const struct GNUNET_PeerIdentity *peer,
 684                               int32_t amount,
 685                               GNUNET_ATS_ReservationCallback rcb,
 686                               void *rcb_cls);
 687
 688
 689 /**
 690  * Cancel request for reserving bandwidth.
 691  *
 692  * @param rc context returned by the original GNUNET_ATS_reserve_bandwidth call
 693  */
 694 void
 695 GNUNET_ATS_reserve_bandwidth_cancel (struct GNUNET_ATS_ReservationContext *rc);
 696
 697
 698
 699 /**
 700  * Enum defining all known preference categories.
 701  */
 702 enum GNUNET_ATS_PreferenceKind
 703 {
 704
 705   /**
 706    * End of preference list.
 707    */
 708   GNUNET_ATS_PREFERENCE_END = 0,
 709
 710   /**
 711    * Change the peer's bandwidth value (value per byte of bandwidth in
 712    * the goal function) to the given amount.  The argument is followed
 713    * by a double value giving the desired value (can be negative).
 714    * Preference changes are forgotten if peers disconnect.
 715    */
 716   GNUNET_ATS_PREFERENCE_BANDWIDTH,
 717
 718   /**
 719    * Change the peer's latency value to the given amount.  The
 720    * argument is followed by a double value giving the desired value
 721    * (can be negative).  The absolute score in the goal function is
 722    * the inverse of the latency in ms (minimum: 1 ms) multiplied by
 723    * the latency preferences.
 724    */
 725   GNUNET_ATS_PREFERENCE_LATENCY
 726 };
 727
 728
 729 /**
 730  * Change preferences for the given peer. Preference changes are forgotten if peers
 731  * disconnect.
 732  *
 733  * @param ph performance handle
 734  * @param peer identifies the peer
 735  * @param ... 0-terminated specification of the desired changes
 736  */
 737 void
 738 GNUNET_ATS_change_preference (struct GNUNET_ATS_PerformanceHandle *ph,
 739                               const struct GNUNET_PeerIdentity *peer, ...);
 740
 741
 742
 743 #endif
 744 /* end of file gnunet-service-transport_ats.h */