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 GNUNET_NETWORK_STRUCT_BEGIN
 473
 474 /**
 475  * struct used to communicate the transport's properties like cost and
 476  * quality of service as well as high-level constraints on resource
 477  * consumption.
 478  *
 479  *                             +---+
 480  *  +-----------+ Constraints  |   |  Plugin properties +---------+
 481  *  | Highlevel |------------> |ATS| <------------------|Transport|
 482  *  | Component | ATS struct   |   |    ATS struct      | Plugin  |
 483  *  +-----------+              |   |                    +---------+
 484  *                             +---+
 485  *
 486  * This structure will be used by transport plugins to communicate
 487  * costs to ATS or by higher level components to tell ATS their
 488  * constraints.  Always a pair of (GNUNET_ATS_Property,
 489  * uint32_t value).  Value is always uint32_t, so all units used to
 490  * define costs have to be normalized to fit uint32_t.
 491  */
 492 struct GNUNET_ATS_Information
 493 {
 494   /**
 495    * ATS property type, in network byte order.
 496    */
 497   uint32_t type GNUNET_PACKED;
 498
 499   /**
 500    * ATS property value, in network byte order.
 501    */
 502   uint32_t value GNUNET_PACKED;
 503 };
 504 GNUNET_NETWORK_STRUCT_END
 505
 506 /* ******************************** Scheduling API ***************************** */
 507
 508 /**
 509  * Handle to the ATS subsystem for bandwidth/transport scheduling information.
 510  */
 511 struct GNUNET_ATS_SchedulingHandle;
 512
 513 /**
 514  * Handle for address suggestion requests
 515  *
 516  */
 517 struct GNUNET_ATS_SuggestHandle;
 518
 519 /**
 520  * Opaque session handle, defined by plugins.  Contents not known to ATS.
 521  */
 522 struct Session;
 523
 524 /**
 525  * Signature of a function called by ATS with the current bandwidth
 526  * and address preferences as determined by ATS.
 527  *
 528  * @param cls closure
 529  * @param address suggested address (including peer identity of the peer)
 530  * @param session session to use
 531  * @param bandwidth_out assigned outbound bandwidth for the connection
 532  * @param bandwidth_in assigned inbound bandwidth for the connection
 533  * @param ats performance data for the address (as far as known)
 534  * @param ats_count number of performance records in 'ats'
 535  */
 536 typedef void
 537 (*GNUNET_ATS_AddressSuggestionCallback) (void *cls,
 538     const struct GNUNET_HELLO_Address * address, struct Session * session,
 539     struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out,
 540     struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in,
 541     const struct GNUNET_ATS_Information * ats, uint32_t ats_count);
 542
 543 /**
 544  * Initialize the ATS subsystem.
 545  *
 546  * @param cfg configuration to use
 547  * @param suggest_cb notification to call whenever the suggestation changed
 548  * @param suggest_cb_cls closure for 'suggest_cb'
 549  * @return ats context
 550  */
 551 struct GNUNET_ATS_SchedulingHandle *
 552 GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
 553     GNUNET_ATS_AddressSuggestionCallback suggest_cb, void *suggest_cb_cls);
 554
 555 /**
 556  * Client is done with ATS scheduling, release resources.
 557  *
 558  * @param sh handle to release
 559  */
 560 void
 561 GNUNET_ATS_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh);
 562
 563 /**
 564  * We would like to reset the address suggestion block time for this
 565  * peer
 566  *
 567  * @param sh handle
 568  * @param peer identity of the peer we want to reset
 569  */
 570 void
 571 GNUNET_ATS_reset_backoff (struct GNUNET_ATS_SchedulingHandle *sh,
 572     const struct GNUNET_PeerIdentity *peer);
 573
 574 /**
 575  * We would like to establish a new connection with a peer.  ATS
 576  * should suggest a good address to begin with.
 577  *
 578  * @param sh handle
 579  * @param peer identity of the peer we need an address for
 580  * @return suggestion handle
 581  */
 582 struct GNUNET_ATS_SuggestHandle *
 583 GNUNET_ATS_suggest_address (struct GNUNET_ATS_SchedulingHandle *sh,
 584     const struct GNUNET_PeerIdentity *peer);
 585
 586 /**
 587  * We want to cancel ATS suggesting addresses for a peer.
 588  *
 589  * @param sh handle
 590  * @param peer identity of the peer
 591  */
 592 void
 593 GNUNET_ATS_suggest_address_cancel (struct GNUNET_ATS_SchedulingHandle *sh,
 594     const struct GNUNET_PeerIdentity *peer);
 595
 596 /**
 597  * Convert a ATS property to a string
 598  *
 599  * @param type the atsi type
 600  * @return a string or NULL if invalid
 601  */
 602 const char *
 603 GNUNET_ATS_print_property_type (uint32_t type);
 604
 605 /**
 606  * Convert a GNUNET_ATS_NetworkType to a string
 607  *
 608  * @param net the network type
 609  * @return a string or NULL if invalid
 610  */
 611 const char *
 612 GNUNET_ATS_print_network_type (uint32_t net);
 613
 614 /**
 615  * Returns where the address is located: LAN or WAN or ...
 616  * @param sh the GNUNET_ATS_SchedulingHandle handle
 617  * @param addr address
 618  * @param addrlen address length
 619  * @return location as GNUNET_ATS_Information
 620  */
 621 struct GNUNET_ATS_Information
 622 GNUNET_ATS_address_get_type (struct GNUNET_ATS_SchedulingHandle *sh,
 623     const struct sockaddr * addr, socklen_t addrlen);
 624
 625 /**
 626  * Test if a address and a session is known to ATS
 627  *
 628  * @param sh the scheduling handle
 629  * @param address the address
 630  * @param session the session
 631  * @return GNUNET_YES or GNUNET_NO
 632  */
 633 int
 634 GNUNET_ATS_session_known (struct GNUNET_ATS_SchedulingHandle *sh,
 635     const struct GNUNET_HELLO_Address *address, struct Session *session);
 636
 637 /**
 638  * We have a new address ATS should know. Addresses have to be added with this
 639  * function before they can be: updated, set in use and destroyed
 640  *
 641  * @param sh handle
 642  * @param address the address
 643  * @param session session handle (if available)
 644  * @param ats performance data for the address
 645  * @param ats_count number of performance records in 'ats'
 646  */
 647 int
 648 GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh,
 649     const struct GNUNET_HELLO_Address *address, struct Session *session,
 650     const struct GNUNET_ATS_Information *ats, uint32_t ats_count);
 651
 652 /**
 653  * We have updated performance statistics for a given address.  Note
 654  * that this function can be called for addresses that are currently
 655  * in use as well as addresses that are valid but not actively in use.
 656  * Furthermore, the peer may not even be connected to us right now (in
 657  * which case the call may be ignored or the information may be stored
 658  * for later use).  Update bandwidth assignments.
 659  *
 660  * @param sh handle
 661  * @param address updated address
 662  * @param session session handle (if available)
 663  * @param ats performance data for the address
 664  * @param ats_count number of performance records in 'ats'
 665  * @return GNUNET_OK or GNUNET_SYSERR
 666  */
 667 int
 668 GNUNET_ATS_address_update (struct GNUNET_ATS_SchedulingHandle *sh,
 669     const struct GNUNET_HELLO_Address *address, struct Session *session,
 670     const struct GNUNET_ATS_Information *ats, uint32_t ats_count);
 671
 672 /**
 673  * An address is now in use or not used any more.
 674  *
 675  * @param sh handle
 676  * @param address the address
 677  * @param session session handle
 678  * @param in_use GNUNET_YES if this address is now used, GNUNET_NO
 679  * if address is not used any more
 680  */
 681 void
 682 GNUNET_ATS_address_in_use (struct GNUNET_ATS_SchedulingHandle *sh,
 683     const struct GNUNET_HELLO_Address *address, struct Session *session,
 684     int in_use);
 685
 686 /**
 687  * A session got destroyed, stop including it as a valid address.
 688  *
 689  * @param sh handle
 690  * @param address the address
 691  * @param session session handle that is no longer valid (if available)
 692  */
 693 void
 694 GNUNET_ATS_address_destroyed (struct GNUNET_ATS_SchedulingHandle *sh,
 695     const struct GNUNET_HELLO_Address *address, struct Session *session);
 696
 697 /* ******************************** Performance API ***************************** */
 698
 699 /**
 700  * ATS Handle to obtain and/or modify performance information.
 701  */
 702 struct GNUNET_ATS_PerformanceHandle;
 703
 704 /**
 705  * Signature of a function that is called with QoS information about an address.
 706  *
 707  * @param cls closure
 708  * @param address the address
 709  * @param address_active is this address actively used to maintain a connection
 710  *                              to a peer
 711  * @param bandwidth_out assigned outbound bandwidth for the connection
 712  * @param bandwidth_in assigned inbound bandwidth for the connection
 713  * @param ats performance data for the address (as far as known)
 714  * @param ats_count number of performance records in 'ats'
 715  */
 716 typedef void
 717 (*GNUNET_ATS_AddressInformationCallback) (void *cls,
 718     const struct GNUNET_HELLO_Address *address, int address_active,
 719     struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out,
 720     struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in,
 721     const struct GNUNET_ATS_Information *ats, uint32_t ats_count);
 722
 723 /**
 724  * Handle for an address listing operation
 725  */
 726 struct GNUNET_ATS_AddressListHandle;
 727
 728 /**
 729  * Get handle to access performance API of the ATS subsystem.
 730  *
 731  * @param cfg configuration to use
 732  * @param addr_info_cb callback called when performance characteristics for
 733  *      an address change
 734  * @param addr_info_cb_cls closure for infocb
 735  * @return ats performance context
 736  */
 737 struct GNUNET_ATS_PerformanceHandle *
 738 GNUNET_ATS_performance_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
 739     GNUNET_ATS_AddressInformationCallback addr_info_cb, void *addr_info_cb_cls);
 740
 741 /**
 742  * Get information about addresses known to the ATS subsystem.
 743  *
 744  * @param handle the performance handle to use
 745  * @param peer peer idm can be NULL for all peers
 746  * @param all GNUNET_YES to get information about all addresses or GNUNET_NO to
 747  *        get only address currently used
 748  * @param infocb callback to call with the addresses,
 749  *        will callback with address == NULL when done
 750  * @param infocb_cls closure for infocb
 751  * @return ats performance context
 752  */
 753 struct GNUNET_ATS_AddressListHandle *
 754 GNUNET_ATS_performance_list_addresses (
 755     struct GNUNET_ATS_PerformanceHandle *handle,
 756     const struct GNUNET_PeerIdentity *peer, int all,
 757     GNUNET_ATS_AddressInformationCallback infocb, void *infocb_cls);
 758
 759 /**
 760  * Cancel a pending address listing operation
 761  *
 762  * @param handle the GNUNET_ATS_AddressListHandle handle to cancel
 763  */
 764 void
 765 GNUNET_ATS_performance_list_addresses_cancel (
 766     struct GNUNET_ATS_AddressListHandle *handle);
 767
 768 /**
 769  * Client is done using the ATS performance subsystem, release resources.
 770  *
 771  * @param ph handle
 772  */
 773 void
 774 GNUNET_ATS_performance_done (struct GNUNET_ATS_PerformanceHandle *ph);
 775
 776 /**
 777  * Function called with reservation result.
 778  *
 779  * @param cls closure
 780  * @param peer identifies the peer
 781  * @param amount set to the amount that was actually reserved or unreserved;
 782  *               either the full requested amount or zero (no partial reservations)
 783  * @param res_delay if the reservation could not be satisfied (amount was 0), how
 784  *        long should the client wait until re-trying?
 785  */
 786 typedef void
 787 (*GNUNET_ATS_ReservationCallback) (void *cls,
 788     const struct GNUNET_PeerIdentity * peer, int32_t amount,
 789     struct GNUNET_TIME_Relative res_delay);
 790
 791 /**
 792  * Context that can be used to cancel a peer information request.
 793  */
 794 struct GNUNET_ATS_ReservationContext;
 795
 796 /**
 797  * Reserve inbound bandwidth from the given peer.  ATS will look at
 798  * the current amount of traffic we receive from the peer and ensure
 799  * that the peer could add 'amount' of data to its stream.
 800  *
 801  * @param ph performance handle
 802  * @param peer identifies the peer
 803  * @param amount reserve N bytes for receiving, negative
 804  *                amounts can be used to undo a (recent) reservation;
 805  * @param rcb function to call with the resulting reservation information
 806  * @param rcb_cls closure for info
 807  * @return NULL on error
 808  * @deprecated will be replaced soon
 809  */
 810 struct GNUNET_ATS_ReservationContext *
 811 GNUNET_ATS_reserve_bandwidth (struct GNUNET_ATS_PerformanceHandle *ph,
 812     const struct GNUNET_PeerIdentity *peer, int32_t amount,
 813     GNUNET_ATS_ReservationCallback rcb, void *rcb_cls);
 814
 815 /**
 816  * Cancel request for reserving bandwidth.
 817  *
 818  * @param rc context returned by the original GNUNET_ATS_reserve_bandwidth call
 819  */
 820 void
 821 GNUNET_ATS_reserve_bandwidth_cancel (struct GNUNET_ATS_ReservationContext *rc);
 822
 823 /**
 824  * Number of preference types supported by ATS
 825  */
 826 #define GNUNET_ATS_PreferenceCount 3
 827
 828 /**
 829  * ATS preference types as array initializer
 830  */
 831 #define GNUNET_ATS_PreferenceType {GNUNET_ATS_PREFERENCE_END, GNUNET_ATS_PREFERENCE_BANDWIDTH, GNUNET_ATS_PREFERENCE_LATENCY}
 832
 833 /**
 834  * ATS preference types as string array initializer
 835  */
 836 #define GNUNET_ATS_PreferenceTypeString {"END", "BANDWIDTH", "LATENCY"}
 837
 838 /**
 839  * Enum defining all known preference categories.
 840  */
 841 enum GNUNET_ATS_PreferenceKind
 842 {
 843
 844   /**
 845    * End of preference list.
 846    */
 847   GNUNET_ATS_PREFERENCE_END = 0,
 848
 849   /**
 850    * Change the peer's bandwidth value (value per byte of bandwidth in
 851    * the goal function) to the given amount.  The argument is followed
 852    * by a double value giving the desired value (can be negative).
 853    * Preference changes are forgotten if peers disconnect.
 854    */
 855   GNUNET_ATS_PREFERENCE_BANDWIDTH,
 856
 857   /**
 858    * Change the peer's latency value to the given amount.  The
 859    * argument is followed by a double value giving the desired value
 860    * (can be negative).  The absolute score in the goal function is
 861    * the inverse of the latency in microseconds (minimum: 1
 862    * microsecond) multiplied by the latency preferences.
 863    */
 864   GNUNET_ATS_PREFERENCE_LATENCY
 865 };
 866
 867 /**
 868  * Convert a GNUNET_ATS_PreferenceType to a string
 869  *
 870  * @param type the preference type
 871  * @return a string or NULL if invalid
 872  */
 873 const char *
 874 GNUNET_ATS_print_preference_type (uint32_t type);
 875
 876 /**
 877  * Change preferences for the given peer. Preference changes are forgotten if peers
 878  * disconnect.
 879  *
 880  * @param ph performance handle
 881  * @param peer identifies the peer
 882  * @param ... 0-terminated specification of the desired changes
 883  */
 884 void
 885 GNUNET_ATS_performance_change_preference (
 886     struct GNUNET_ATS_PerformanceHandle *ph,
 887     const struct GNUNET_PeerIdentity *peer, ...);
 888
 889 /**
 890  * Application feedback on how good preference requirements are fulfilled
 891  * for the preferences included in the given time scope [now - scope .. now]
 892  *
 893  * An application notifies ATS if (and only if) it has feedback information
 894  * for specific properties. This values are valid until the feedback scores are
 895  * updated by the application.
 896  *
 897  * If the application has no feedback for this preference kind the application
 898  * will not explicitly call for this property and will not include it in this
 899  * function call.
 900  *
 901  * @param ph performance handle
 902  * @param scope the time interval this valid for: [now - scope .. now]
 903  * @param peer identifies the peer
 904  * @param ... 0-terminated specification of the desired changes
 905  */
 906 void
 907 GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph,
 908     const struct GNUNET_PeerIdentity *peer,
 909     const struct GNUNET_TIME_Relative scope, ...);
 910
 911 #endif
 912 /* end of file gnunet-service-transport_ats.h */