gnunet_ats_service.h

Go to the documentation of this file.

/*
   This file is part of GNUnet.
   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 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
   Affero General Public License for more details.
 
   You should have received a copy of the GNU Affero General Public License
   along with this program.  If not, see <http://www.gnu.org/licenses/>.
 
     SPDX-License-Identifier: AGPL3.0-or-later
 */
#ifndef GNUNET_ATS_SERVICE_H
#define GNUNET_ATS_SERVICE_H
 
 
#include "gnunet_constants.h"
#include "gnunet_util_lib.h"
#include "gnunet_hello_lib.h"
 
 
#define GNUNET_ATS_DefaultBandwidth 65536
 
#define GNUNET_ATS_VALUE_UNDEFINED UINT32_MAX
 
#define GNUNET_ATS_VALUE_UNDEFINED_STR "undefined"
 
#define GNUNET_ATS_MaxBandwidth UINT32_MAX
 
#define GNUNET_ATS_MaxBandwidthString "unlimited"
 
 
struct GNUNET_ATS_Properties
{
  struct GNUNET_TIME_Relative delay;
 
  uint32_t utilization_out;
 
  uint32_t utilization_in;
 
  unsigned int distance;
 
  enum GNUNET_NetworkType scope;
};
 
 
struct GNUNET_ATS_PropertiesNBO
{
  uint32_t utilization_out GNUNET_PACKED;
 
  uint32_t utilization_in GNUNET_PACKED;
 
  uint32_t scope GNUNET_PACKED;
 
  uint32_t distance GNUNET_PACKED;
 
  struct GNUNET_TIME_RelativeNBO delay;
};
 
 
/* ********************* LAN Characterization library ************************ */
/* Note: these functions do not really communicate with the ATS service */
 
 
void
GNUNET_ATS_properties_hton (struct GNUNET_ATS_PropertiesNBO *nbo,
                            const struct GNUNET_ATS_Properties *hbo);
 
 
void
GNUNET_ATS_properties_ntoh (struct GNUNET_ATS_Properties *hbo,
                            const struct GNUNET_ATS_PropertiesNBO *nbo);
 
 
/* ********************Connection Suggestion API ***************************** */
 
struct GNUNET_ATS_ConnectivityHandle;
 
struct GNUNET_ATS_ConnectivitySuggestHandle;
 
 
struct GNUNET_ATS_ConnectivityHandle *
GNUNET_ATS_connectivity_init (const struct GNUNET_CONFIGURATION_Handle *cfg);
 
 
void
GNUNET_ATS_connectivity_done (struct GNUNET_ATS_ConnectivityHandle *ch);
 
 
struct GNUNET_ATS_ConnectivitySuggestHandle *
GNUNET_ATS_connectivity_suggest (struct GNUNET_ATS_ConnectivityHandle *ch,
                                 const struct GNUNET_PeerIdentity *peer,
                                 uint32_t strength);
 
 
void
GNUNET_ATS_connectivity_suggest_cancel (struct
                                        GNUNET_ATS_ConnectivitySuggestHandle *sh);
 
 
/* ******************************** Scheduling API ***************************** */
 
struct GNUNET_ATS_SchedulingHandle;
 
struct GNUNET_ATS_Session;
 
 
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);
 
 
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_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh);
 
 
struct GNUNET_ATS_AddressRecord;
 
 
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);
 
 
void
GNUNET_ATS_address_add_session (struct GNUNET_ATS_AddressRecord *ar,
                                struct GNUNET_ATS_Session *session);
 
 
int
GNUNET_ATS_address_del_session (struct GNUNET_ATS_AddressRecord *ar,
                                struct GNUNET_ATS_Session *session);
 
 
void
GNUNET_ATS_address_update (struct GNUNET_ATS_AddressRecord *ar,
                           const struct GNUNET_ATS_Properties *prop);
 
 
void
GNUNET_ATS_address_destroy (struct GNUNET_ATS_AddressRecord *ar);
 
 
/* ******************************** Performance API ***************************** */
 
struct GNUNET_ATS_PerformanceHandle;
 
typedef void
(*GNUNET_ATS_AddressInformationCallback) (void *cls,
                                          const struct
                                          GNUNET_HELLO_Address *address,
                                          int address_active,
                                          struct GNUNET_BANDWIDTH_Value32NBO
                                          bandwidth_out,
                                          struct GNUNET_BANDWIDTH_Value32NBO
                                          bandwidth_in,
                                          const struct
                                          GNUNET_ATS_Properties *prop);
 
 
struct GNUNET_ATS_AddressListHandle;
 
 
struct GNUNET_ATS_PerformanceHandle *
GNUNET_ATS_performance_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
                             GNUNET_ATS_AddressInformationCallback addr_info_cb,
                             void *addr_info_cb_cls);
 
 
struct GNUNET_ATS_AddressListHandle *
GNUNET_ATS_performance_list_addresses (struct GNUNET_ATS_PerformanceHandle *ph,
                                       const struct GNUNET_PeerIdentity *peer,
                                       int all,
                                       GNUNET_ATS_AddressInformationCallback
                                       infocb,
                                       void *infocb_cls);
 
 
void
GNUNET_ATS_performance_list_addresses_cancel (struct
                                              GNUNET_ATS_AddressListHandle *alh);
 
 
void
GNUNET_ATS_performance_done (struct GNUNET_ATS_PerformanceHandle *ph);
 
 
typedef void
(*GNUNET_ATS_ReservationCallback) (void *cls,
                                   const struct GNUNET_PeerIdentity *peer,
                                   int32_t amount,
                                   struct GNUNET_TIME_Relative res_delay);
 
 
struct GNUNET_ATS_ReservationContext;
 
 
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);
 
 
void
GNUNET_ATS_reserve_bandwidth_cancel (struct GNUNET_ATS_ReservationContext *rc);
 
 
#define GNUNET_ATS_PreferenceType { GNUNET_ATS_PREFERENCE_BANDWIDTH, \
                                    GNUNET_ATS_PREFERENCE_LATENCY, \
                                    GNUNET_ATS_PREFERENCE_END }
 
#define GNUNET_ATS_PreferenceTypeString { "BANDWIDTH", "LATENCY", "END" }
 
enum GNUNET_ATS_PreferenceKind
{
  GNUNET_ATS_PREFERENCE_BANDWIDTH = 0,
 
  GNUNET_ATS_PREFERENCE_LATENCY = 1,
 
  GNUNET_ATS_PREFERENCE_END = 2
};
 
 
const char *
GNUNET_ATS_print_preference_type (enum GNUNET_ATS_PreferenceKind type);
 
 
void
GNUNET_ATS_performance_change_preference (struct
                                          GNUNET_ATS_PerformanceHandle *ph,
                                          const struct
                                          GNUNET_PeerIdentity *peer,
                                          ...);
 
 
void
GNUNET_ATS_performance_give_feedback (struct GNUNET_ATS_PerformanceHandle *ph,
                                      const struct GNUNET_PeerIdentity *peer,
                                      const struct GNUNET_TIME_Relative scope,
                                      ...);
 
#endif
  /* end of group */
  /* end of Backbone addition */
 
/* end of file gnunet-service-transport_ats.h */