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