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