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