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