X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_ats_service.h;h=7ea624f5e272d5541fcd9ce8d7e13feef9c3e964;hb=6e626937fd5133188d2bd06f280a1b889219eef2;hp=c036a536b2cda7cb6551d5fb2921224b94489871;hpb=ad0777dcb1709b8d46d141e2cb8900dc9c91329d;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_ats_service.h b/src/include/gnunet_ats_service.h index c036a536b..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. - Copyright (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,48 +38,6 @@ #include "gnunet_util_lib.h" #include "gnunet_hello_lib.h" -/** - * 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 - -/** - * Number of network types supported by ATS - */ -#define GNUNET_ATS_NetworkTypeCount 6 - -}; - /** * Default bandwidth assigned to a network : 64 KB/s @@ -105,6 +71,12 @@ enum GNUNET_ATS_Network_Type struct GNUNET_ATS_Properties { + /** + * Delay. Time between when the time packet is sent and the packet + * arrives. FOREVER if we did not measure yet. + */ + struct GNUNET_TIME_Relative delay; + /** * Actual traffic on this connection from this peer to the other peer. * Includes transport overhead. @@ -121,12 +93,6 @@ struct GNUNET_ATS_Properties */ uint32_t utilization_in; - /** - * Which network scope does the respective address belong to? - * This property does not change. - */ - enum GNUNET_ATS_Network_Type scope; - /** * Distance on network layer (required for distance-vector routing) * in hops. Zero for direct connections (i.e. plain TCP/UDP). @@ -134,10 +100,10 @@ struct GNUNET_ATS_Properties unsigned int distance; /** - * Delay. Time between when the time packet is sent and the packet - * arrives. FOREVER if we did not measure yet. + * Which network scope does the respective address belong to? + * This property does not change. */ - struct GNUNET_TIME_Relative delay; + enum GNUNET_NetworkType scope; }; @@ -214,55 +180,6 @@ GNUNET_ATS_properties_ntoh (struct GNUNET_ATS_Properties *hbo, -/** - * Convert a `enum GNUNET_ATS_Network_Type` to a string - * - * @param net the network type - * @return a string or NULL if invalid - */ -const char * -GNUNET_ATS_print_network_type (enum GNUNET_ATS_Network_Type net); - - -/** - * Handle for the LAN Characterization library. - */ -struct GNUNET_ATS_InterfaceScanner; - - -/** - * Returns where the address is located: loopback, LAN or WAN. - * - * @param is handle from #GNUNET_ATS_interface_scanner_init() - * @param addr address - * @param addrlen address length - * @return type of the network the address belongs to - */ -enum GNUNET_ATS_Network_Type -GNUNET_ATS_scanner_address_get_type (struct GNUNET_ATS_InterfaceScanner *is, - const struct sockaddr *addr, - socklen_t addrlen); - - -/** - * Initialize the ATS address characterization client handle. - * - * @return scanner handle, NULL on error - */ -struct GNUNET_ATS_InterfaceScanner * -GNUNET_ATS_scanner_init (void); - - -/** - * Terminate interface scanner. - * - * @param is scanner we are done with - */ -void -GNUNET_ATS_scanner_done (struct GNUNET_ATS_InterfaceScanner *is); - - - /* ********************Connection Suggestion API ***************************** */ /** @@ -302,12 +219,13 @@ GNUNET_ATS_connectivity_done (struct GNUNET_ATS_ConnectivityHandle *ch); * * @param ch handle * @param peer identity of the peer we need an address for - * TODO: add argument to allow client to express 'strength's of request + * @param strength how urgent is the need for such a suggestion * @return suggestion handle, NULL if request is already pending - */ + */ struct GNUNET_ATS_ConnectivitySuggestHandle * GNUNET_ATS_connectivity_suggest (struct GNUNET_ATS_ConnectivityHandle *ch, - const struct GNUNET_PeerIdentity *peer); + const struct GNUNET_PeerIdentity *peer, + uint32_t strength); /** @@ -328,13 +246,15 @@ struct GNUNET_ATS_SchedulingHandle; /** * Opaque session handle, defined by plugins. Contents not known to ATS. - * FIXME: This violates our naming conventions. */ -struct Session; +struct GNUNET_ATS_Session; + /** * Signature of a function called by ATS with the current bandwidth - * and address preferences as determined by ATS. + * 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 peer for which we suggest an address, NULL if ATS connection died @@ -350,7 +270,7 @@ typedef void (*GNUNET_ATS_AddressSuggestionCallback) (void *cls, const struct GNUNET_PeerIdentity *peer, const struct GNUNET_HELLO_Address *address, - struct Session *session, + struct GNUNET_ATS_Session *session, struct GNUNET_BANDWIDTH_Value32NBO bandwidth_out, struct GNUNET_BANDWIDTH_Value32NBO bandwidth_in); @@ -399,7 +319,7 @@ struct GNUNET_ATS_AddressRecord; struct GNUNET_ATS_AddressRecord * GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh, const struct GNUNET_HELLO_Address *address, - struct Session *session, + struct GNUNET_ATS_Session *session, const struct GNUNET_ATS_Properties *prop); @@ -411,13 +331,13 @@ GNUNET_ATS_address_add (struct GNUNET_ATS_SchedulingHandle *sh, */ void GNUNET_ATS_address_add_session (struct GNUNET_ATS_AddressRecord *ar, - struct Session *session); + struct GNUNET_ATS_Session *session); /** - * A session was destroyed, disassociate it from the - * given address record. If this was an incoming - * addess, destroy the address as well. + * A @a session was destroyed, disassociate it from the given address + * record. If this was an incoming addess, destroys the address as + * well. * * @param ar address record to update information for * @param session session handle @@ -428,7 +348,7 @@ GNUNET_ATS_address_add_session (struct GNUNET_ATS_AddressRecord *ar, */ int GNUNET_ATS_address_del_session (struct GNUNET_ATS_AddressRecord *ar, - struct Session *session); + struct GNUNET_ATS_Session *session); /** @@ -515,7 +435,7 @@ GNUNET_ATS_performance_init (const struct GNUNET_CONFIGURATION_Handle *cfg, /** * 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 * get only address currently used @@ -525,7 +445,7 @@ GNUNET_ATS_performance_init (const struct GNUNET_CONFIGURATION_Handle *cfg, * @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, @@ -535,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); /** @@ -604,11 +524,6 @@ 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 */ @@ -698,4 +613,7 @@ GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph, ...); #endif + +/** @} */ /* end of group */ + /* end of file gnunet-service-transport_ats.h */