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