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