/**
* Handle for address suggestion requests
- *
*/
struct GNUNET_ATS_SuggestHandle;
* 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
+ *
* @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 'ats'
+ * @param ats_count number of performance records in @a ats
*/
typedef void
(*GNUNET_ATS_AddressSuggestionCallback) (void *cls,
- const struct GNUNET_HELLO_Address * address, struct Session * session,
+ 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_ATS_Information *ats, uint32_t ats_count);
+
/**
* Initialize the ATS subsystem.
*
* @param cfg configuration to use
* @param suggest_cb notification to call whenever the suggestation changed
- * @param suggest_cb_cls closure for 'suggest_cb'
+ * @param suggest_cb_cls closure for @a suggest_cb
* @return ats context
*/
struct GNUNET_ATS_SchedulingHandle *
GNUNET_ATS_scheduling_init (const struct GNUNET_CONFIGURATION_Handle *cfg,
GNUNET_ATS_AddressSuggestionCallback suggest_cb, void *suggest_cb_cls);
+
/**
* Client is done with ATS scheduling, release resources.
*
void
GNUNET_ATS_scheduling_done (struct GNUNET_ATS_SchedulingHandle *sh);
+
/**
* We would like to reset the address suggestion block time for this
* peer
*/
void
GNUNET_ATS_reset_backoff (struct GNUNET_ATS_SchedulingHandle *sh,
- const struct GNUNET_PeerIdentity *peer);
+ const struct GNUNET_PeerIdentity *peer);
+
/**
* We would like to establish a new connection with a peer. ATS
*
* @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
*/
struct GNUNET_ATS_SuggestHandle *
GNUNET_ATS_suggest_address (struct GNUNET_ATS_SchedulingHandle *sh,
- const struct GNUNET_PeerIdentity *peer);
+ const struct GNUNET_PeerIdentity *peer,
+ GNUNET_ATS_AddressSuggestionCallback cont,
+ void *cont_cls);
+
/**
* We want to cancel ATS suggesting addresses for a peer.
*/
void
GNUNET_ATS_suggest_address_cancel (struct GNUNET_ATS_SchedulingHandle *sh,
- const struct GNUNET_PeerIdentity *peer);
+ const struct GNUNET_PeerIdentity *peer);
+
/**
* Convert a ATS property to a string
const char *
GNUNET_ATS_print_property_type (uint32_t type);
+
/**
* Convert a GNUNET_ATS_NetworkType to a string
*
const char *
GNUNET_ATS_print_network_type (uint32_t net);
+
/**
* Returns where the address is located: LAN or WAN or ...
- * @param sh the GNUNET_ATS_SchedulingHandle handle
+ * @param sh the `struct GNUNET_ATS_SchedulingHandle` handle
* @param addr address
* @param addrlen address length
- * @return location as GNUNET_ATS_Information
+ * @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);
+ 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
+ * @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);
+ const struct GNUNET_HELLO_Address *address,
+ struct Session *session);
+
/**
* We have a new address ATS should know. Addresses have to be added with this
* @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 'ats'
+ * @param ats_count number of performance records in @a ats
*/
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);
+ const struct GNUNET_HELLO_Address *address,
+ struct Session *session,
+ const struct GNUNET_ATS_Information *ats,
+ uint32_t ats_count);
+
/**
* We have updated performance statistics for a given address. Note
* @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 'ats'
- * @return GNUNET_OK or GNUNET_SYSERR
+ * @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);
+ 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
+ * @param in_use #GNUNET_YES if this address is now used, #GNUNET_NO
* if address is not used any more
*/
void
GNUNET_ATS_address_in_use (struct GNUNET_ATS_SchedulingHandle *sh,
- const struct GNUNET_HELLO_Address *address, struct Session *session,
- int in_use);
+ const struct GNUNET_HELLO_Address *address,
+ struct Session *session,
+ int in_use);
+
/**
- * A session got destroyed, stop including it as a valid address.
+ * 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.
*
* @param sh handle
* @param address the address
*/
void
GNUNET_ATS_address_destroyed (struct GNUNET_ATS_SchedulingHandle *sh,
- const struct GNUNET_HELLO_Address *address, struct Session *session);
+ const struct GNUNET_HELLO_Address *address,
+ struct Session *session);
+
/* ******************************** Performance API ***************************** */
* Signature of a function that is called with QoS information about an address.
*
* @param cls closure
- * @param address the address
+ * @param address the address, NULL if ATS service was disconnected
* @param address_active is this address actively used to maintain a connection
- * to a peer
+ to a peer
* @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 'ats'
+ * @param ats_count number of performance records in @a ats
*/
typedef void
(*GNUNET_ATS_AddressInformationCallback) (void *cls,
- const struct GNUNET_HELLO_Address *address, int address_active,
+ 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_Information *ats, uint32_t ats_count);
+ const struct GNUNET_ATS_Information *ats,
+ uint32_t ats_count);
/**
* Handle for an address listing operation
*/
struct GNUNET_ATS_AddressListHandle;
+
/**
* Get handle to access performance API of the ATS subsystem.
*
* @param cfg configuration to use
* @param addr_info_cb callback called when performance characteristics for
* an address change
- * @param addr_info_cb_cls closure for infocb
+ * @param addr_info_cb_cls closure for @a addr_info_cb
* @return ats performance context
*/
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);
+ GNUNET_ATS_AddressInformationCallback addr_info_cb,
+ void *addr_info_cb_cls);
+
/**
* Get information about addresses known to the ATS subsystem.
const struct GNUNET_PeerIdentity *peer, int all,
GNUNET_ATS_AddressInformationCallback infocb, void *infocb_cls);
+
/**
* Cancel a pending address listing operation
*
- * @param handle the GNUNET_ATS_AddressListHandle handle to cancel
+ * @param handle 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 *handle);
+
/**
* Client is done using the ATS performance subsystem, release resources.
void
GNUNET_ATS_performance_done (struct GNUNET_ATS_PerformanceHandle *ph);
+
/**
* Function called with reservation result.
*
const struct GNUNET_PeerIdentity * peer, int32_t amount,
struct GNUNET_TIME_Relative res_delay);
+
/**
* Context that can be used to cancel a peer information request.
*/
struct GNUNET_ATS_ReservationContext;
+
/**
* Reserve inbound bandwidth from the given peer. ATS will look at
* the current amount of traffic we receive from the peer and ensure
const struct GNUNET_PeerIdentity *peer, int32_t amount,
GNUNET_ATS_ReservationCallback rcb, void *rcb_cls);
+
/**
* Cancel request for reserving bandwidth.
*
const char *
GNUNET_ATS_print_preference_type (uint32_t type);
+
/**
* Change preferences for the given peer. Preference changes are forgotten if peers
* disconnect.
* @param ... 0-terminated specification of the desired changes
*/
void
-GNUNET_ATS_performance_change_preference (
- struct GNUNET_ATS_PerformanceHandle *ph,
- const struct GNUNET_PeerIdentity *peer, ...);
+GNUNET_ATS_performance_change_preference (struct GNUNET_ATS_PerformanceHandle *ph,
+ const struct GNUNET_PeerIdentity *peer, ...);
+
/**
* Application feedback on how good preference requirements are fulfilled
projects / oweals / gnunet.git / blobdiff