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