X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_ats_service.h;h=7ea624f5e272d5541fcd9ce8d7e13feef9c3e964;hb=6e626937fd5133188d2bd06f280a1b889219eef2;hp=7be2e475891ae1516628017a2ad7d7106ea649bd;hpb=21eb8c5325edec855da64c2318590f5f0afa78a8;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_ats_service.h b/src/include/gnunet_ats_service.h index 7be2e4758..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-2015 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,53 +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 } - - -/** - * Types of networks (with separate quotas) we support. - */ -enum GNUNET_ATS_Network_Type -{ - /** - * Category of last resort. - */ - GNUNET_ATS_NET_UNSPECIFIED = 0, - - /** - * Loopback (same host). - */ - GNUNET_ATS_NET_LOOPBACK = 1, - - /** - * Local area network. - */ - GNUNET_ATS_NET_LAN = 2, - - /** - * Wide area network (i.e. Internet) - */ - GNUNET_ATS_NET_WAN = 3, - - /** - * Wireless LAN (i.e. 802.11abgn) - */ - GNUNET_ATS_NET_WLAN = 4, - - /** - * Bluetooth LAN - */ - GNUNET_ATS_NET_BT = 5 -}; - /** * Default bandwidth assigned to a network : 64 KB/s @@ -103,353 +64,244 @@ enum GNUNET_ATS_Network_Type */ #define GNUNET_ATS_MaxBandwidthString "unlimited" -/** - * Number of property types supported by ATS - */ -#define GNUNET_ATS_PropertyCount 11 - /** - * 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; /** - * Actual traffic on this connection from this peer to the other peer. - * Only payload from layers > transport - * - * Unit: [bytes/second] + * Distance on network layer (required for distance-vector routing) + * in hops. Zero for direct connections (i.e. plain TCP/UDP). */ - GNUNET_ATS_UTILIZATION_PAYLOAD_OUT, + unsigned int distance; /** - * Actual traffic on this connection from the other peer to this peer. - * Only payload from layers > transport - * - * Unit: [bytes/second] + * Which network scope does the respective address belong to? + * This property does not change. */ - GNUNET_ATS_UTILIZATION_PAYLOAD_IN, + enum GNUNET_NetworkType scope; + +}; - /** - * Is this address located in WAN, LAN or a loopback address - * Value is element of GNUNET_ATS_Network_Type - */ - GNUNET_ATS_NETWORK_TYPE, + +/** + * ATS performance characteristics for an address in + * network byte order (for IPC). + */ +struct GNUNET_ATS_PropertiesNBO +{ /** - * Delay - * Time between when the time packet is sent and the packet arrives - * - * Unit: [microseconds] - * - * Examples: + * Actual traffic on this connection from this peer to the other peer. + * Includes transport overhead. * - * LAN : 1 - * WLAN : 2 - * Dialup: 500 + * Unit: [bytes/second] */ - GNUNET_ATS_QUALITY_NET_DELAY, + uint32_t utilization_out GNUNET_PACKED; /** - * Distance on network layer (required for distance-vector routing). + * Actual traffic on this connection from the other peer to this peer. + * Includes transport overhead. * - * Unit: [DV-hops] + * Unit: [bytes/second] */ - GNUNET_ATS_QUALITY_NET_DISTANCE, + uint32_t utilization_in GNUNET_PACKED; /** - * 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] + * Which network scope does the respective address belong to? + * This property does not change. */ - GNUNET_ATS_COST_WAN, + uint32_t scope GNUNET_PACKED; /** - * 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] + * Distance on network layer (required for distance-vector routing) + * in hops. Zero for direct connections (i.e. plain TCP/UDP). */ - GNUNET_ATS_COST_LAN, + uint32_t distance GNUNET_PACKED; /** - * 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] + * Delay. Time between when the time packet is sent and the packet + * arrives. FOREVER if we did not measure yet. */ - GNUNET_ATS_COST_WLAN + struct GNUNET_TIME_RelativeNBO delay; }; -/** - * Number of ATS quality properties - */ -#define GNUNET_ATS_QualityPropertiesCount 2 -/** - * ATS quality properties as array initializer - */ -#define GNUNET_ATS_QualityProperties { GNUNET_ATS_QUALITY_NET_DELAY, GNUNET_ATS_QUALITY_NET_DISTANCE } +/* ********************* LAN Characterization library ************************ */ +/* Note: these functions do not really communicate with the ATS service */ + /** - * ATS quality properties as string array initializer + * Convert ATS properties from host to network byte order. + * + * @param nbo[OUT] value written + * @param hbo value read */ -#define GNUNET_ATS_QualityPropertiesString {"Delay", "Distance"} +void +GNUNET_ATS_properties_hton (struct GNUNET_ATS_PropertiesNBO *nbo, + const struct GNUNET_ATS_Properties *hbo); -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 | - * +-----------+ | | +---------+ - * +---+ + * Convert ATS properties from network to host byte order. * - * 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 hbo[OUT] value written + * @param nbo value read */ -struct GNUNET_ATS_Information -{ - /** - * ATS property type, in network byte order. - */ - uint32_t type GNUNET_PACKED; +void +GNUNET_ATS_properties_ntoh (struct GNUNET_ATS_Properties *hbo, + const struct GNUNET_ATS_PropertiesNBO *nbo); - /** - * ATS property value, in network byte order. - */ - uint32_t value GNUNET_PACKED; -}; -GNUNET_NETWORK_STRUCT_END -/* ******************************** Scheduling API ***************************** */ -/** - * Handle to the ATS subsystem for bandwidth/transport scheduling information. - */ -struct GNUNET_ATS_SchedulingHandle; +/* ********************Connection Suggestion API ***************************** */ /** - * Handle for address suggestion requests + * Handle to the ATS subsystem for making suggestions about + * connections the peer would like to have. */ -struct GNUNET_ATS_SuggestHandle; +struct GNUNET_ATS_ConnectivityHandle; /** - * Opaque session handle, defined by plugins. Contents not known to ATS. + * Handle for address suggestion requests. */ -struct Session; +struct GNUNET_ATS_ConnectivitySuggestHandle; + /** - * Signature of a function called by ATS with the current bandwidth - * and address preferences as determined by ATS. + * Initialize the ATS connectivity suggestion client handle. * - * 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 - * - * @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 cfg configuration to use + * @return ats connectivity handle, NULL on error */ -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); +struct GNUNET_ATS_ConnectivityHandle * +GNUNET_ATS_connectivity_init (const struct GNUNET_CONFIGURATION_Handle *cfg); /** - * Initialize the ATS subsystem. + * Shutdown ATS connectivity suggestion client. * - * @param cfg configuration to use - * @param suggest_cb notification to call whenever the suggestation changed - * @param suggest_cb_cls closure for @a suggest_cb - * @return ats context + * @param ch handle to destroy */ -struct GNUNET_ATS_SchedulingHandle * -GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg, - GNUNET_ATS_AddressSuggestionCallback suggest_cb, void *suggest_cb_cls); +void +GNUNET_ATS_connectivity_done (struct GNUNET_ATS_ConnectivityHandle *ch); /** - * Client is done with ATS scheduling, release resources. + * We would like to establish a new connection with a peer. ATS + * should suggest a good address to begin with. * - * @param sh handle to release + * @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 */ -void -GNUNET_ATS_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh); +struct GNUNET_ATS_ConnectivitySuggestHandle * +GNUNET_ATS_connectivity_suggest (struct GNUNET_ATS_ConnectivityHandle *ch, + const struct GNUNET_PeerIdentity *peer, + uint32_t strength); /** - * We would like to reset the address suggestion block time for this - * peer. + * We no longer care about being connected to a peer. * * @param sh handle - * @param peer identity of the peer we want to reset */ void -GNUNET_ATS_reset_backoff (struct GNUNET_ATS_SchedulingHandle *sh, - const struct GNUNET_PeerIdentity *peer); +GNUNET_ATS_connectivity_suggest_cancel (struct GNUNET_ATS_ConnectivitySuggestHandle *sh); + +/* ******************************** Scheduling API ***************************** */ /** - * We would like to establish a new connection with a peer. ATS - * should suggest a good address to begin with. - * - * @param sh handle - * @param peer identity of the peer we need an address for - * @return suggestion handle + * Handle to the ATS subsystem for bandwidth/transport scheduling information. */ -struct GNUNET_ATS_SuggestHandle * -GNUNET_ATS_suggest_address (struct GNUNET_ATS_SchedulingHandle *sh, - const struct GNUNET_PeerIdentity *peer); - +struct GNUNET_ATS_SchedulingHandle; /** - * We want to cancel ATS suggesting addresses for a peer. - * - * @param sh handle - * @param peer identity of the peer + * Opaque session handle, defined by plugins. Contents not known to ATS. */ -void -GNUNET_ATS_suggest_address_cancel (struct GNUNET_ATS_SchedulingHandle *sh, - const struct GNUNET_PeerIdentity *peer); +struct GNUNET_ATS_Session; /** - * Convert a ATS property to a string + * Signature of a function called by ATS with the current bandwidth + * 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 type the property type - * @return a string or NULL if invalid + * @param cls closure + * @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 */ -const char * -GNUNET_ATS_print_property_type (enum GNUNET_ATS_Property type); +typedef void +(*GNUNET_ATS_AddressSuggestionCallback) (void *cls, + 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); /** - * Convert a `enum GNUNET_ATS_Network_Type` to a string + * Initialize the ATS scheduling subsystem. * - * @param net the network type - * @return a string or NULL if invalid + * @param cfg configuration to use + * @param suggest_cb notification to call whenever the suggestation changed + * @param suggest_cb_cls closure for @a suggest_cb + * @return ats context */ -const char * -GNUNET_ATS_print_network_type (enum GNUNET_ATS_Network_Type net); +struct GNUNET_ATS_SchedulingHandle * +GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg, + GNUNET_ATS_AddressSuggestionCallback suggest_cb, + void *suggest_cb_cls); /** - * Returns where the address is located: LAN or WAN or ... + * Client is done with ATS scheduling, release resources. * - * @param sh the `struct GNUNET_ATS_SchedulingHandle` handle - * @param addr address - * @param addrlen address length - * @return location as `struct GNUNET_ATS_Information` + * @param sh handle to release */ -struct GNUNET_ATS_Information -GNUNET_ATS_address_get_type (struct GNUNET_ATS_SchedulingHandle *sh, - const struct sockaddr *addr, - socklen_t addrlen); +void +GNUNET_ATS_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh); /** - * 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 + * Handle used within ATS to track an address. */ -int -GNUNET_ATS_session_known (struct GNUNET_ATS_SchedulingHandle *sh, - const struct GNUNET_HELLO_Address *address, - struct Session *session); +struct GNUNET_ATS_AddressRecord; /** @@ -458,71 +310,74 @@ GNUNET_ATS_session_known (struct GNUNET_ATS_SchedulingHandle *sh, * * @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 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) */ -int +struct GNUNET_ATS_AddressRecord * 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); + struct GNUNET_ATS_Session *session, + const struct GNUNET_ATS_Properties *prop); /** - * 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. + * An address was used to initiate a session. * - * @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 + * @param ar address record to update information for + * @param session session handle */ -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); +void +GNUNET_ATS_address_add_session (struct GNUNET_ATS_AddressRecord *ar, + struct GNUNET_ATS_Session *session); /** - * An address is now in use or not used any more. + * 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 ar address record to update information for * @param session session handle - * @param in_use #GNUNET_YES if this address is now used, #GNUNET_NO - * if address is not used any more + * @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 */ -void -GNUNET_ATS_address_in_use (struct GNUNET_ATS_SchedulingHandle *sh, - const struct GNUNET_HELLO_Address *address, - struct Session *session, - int in_use); +int +GNUNET_ATS_address_del_session (struct GNUNET_ATS_AddressRecord *ar, + struct GNUNET_ATS_Session *session); /** - * An address got destroyed, stop including it as a valid address. + * 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 (@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. * - * If a session is given, only the session will be removed, if no session is - * given the full address will be deleted. + * @param ar address record to update information for + * @param prop performance data for the address + */ +void +GNUNET_ATS_address_update (struct GNUNET_ATS_AddressRecord *ar, + const struct GNUNET_ATS_Properties *prop); + + +/** + * 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 ***************************** */ @@ -536,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, @@ -552,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); /** @@ -577,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, @@ -601,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); /** @@ -628,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); @@ -649,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); /** @@ -667,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. @@ -688,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 @@ -708,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 * @@ -718,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, + ...); /** @@ -749,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 */