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