X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_ats_service.h;h=7ea624f5e272d5541fcd9ce8d7e13feef9c3e964;hb=6e626937fd5133188d2bd06f280a1b889219eef2;hp=c19fa40b6d153d464d316ffccd1c7cd578b8bff6;hpb=1eef01cd60f92a3d77061d655c0217bd6f9ffce4;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_ats_service.h b/src/include/gnunet_ats_service.h index c19fa40b6..7ea624f5e 100644 --- a/src/include/gnunet_ats_service.h +++ b/src/include/gnunet_ats_service.h @@ -1,27 +1,35 @@ /* This file is part of GNUnet. - (C) 2010,2011 Christian Grothoff (and other contributing authors) + Copyright (C) 2010-2015 GNUnet e.V. - GNUnet is free software; you can redistribute it and/or modify - it under the terms of the GNU General Public License as published - by the Free Software Foundation; either version 3, or (at your - option) any later version. + GNUnet is free software: you can redistribute it and/or modify it + under the terms of the GNU Affero General Public License as published + by the Free Software Foundation, either version 3 of the License, + or (at your option) any later version. GNUnet is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - General Public License for more details. + Affero General Public License for more details. - You should have received a copy of the GNU General Public License - along with GNUnet; see the file COPYING. If not, write to the - Free Software Foundation, Inc., 59 Temple Place - Suite 330, - Boston, MA 02111-1307, USA. + You should have received a copy of the GNU Affero General Public License + along with this program. If not, see . + + SPDX-License-Identifier: AGPL3.0-or-later */ /** - * @file include/gnunet_ats_service.h - * @brief automatic transport selection and outbound bandwidth determination + * @file + * Automatic transport selection and outbound bandwidth determination + * * @author Christian Grothoff * @author Matthias Wachs + * + * @defgroup ats ATS service + * Automatic Transport Selection and outbound bandwidth determination + * + * @see [Documentation](https://gnunet.org/ats-subsystem) + * + * @{ */ #ifndef GNUNET_ATS_SERVICE_H #define GNUNET_ATS_SERVICE_H @@ -30,30 +38,6 @@ #include "gnunet_util_lib.h" #include "gnunet_hello_lib.h" -/** - * Number of network types supported by ATS - */ -#define GNUNET_ATS_NetworkTypeCount 6 - -/** - * ATS network types as array initializer - */ -#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} - -/** - * ATS network types as string array initializer - */ -#define GNUNET_ATS_NetworkTypeString {"UNSPECIFIED", "LOOPBACK", "LAN", "WAN", "WLAN", "BLUETOOTH"} - -enum GNUNET_ATS_Network_Type -{ - GNUNET_ATS_NET_UNSPECIFIED = 0, - GNUNET_ATS_NET_LOOPBACK = 1, - GNUNET_ATS_NET_LAN = 2, - GNUNET_ATS_NET_WAN = 3, - GNUNET_ATS_NET_WLAN = 4, - GNUNET_ATS_NET_BT = 5 -}; /** * Default bandwidth assigned to a network : 64 KB/s @@ -61,7 +45,7 @@ enum GNUNET_ATS_Network_Type #define GNUNET_ATS_DefaultBandwidth 65536 /** - * Undefined value for a GNUNET_ATS_Property + * Undefined value for an `enum GNUNET_ATS_Property` */ #define GNUNET_ATS_VALUE_UNDEFINED UINT32_MAX @@ -80,447 +64,178 @@ enum GNUNET_ATS_Network_Type */ #define GNUNET_ATS_MaxBandwidthString "unlimited" -/** - * Number of property types supported by ATS - */ -#define GNUNET_ATS_PropertyCount 11 - -/** - * ATS properties types as string array initializer - */ -#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"} /** - * Enum defining all known property types for ATS Enum values are used - * in the GNUNET_ATS_Information struct as - * (key,value)-pairs. - * - * Cost are always stored in uint32_t, so all units used to define costs - * have to be normalized to fit in uint32_t [0 .. UINT32_MAX-1] - * - * UINT32_MAX is reserved for uninitialized values GNUNET_ATS_VALUE_UNDEFINED + * ATS performance characteristics for an address. */ -enum GNUNET_ATS_Property +struct GNUNET_ATS_Properties { /** - * End of the array. - * @deprecated + * Delay. Time between when the time packet is sent and the packet + * arrives. FOREVER if we did not measure yet. */ - GNUNET_ATS_ARRAY_TERMINATOR = 0, + struct GNUNET_TIME_Relative delay; /** * Actual traffic on this connection from this peer to the other peer. - * Includes transport overhead + * Includes transport overhead. * * Unit: [bytes/second] */ - GNUNET_ATS_UTILIZATION_OUT, + uint32_t utilization_out; /** * Actual traffic on this connection from the other peer to this peer. - * Includes transport overhead + * Includes transport overhead. * * Unit: [bytes/second] */ - GNUNET_ATS_UTILIZATION_IN, + uint32_t utilization_in; + + /** + * Distance on network layer (required for distance-vector routing) + * in hops. Zero for direct connections (i.e. plain TCP/UDP). + */ + unsigned int distance; + + /** + * Which network scope does the respective address belong to? + * This property does not change. + */ + enum GNUNET_NetworkType scope; + +}; + +/** + * ATS performance characteristics for an address in + * network byte order (for IPC). + */ +struct GNUNET_ATS_PropertiesNBO +{ /** * Actual traffic on this connection from this peer to the other peer. - * Only payload from layers > transport + * Includes transport overhead. * * Unit: [bytes/second] */ - GNUNET_ATS_UTILIZATION_PAYLOAD_OUT, + uint32_t utilization_out GNUNET_PACKED; /** * Actual traffic on this connection from the other peer to this peer. - * Only payload from layers > transport + * Includes transport overhead. * * Unit: [bytes/second] */ - GNUNET_ATS_UTILIZATION_PAYLOAD_IN, + uint32_t utilization_in GNUNET_PACKED; /** - * Is this address located in WAN, LAN or a loopback address - * Value is element of GNUNET_ATS_Network_Type + * Which network scope does the respective address belong to? + * This property does not change. */ - GNUNET_ATS_NETWORK_TYPE, + uint32_t scope GNUNET_PACKED; /** - * Delay - * Time between when the time packet is sent and the packet arrives - * - * Unit: [microseconds] - * - * Examples: - * - * LAN : 1 - * WLAN : 2 - * Dialup: 500 + * Distance on network layer (required for distance-vector routing) + * in hops. Zero for direct connections (i.e. plain TCP/UDP). */ - GNUNET_ATS_QUALITY_NET_DELAY, + uint32_t distance GNUNET_PACKED; /** - * Distance on network layer (required for distance-vector routing). - * - * Unit: [DV-hops] + * Delay. Time between when the time packet is sent and the packet + * arrives. FOREVER if we did not measure yet. */ - GNUNET_ATS_QUALITY_NET_DISTANCE, + struct GNUNET_TIME_RelativeNBO delay; - /** - * Network overhead on WAN (Wide-Area Network) - * - * How many bytes are sent on the WAN when 1 kilobyte (1024 bytes) - * of application data is transmitted? - * A factor used with connect cost, bandwidth cost and energy cost - * to describe the overhead produced by the transport protocol - * - * Unit: [bytes/kb] - * - * Interpretation: less is better - * - * Examples: - * - * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb] - * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb] - * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8 = 1090 [bytes/kb] - * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8 = 1110 [bytes/kb] - */ - GNUNET_ATS_COST_WAN, +}; + + + +/* ********************* LAN Characterization library ************************ */ +/* Note: these functions do not really communicate with the ATS service */ - /** - * Network overhead on LAN (Local-Area Network) - * - * How many bytes are sent on the LAN when 1 kilobyte (1024 bytes) - * of application data is transmitted? - * A factor used with connect cost, bandwidth cost and energy cost - * to describe the overhead produced by the transport protocol - * - * Unit: [bytes/kb] - * - * Interpretation: less is better - * - * Examples: - * - * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb] - * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb] - * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8 = 1090 [bytes/kb] - * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8 = 1110 [bytes/kb] - */ - GNUNET_ATS_COST_LAN, - /** - * Network overhead on WLAN (Wireless Local Area Network) - * - * How many bytes are sent on the LAN when 1 kilobyte (1024 bytes) - * of application data is transmitted? - * A factor used with connect cost, bandwidth cost and energy cost - * to describe the overhead produced by the transport protocol - * - * Unit: [bytes/kb] - * - * Interpretation: less is better - * - * Examples: - * - * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb] - * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb] - * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8 = 1090 [bytes/kb] - * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8 = 1110 [bytes/kb] - */ - GNUNET_ATS_COST_WLAN -/* Cost related values */ -/* =================== */ -/** - * Volume based cost in financial units to transmit data - * - * Note: This value is not bound to a specific currency or unit and only - * used locally. - * "cent" just refers the smallest amount of money in the respective - * currency. - * - * Unit: [cent/MB] - * - * Interpretation: less is better - * - * Examples: - * LAN: 0 [cent/MB] - * 2G : 10 [cent/MB] - */ -// GNUNET_ATS_COST_FINANCIAL_PER_VOLUME = 1, -/** - * Time based cost in financial units to transmit data - * - * Note: This value is not bound to a specific currency or unit and only - * used locally. - * "cent" just refers the smallest amount of money in the respective - * currency. - * - * Unit: [cent/h] - * - * Interpretation: less is better - * - * Examples: - * LAN : 0 [cent/h] - * Dialup: 10 [cent/h] - */ -// GNUNET_ATS_COST_FINANCIAL_PER_TIME = 2, -/** - * Computational costs - * - * Effort of preparing data to be sent with this transport - * Includes encoding, encryption and conversion of data - * Partial values can be summed up: c_sum = c_enc + c_enc + c_conv - * Resulting values depend on local system properties, e.g. CPU - * - * Unit: [ms/GB] - * - * Interpretation: less is better - * - * Examples: - * - * HTTPS with AES CBC-256: 7,382 - * HTTPS with AES CBC-128: 5,279 - * HTTPS with RC4-1024: 2,652 - */ -// GNUNET_ATS_COST_COMPUTATIONAL = 3, -/** - * Energy consumption - * - * Energy consumption using this transport when sending with a certain - * power at a certain bitrate. This is only an approximation based on: - * Energy consumption E = P / D - * - * with: - * Power P in Watt (J/s) - * Datarate D in MBit/s - * - * Conversion between power P and dBm used by WLAN in radiotap's dBm TX power: - * - * Lp(dbm) = 10 log10 (P/ 1mW) - * - * => P = 1 mW * 10^(Lp(dbm)/10) - * - * Unit: [mJ/MB] - * - * Interpretation: less is better - * - * Examples: - * - * LAN: 0 - * WLAN: 89 (600 mW @ 802.11g /w 54 MBit/s) - * Bluetooth: 267 (100 mW @ BT2.0 EDR /w 3 MBit/s) - */ -// GNUNET_ATS_COST_ENERGY_CONSUMPTION = 4, -/** - * Connect cost - * How many bytes are transmitted to initiate a new connection using - * this transport? - * - * Unit: [bytes] - * - * Interpretation: less is better - * - * Examples: - * - * UDP (No connection) : - * 0 bytes - * TCP (TCP 3-Way handshake): - * 220 bytes Ethernet, 172 bytes TCP/IP, 122 bytes TCP - * HTTP (TCP + Header) : - * 477 bytes Ethernet, 429 bytes TCP/IP, 374 bytes TCP, 278 bytes HTTP - * HTTPS HTTP+TLS Handshake: - * 2129 bytes Ethernet, 1975 bytes TCP/IP, 1755 bytes TCP, 1403 bytes HTTPS - * - * */ -// GNUNET_ATS_COST_CONNECT = 5, -/** - * Bandwidth cost - * - * How many bandwidth is available to consume? - * Used to calculate which impact sending data with this transport has - * - * Unit: [kB/s] - * - * Interpretation: more is better - * - * Examples: - * LAN: 12,800 (100 MBit/s) - * WLAN: 6,912 (54 MBit/s) - * Dial-up: 8 (64 Kbit/s) - * - */ -// GNUNET_ATS_COST_BANDWITH_AVAILABLE = 6, -/** - * Network overhead - * - * How many bytes are sent over the wire when 1 kilobyte (1024 bytes) - * of application data is transmitted? - * A factor used with connect cost, bandwidth cost and energy cost - * to describe the overhead produced by the transport protocol - * - * Unit: [bytes/kb] - * - * Interpretation: less is better - * - * Examples: - * - * TCP/IPv4 over Ethernet: 1024 + 38 + 20 + 20 = 1102 [bytes/kb] - * TCP/IPv6 over Ethernet: 1024 + 38 + 20 + 40 = 1122 [bytes/kb] - * UDP/IPv4 over Ethernet: 1024 + 38 + 20 + 8 = 1090 [bytes/kb] - * UDP/IPv6 over Ethernet: 1024 + 38 + 40 + 8 = 1110 [bytes/kb] - */ -// GNUNET_ATS_COST_NETWORK_OVERHEAD = 7, -/* Quality related values */ -/* ====================== */ -/* Physical layer quality properties */ -/** - * Signal strength on physical layer - * - * Unit: [dBm] - */ -// GNUNET_ATS_QUALITY_PHY_SIGNAL_STRENGTH = 1025, -/** - * Collision rate on physical layer - * - * Unit: [B/s] - */ -// GNUNET_ATS_QUALITY_PHY_COLLISION_RATE = 1026, /** - * Error rate on physical layer + * Convert ATS properties from host to network byte order. * - * Unit: [B/s] + * @param nbo[OUT] value written + * @param hbo value read */ -// GNUNET_ATS_QUALITY_PHY_ERROR_RATE = 1027, +void +GNUNET_ATS_properties_hton (struct GNUNET_ATS_PropertiesNBO *nbo, + const struct GNUNET_ATS_Properties *hbo); + + /** - * Jitter - * Time variations of the delay - * 1st derivative of a delay function + * Convert ATS properties from network to host byte order. * - * Unit: [ms] + * @param hbo[OUT] value written + * @param nbo value read */ -// GNUNET_ATS_QUALITY_NET_JITTER = 1029, -/** - * Error rate on network layer - * - * Unit: [B/s] - * - * Examples: - * - * LAN : 0 - * WLAN : 400 - * Bluetooth : 100 - * Note: This numbers are just assumptions as an example, not - * measured or somehow determined - */ -// GNUNET_ATS_QUALITY_NET_ERRORRATE = 1030, +void +GNUNET_ATS_properties_ntoh (struct GNUNET_ATS_Properties *hbo, + const struct GNUNET_ATS_PropertiesNBO *nbo); + + + +/* ********************Connection Suggestion API ***************************** */ + /** - * Drop rate on network layer - * Bytes actively dismissed by a network component during transmission - * Reasons for dropped data can be full queues, congestion, quota violations... - * - * Unit: [B/s] - * - * Examples: - * - * LAN : 0 - * WLAN : 400 - * Bluetooth : 100 - * Note: This numbers are just assumptions as an example, not - * measured or somehow determined + * Handle to the ATS subsystem for making suggestions about + * connections the peer would like to have. */ -// GNUNET_ATS_QUALITY_NET_DROPRATE = 1031, +struct GNUNET_ATS_ConnectivityHandle; + /** - * Loss rate on network layer - * Bytes lost during transmission - * Reasons can be collisions, ... - * - * Unit: [B/s] - * - * Examples: - * - * LAN : 0 - * WLAN : 40 - * Bluetooth : 10 - * Note: This numbers are just assumptions as an example, not measured - * or somehow determined + * Handle for address suggestion requests. */ -// GNUNET_ATS_QUALITY_NET_LOSSRATE = 1032, +struct GNUNET_ATS_ConnectivitySuggestHandle; + + /** - * Throughput on network layer - * - * Unit: [kB/s] + * Initialize the ATS connectivity suggestion client handle. * - * Examples: - * - * LAN : 3400 - * WLAN : 1200 - * Dialup: 4 - * - */ -// GNUNET_ATS_QUALITY_NET_THROUGHPUT = 1033, -/* Availability related values */ -/* =========================== */ -/** - * Is a peer reachable? - */ -// GNUNET_ATS_AVAILABILITY_REACHABLE = 2048, -/** - * Is there a connection established to a peer using this transport + * @param cfg configuration to use + * @return ats connectivity handle, NULL on error */ -// GNUNET_ATS_AVAILABILITY_CONNECTED = 2049 -}; +struct GNUNET_ATS_ConnectivityHandle * +GNUNET_ATS_connectivity_init (const struct GNUNET_CONFIGURATION_Handle *cfg); -/** - * Number of ATS quality properties - */ -#define GNUNET_ATS_QualityPropertiesCount 2 /** - * ATS quality properties as array initializer + * Shutdown ATS connectivity suggestion client. + * + * @param ch handle to destroy */ -#define GNUNET_ATS_QualityProperties {GNUNET_ATS_QUALITY_NET_DELAY, GNUNET_ATS_QUALITY_NET_DISTANCE} +void +GNUNET_ATS_connectivity_done (struct GNUNET_ATS_ConnectivityHandle *ch); + /** - * ATS quality properties as string array initializer + * We would like to establish a new connection with a peer. ATS + * should suggest a good address to begin with. + * + * @param ch handle + * @param peer identity of the peer we need an address for + * @param strength how urgent is the need for such a suggestion + * @return suggestion handle, NULL if request is already pending */ -#define GNUNET_ATS_QualityPropertiesString {"Delay", "Distance"} +struct GNUNET_ATS_ConnectivitySuggestHandle * +GNUNET_ATS_connectivity_suggest (struct GNUNET_ATS_ConnectivityHandle *ch, + const struct GNUNET_PeerIdentity *peer, + uint32_t strength); -GNUNET_NETWORK_STRUCT_BEGIN /** - * struct used to communicate the transport's properties like cost and - * quality of service as well as high-level constraints on resource - * consumption. - * - * +---+ - * +-----------+ Constraints | | Plugin properties +---------+ - * | Highlevel |------------> |ATS| <------------------|Transport| - * | Component | ATS struct | | ATS struct | Plugin | - * +-----------+ | | +---------+ - * +---+ + * We no longer care about being connected to a peer. * - * This structure will be used by transport plugins to communicate - * costs to ATS or by higher level components to tell ATS their - * constraints. Always a pair of (GNUNET_ATS_Property, - * uint32_t value). Value is always uint32_t, so all units used to - * define costs have to be normalized to fit uint32_t. + * @param sh handle */ -struct GNUNET_ATS_Information -{ - /** - * ATS property type, in network byte order. - */ - uint32_t type GNUNET_PACKED; +void +GNUNET_ATS_connectivity_suggest_cancel (struct GNUNET_ATS_ConnectivitySuggestHandle *sh); - /** - * ATS property value, in network byte order. - */ - uint32_t value GNUNET_PACKED; -}; -GNUNET_NETWORK_STRUCT_END /* ******************************** Scheduling API ***************************** */ @@ -529,44 +244,39 @@ GNUNET_NETWORK_STRUCT_END */ struct GNUNET_ATS_SchedulingHandle; -/** - * Handle for address suggestion requests - */ -struct GNUNET_ATS_SuggestHandle; - /** * Opaque session handle, defined by plugins. Contents not known to ATS. */ -struct Session; +struct GNUNET_ATS_Session; + /** * Signature of a function called by ATS with the current bandwidth - * and address preferences as determined by ATS. - * - * If an address is available immediately the address will be included. If no - * address can be suggested, address, session, bandwidth and ATS information will - * be NULL/0. ATS will suggest an address as soon as it can provide such an - * address + * and address preferences as determined by ATS. If our connection + * to ATS dies and thus all suggestions become invalid, this function + * is called ONCE with all arguments (except @a cls) being NULL/0. * * @param cls closure - * @param address suggested address (including peer identity of the peer) - * @param session session to use - * @param bandwidth_out assigned outbound bandwidth for the connection - * @param bandwidth_in assigned inbound bandwidth for the connection - * @param ats performance data for the address (as far as known) - * @param ats_count number of performance records in @a ats + * @param peer for which we suggest an address, NULL if ATS connection died + * @param address suggested address (including peer identity of the peer), + * may be NULL to signal disconnect from peer + * @param session session to use, NULL to establish a new outgoing session + * @param bandwidth_out assigned outbound bandwidth for the connection, + * 0 to signal disconnect + * @param bandwidth_in assigned inbound bandwidth for the connection, + * 0 to signal disconnect */ typedef void (*GNUNET_ATS_AddressSuggestionCallback) (void *cls, - const struct GNUNET_PeerIdentity *peer, - const struct GNUNET_HELLO_Address *address, struct Session *session, - struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out, - struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in, - const struct GNUNET_ATS_Information *ats, uint32_t ats_count); + const struct GNUNET_PeerIdentity *peer, + const struct GNUNET_HELLO_Address *address, + struct GNUNET_ATS_Session *session, + struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out, + struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in); /** - * Initialize the ATS subsystem. + * Initialize the ATS scheduling subsystem. * * @param cfg configuration to use * @param suggest_cb notification to call whenever the suggestation changed @@ -575,7 +285,8 @@ typedef void */ struct GNUNET_ATS_SchedulingHandle * GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg, - GNUNET_ATS_AddressSuggestionCallback suggest_cb, void *suggest_cb_cls); + GNUNET_ATS_AddressSuggestionCallback suggest_cb, + void *suggest_cb_cls); /** @@ -588,163 +299,85 @@ GNUNET_ATS_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh); /** - * We would like to reset the address suggestion block time for this - * peer - * - * @param sh handle - * @param peer identity of the peer we want to reset + * Handle used within ATS to track an address. */ -void -GNUNET_ATS_reset_backoff (struct GNUNET_ATS_SchedulingHandle *sh, - const struct GNUNET_PeerIdentity *peer); +struct GNUNET_ATS_AddressRecord; /** - * We would like to establish a new connection with a peer. ATS - * should suggest a good address to begin with. + * We have a new address ATS should know. Addresses have to be added with this + * function before they can be: updated, set in use and destroyed * * @param sh handle - * @param peer identity of the peer we need an address for - * @param cont the continuation to indicate success to call with the address - * @param cont_cls the closure for the @a cont - * @return suggestion handle + * @param address the address + * @param session session handle (if available, i.e. for incoming connections) + * @param prop performance data for the address + * @return handle to the address representation inside ATS, NULL + * on error (i.e. ATS knows this exact address already, or + * address is invalid) */ -struct GNUNET_ATS_SuggestHandle * -GNUNET_ATS_suggest_address (struct GNUNET_ATS_SchedulingHandle *sh, - const struct GNUNET_PeerIdentity *peer, - GNUNET_ATS_AddressSuggestionCallback cont, - void *cont_cls); +struct GNUNET_ATS_AddressRecord * +GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh, + const struct GNUNET_HELLO_Address *address, + struct GNUNET_ATS_Session *session, + const struct GNUNET_ATS_Properties *prop); /** - * We want to cancel ATS suggesting addresses for a peer. + * An address was used to initiate a session. * - * @param sh handle - * @param peer identity of the peer + * @param ar address record to update information for + * @param session session handle */ void -GNUNET_ATS_suggest_address_cancel (struct GNUNET_ATS_SchedulingHandle *sh, - const struct GNUNET_PeerIdentity *peer); - - -/** - * Convert a ATS property to a string - * - * @param type the atsi type - * @return a string or NULL if invalid - */ -const char * -GNUNET_ATS_print_property_type (uint32_t type); - - -/** - * Convert a GNUNET_ATS_NetworkType to a string - * - * @param net the network type - * @return a string or NULL if invalid - */ -const char * -GNUNET_ATS_print_network_type (uint32_t net); - - -/** - * Returns where the address is located: LAN or WAN or ... - * @param sh the `struct GNUNET_ATS_SchedulingHandle` handle - * @param addr address - * @param addrlen address length - * @return location as `struct GNUNET_ATS_Information` - */ -struct GNUNET_ATS_Information -GNUNET_ATS_address_get_type (struct GNUNET_ATS_SchedulingHandle *sh, - const struct sockaddr * addr, - socklen_t addrlen); - - -/** - * Test if a address and a session is known to ATS - * - * @param sh the scheduling handle - * @param address the address - * @param session the session - * @return #GNUNET_YES or #GNUNET_NO - */ -int -GNUNET_ATS_session_known (struct GNUNET_ATS_SchedulingHandle *sh, - const struct GNUNET_HELLO_Address *address, - struct Session *session); +GNUNET_ATS_address_add_session (struct GNUNET_ATS_AddressRecord *ar, + struct GNUNET_ATS_Session *session); /** - * We have a new address ATS should know. Addresses have to be added with this - * function before they can be: updated, set in use and destroyed + * A @a session was destroyed, disassociate it from the given address + * record. If this was an incoming addess, destroys the address as + * well. * - * @param sh handle - * @param address the address - * @param session session handle (if available) - * @param ats performance data for the address - * @param ats_count number of performance records in @a ats + * @param ar address record to update information for + * @param session session handle + * @return #GNUNET_YES if the @a ar was destroyed because + * it was an incoming address, + * #GNUNET_NO if the @ar was kept because we can + * use it still to establish a new session */ int -GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh, - const struct GNUNET_HELLO_Address *address, - struct Session *session, - const struct GNUNET_ATS_Information *ats, - uint32_t ats_count); +GNUNET_ATS_address_del_session (struct GNUNET_ATS_AddressRecord *ar, + struct GNUNET_ATS_Session *session); /** * We have updated performance statistics for a given address. Note * that this function can be called for addresses that are currently * in use as well as addresses that are valid but not actively in use. - * Furthermore, the peer may not even be connected to us right now (in - * which case the call may be ignored or the information may be stored - * for later use). Update bandwidth assignments. + * Furthermore, the peer may not even be connected to us right now (@a + * session value of NULL used to signal disconnect, or somehow we + * otherwise got updated on @a ats information). Based on the + * information provided, ATS may update bandwidth assignments and + * suggest to switch addresses. * - * @param sh handle - * @param address updated address - * @param session session handle (if available) - * @param ats performance data for the address - * @param ats_count number of performance records in @a ats - * @return #GNUNET_OK or #GNUNET_SYSERR - */ -int -GNUNET_ATS_address_update (struct GNUNET_ATS_SchedulingHandle *sh, - const struct GNUNET_HELLO_Address *address, - struct Session *session, - const struct GNUNET_ATS_Information *ats, - uint32_t ats_count); - - -/** - * An address is now in use or not used any more. - * - * @param sh handle - * @param address the address - * @param session session handle - * @param in_use #GNUNET_YES if this address is now used, #GNUNET_NO - * if address is not used any more + * @param ar address record to update information for + * @param prop performance data for the address */ void -GNUNET_ATS_address_in_use (struct GNUNET_ATS_SchedulingHandle *sh, - const struct GNUNET_HELLO_Address *address, - struct Session *session, - int in_use); +GNUNET_ATS_address_update (struct GNUNET_ATS_AddressRecord *ar, + const struct GNUNET_ATS_Properties *prop); /** - * An address got destroyed, stop including it as a valid address. - * - * If a session is given, only the session will be removed, if no session is - * given the full address will be deleted. + * An address got destroyed, stop using it as a valid address. * - * @param sh handle - * @param address the address - * @param session session handle that is no longer valid (if available) + * @param ar address record to destroy, it's validation has + * expired and ATS may no longer use it */ void -GNUNET_ATS_address_destroyed (struct GNUNET_ATS_SchedulingHandle *sh, - const struct GNUNET_HELLO_Address *address, - struct Session *session); +GNUNET_ATS_address_destroy (struct GNUNET_ATS_AddressRecord *ar); + /* ******************************** Performance API ***************************** */ @@ -758,15 +391,16 @@ struct GNUNET_ATS_PerformanceHandle; * Signature of a function that is called with QoS information about an address. * * @param cls closure - * @param address the address, NULL if ATS service was disconnected + * @param address the address, NULL if ATS service was disconnected or + * when the iteration is completed in the case of + * #GNUNET_ATS_performance_list_addresses() * @param address_active #GNUNET_YES if this address is actively used * to maintain a connection to a peer; * #GNUNET_NO if the address is not actively used; * #GNUNET_SYSERR if this address is no longer available for ATS * @param bandwidth_out assigned outbound bandwidth for the connection * @param bandwidth_in assigned inbound bandwidth for the connection - * @param ats performance data for the address (as far as known) - * @param ats_count number of performance records in @a ats + * @param prop performance data for the address */ typedef void (*GNUNET_ATS_AddressInformationCallback) (void *cls, @@ -774,8 +408,7 @@ typedef void int address_active, struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out, struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in, - const struct GNUNET_ATS_Information *ats, - uint32_t ats_count); + const struct GNUNET_ATS_Properties *prop); /** @@ -799,21 +432,20 @@ GNUNET_ATS_performance_init (const struct GNUNET_CONFIGURATION_Handle *cfg, void *addr_info_cb_cls); - /** * Get information about addresses known to the ATS subsystem. * - * @param handle the performance handle to use + * @param ph the performance handle to use * @param peer peer idm can be NULL for all peers - * @param all GNUNET_YES to get information about all addresses or GNUNET_NO to + * @param all #GNUNET_YES to get information about all addresses or #GNUNET_NO to * get only address currently used * @param infocb callback to call with the addresses, * will callback with address == NULL when done * @param infocb_cls closure for @a infocb - * @return ats performance context + * @return handle to abort the operation */ struct GNUNET_ATS_AddressListHandle * -GNUNET_ATS_performance_list_addresses (struct GNUNET_ATS_PerformanceHandle *handle, +GNUNET_ATS_performance_list_addresses (struct GNUNET_ATS_PerformanceHandle *ph, const struct GNUNET_PeerIdentity *peer, int all, GNUNET_ATS_AddressInformationCallback infocb, @@ -823,10 +455,10 @@ GNUNET_ATS_performance_list_addresses (struct GNUNET_ATS_PerformanceHandle *hand /** * Cancel a pending address listing operation * - * @param handle the `struct GNUNET_ATS_AddressListHandle` handle to cancel + * @param alh the `struct GNUNET_ATS_AddressListHandle` handle to cancel */ void -GNUNET_ATS_performance_list_addresses_cancel (struct GNUNET_ATS_AddressListHandle *handle); +GNUNET_ATS_performance_list_addresses_cancel (struct GNUNET_ATS_AddressListHandle *alh); /** @@ -850,7 +482,7 @@ GNUNET_ATS_performance_done (struct GNUNET_ATS_PerformanceHandle *ph); */ typedef void (*GNUNET_ATS_ReservationCallback) (void *cls, - const struct GNUNET_PeerIdentity * peer, + const struct GNUNET_PeerIdentity *peer, int32_t amount, struct GNUNET_TIME_Relative res_delay); @@ -871,14 +503,16 @@ struct GNUNET_ATS_ReservationContext; * @param amount reserve N bytes for receiving, negative * amounts can be used to undo a (recent) reservation; * @param rcb function to call with the resulting reservation information - * @param rcb_cls closure for info + * @param rcb_cls closure for @a rcb * @return NULL on error * @deprecated will be replaced soon */ struct GNUNET_ATS_ReservationContext * GNUNET_ATS_reserve_bandwidth (struct GNUNET_ATS_PerformanceHandle *ph, - const struct GNUNET_PeerIdentity *peer, int32_t amount, - GNUNET_ATS_ReservationCallback rcb, void *rcb_cls); + const struct GNUNET_PeerIdentity *peer, + int32_t amount, + GNUNET_ATS_ReservationCallback rcb, + void *rcb_cls); /** @@ -889,20 +523,16 @@ GNUNET_ATS_reserve_bandwidth (struct GNUNET_ATS_PerformanceHandle *ph, void GNUNET_ATS_reserve_bandwidth_cancel (struct GNUNET_ATS_ReservationContext *rc); -/** - * Number of preference types supported by ATS - */ -#define GNUNET_ATS_PreferenceCount 3 /** * ATS preference types as array initializer */ -#define GNUNET_ATS_PreferenceType {GNUNET_ATS_PREFERENCE_END, GNUNET_ATS_PREFERENCE_BANDWIDTH, GNUNET_ATS_PREFERENCE_LATENCY} +#define GNUNET_ATS_PreferenceType {GNUNET_ATS_PREFERENCE_BANDWIDTH, GNUNET_ATS_PREFERENCE_LATENCY, GNUNET_ATS_PREFERENCE_END} /** * ATS preference types as string array initializer */ -#define GNUNET_ATS_PreferenceTypeString {"END", "BANDWIDTH", "LATENCY"} +#define GNUNET_ATS_PreferenceTypeString {"BANDWIDTH", "LATENCY", "END" } /** * Enum defining all known preference categories. @@ -910,18 +540,13 @@ GNUNET_ATS_reserve_bandwidth_cancel (struct GNUNET_ATS_ReservationContext *rc); enum GNUNET_ATS_PreferenceKind { - /** - * End of preference list. - */ - GNUNET_ATS_PREFERENCE_END = 0, - /** * Change the peer's bandwidth value (value per byte of bandwidth in * the goal function) to the given amount. The argument is followed * by a double value giving the desired value (can be negative). * Preference changes are forgotten if peers disconnect. */ - GNUNET_ATS_PREFERENCE_BANDWIDTH, + GNUNET_ATS_PREFERENCE_BANDWIDTH = 0, /** * Change the peer's latency value to the given amount. The @@ -930,9 +555,16 @@ enum GNUNET_ATS_PreferenceKind * the inverse of the latency in microseconds (minimum: 1 * microsecond) multiplied by the latency preferences. */ - GNUNET_ATS_PREFERENCE_LATENCY + GNUNET_ATS_PREFERENCE_LATENCY = 1, + + /** + * End of preference list. + */ + GNUNET_ATS_PREFERENCE_END = 2 + }; + /** * Convert a GNUNET_ATS_PreferenceType to a string * @@ -940,20 +572,21 @@ enum GNUNET_ATS_PreferenceKind * @return a string or NULL if invalid */ const char * -GNUNET_ATS_print_preference_type (uint32_t type); +GNUNET_ATS_print_preference_type (enum GNUNET_ATS_PreferenceKind type); /** * Change preferences for the given peer. Preference changes are forgotten if peers * disconnect. * - * @param ph performance handle - * @param peer identifies the peer - * @param ... 0-terminated specification of the desired changes + * @param ph performance handle @param peer identifies the peer + * @param ... #GNUNET_ATS_PREFERENCE_END-terminated specification of the + * desired changes */ void GNUNET_ATS_performance_change_preference (struct GNUNET_ATS_PerformanceHandle *ph, - const struct GNUNET_PeerIdentity *peer, ...); + const struct GNUNET_PeerIdentity *peer, + ...); /** @@ -971,12 +604,16 @@ GNUNET_ATS_performance_change_preference (struct GNUNET_ATS_PerformanceHandle *p * @param ph performance handle * @param scope the time interval this valid for: [now - scope .. now] * @param peer identifies the peer - * @param ... 0-terminated specification of the desired changes + * @param ... #GNUNET_ATS_PREFERENCE_END-terminated specification of the desired changes */ void GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph, - const struct GNUNET_PeerIdentity *peer, - const struct GNUNET_TIME_Relative scope, ...); + const struct GNUNET_PeerIdentity *peer, + const struct GNUNET_TIME_Relative scope, + ...); #endif + +/** @} */ /* end of group */ + /* end of file gnunet-service-transport_ats.h */