X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_transport_service.h;h=564b8da248c00810532205749b5bd398324a5b36;hb=c95ddb3eac0292511af734768441444098b90be9;hp=57bdecd17c33a47f1d86420adb2c02c7d1abbe77;hpb=541caf3dec54aaee621fed935e667f9ee423ef31;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_transport_service.h b/src/include/gnunet_transport_service.h index 57bdecd17..564b8da24 100644 --- a/src/include/gnunet_transport_service.h +++ b/src/include/gnunet_transport_service.h @@ -1,10 +1,10 @@ /* This file is part of GNUnet. - (C) 2009 Christian Grothoff (and other contributing authors) + (C) 2009, 2010, 2011 Christian Grothoff (and other contributing authors) 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 2, or (at your + by the Free Software Foundation; either version 3, or (at your option) any later version. GNUnet is distributed in the hope that it will be useful, but @@ -35,27 +35,23 @@ extern "C" #endif #endif -#include "gnunet_bandwidth_lib.h" -#include "gnunet_configuration_lib.h" -#include "gnunet_crypto_lib.h" -#include "gnunet_connection_lib.h" -#include "gnunet_scheduler_lib.h" -#include "gnunet_time_lib.h" +#include "gnunet_util_lib.h" +#include "gnunet_ats_service.h" /** * Version number of the transport API. */ #define GNUNET_TRANSPORT_VERSION 0x00000000 + /** * Function called by the transport for each received message. * * @param cls closure * @param peer (claimed) identity of the other peer * @param message the message - * @param latency estimated latency for communicating with the - * given peer (round-trip) - * @param distance in overlay hops, as given by transport plugin + * @param ats performance data + * @param ats_count number of entries in ats */ typedef void (*GNUNET_TRANSPORT_ReceiveCallback) (void *cls, const struct @@ -63,9 +59,9 @@ typedef void (*GNUNET_TRANSPORT_ReceiveCallback) (void *cls, const struct GNUNET_MessageHeader * message, - struct GNUNET_TIME_Relative - latency, - uint32_t distance); + const struct + GNUNET_ATS_Information * ats, + uint32_t ats_count); /** @@ -80,15 +76,15 @@ struct GNUNET_TRANSPORT_Handle; * * @param cls closure * @param peer the peer that connected - * @param latency estimated latency for communicating with the - * given peer (round-trip) - * @param distance in overlay hops, as given by transport plugin + * @param ats performance data + * @param ats_count number of entries in ats (excluding 0-termination) */ -typedef void - (*GNUNET_TRANSPORT_NotifyConnect) (void *cls, - const struct GNUNET_PeerIdentity * peer, - struct GNUNET_TIME_Relative latency, - uint32_t distance); +typedef void (*GNUNET_TRANSPORT_NotifyConnect) (void *cls, + const struct GNUNET_PeerIdentity + * peer, + const struct + GNUNET_ATS_Information * ats, + uint32_t ats_count); /** * Function called to notify transport users that another @@ -97,47 +93,60 @@ typedef void * @param cls closure * @param peer the peer that disconnected */ -typedef void - (*GNUNET_TRANSPORT_NotifyDisconnect) (void *cls, - const struct GNUNET_PeerIdentity * - peer); +typedef void (*GNUNET_TRANSPORT_NotifyDisconnect) (void *cls, + const struct + GNUNET_PeerIdentity * peer); + + +/** + * Function to call with a textual representation of an address. + * This function will be called several times with different possible + * textual representations, and a last time with NULL to signal the end + * of the iteration. + * + * @param cls closure + * @param address NULL on error or end of iteration, + * otherwise 0-terminated printable UTF-8 string + */ +typedef void (*GNUNET_TRANSPORT_AddressToStringCallback) (void *cls, + const char *address); /** - * Function to call with a human-readable format of an address + * Function to call with a binary format of an address * * @param cls closure - * @param address NULL on error, otherwise 0-terminated printable UTF-8 string + * @param peer peer this update is about (never NULL) + * @param address address, NULL for disconnect notification in monitor mode */ -typedef void -(*GNUNET_TRANSPORT_AddressLookUpCallback) (void *cls, - const char *address); +typedef void (*GNUNET_TRANSPORT_PeerIterateCallback) (void *cls, + const struct + GNUNET_PeerIdentity * + peer, + const struct + GNUNET_HELLO_Address * + address); /** * Connect to the transport service. Note that the connection may * complete (or fail) asynchronously. * - * @param sched scheduler to use * @param cfg configuration to use + * @param self our own identity (API should check that it matches + * the identity found by transport), or NULL (no check) * @param cls closure for the callbacks * @param rec receive function to call * @param nc function to call on connect events * @param nd function to call on disconnect events * @return NULL on error */ -struct GNUNET_TRANSPORT_Handle *GNUNET_TRANSPORT_connect (struct - GNUNET_SCHEDULER_Handle - *sched, - const struct - GNUNET_CONFIGURATION_Handle - *cfg, void *cls, - GNUNET_TRANSPORT_ReceiveCallback - rec, - GNUNET_TRANSPORT_NotifyConnect - nc, - GNUNET_TRANSPORT_NotifyDisconnect - nd); +struct GNUNET_TRANSPORT_Handle * +GNUNET_TRANSPORT_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, + const struct GNUNET_PeerIdentity *self, void *cls, + GNUNET_TRANSPORT_ReceiveCallback rec, + GNUNET_TRANSPORT_NotifyConnect nc, + GNUNET_TRANSPORT_NotifyDisconnect nd); /** @@ -145,30 +154,20 @@ struct GNUNET_TRANSPORT_Handle *GNUNET_TRANSPORT_connect (struct * * @param handle handle returned from connect */ -void GNUNET_TRANSPORT_disconnect (struct GNUNET_TRANSPORT_Handle *handle); +void +GNUNET_TRANSPORT_disconnect (struct GNUNET_TRANSPORT_Handle *handle); /** - * Set the share of incoming/outgoing bandwidth for the given - * peer to the specified amount. + * Ask the transport service to establish a connection to + * the given peer. * * @param handle connection to transport service - * @param target who's bandwidth quota is being changed - * @param quota_in incoming bandwidth quota - * @param quota_out outgoing bandwidth quota - * @param timeout how long to wait until signaling failure if - * we can not communicate the quota change - * @param cont continuation to call when done, will be called - * either with reason "TIMEOUT" or with reason "PREREQ_DONE" - * @param cont_cls closure for continuation + * @param target who we should try to connect to */ void -GNUNET_TRANSPORT_set_quota (struct GNUNET_TRANSPORT_Handle *handle, - const struct GNUNET_PeerIdentity *target, - struct GNUNET_BANDWIDTH_Value32NBO quota_in, - struct GNUNET_BANDWIDTH_Value32NBO quota_out, - struct GNUNET_TIME_Relative timeout, - GNUNET_SCHEDULER_Task cont, void *cont_cls); +GNUNET_TRANSPORT_try_connect (struct GNUNET_TRANSPORT_Handle *handle, + const struct GNUNET_PeerIdentity *target); /** @@ -186,7 +185,7 @@ struct GNUNET_TRANSPORT_TransmitHandle; * @param handle connection to transport service * @param target who should receive the message * @param size how big is the message we want to transmit? - * @param priority how important is the message? + * @param priority how important is the message? @deprecated - remove? * @param timeout after how long should we give up (and call * notify with buf NULL and size 0)? * @param notify function to call when we are ready to @@ -196,27 +195,24 @@ struct GNUNET_TRANSPORT_TransmitHandle; * non-NULL if the notify callback was queued (can be used to cancel * using GNUNET_TRANSPORT_notify_transmit_ready_cancel) */ -struct GNUNET_TRANSPORT_TransmitHandle - *GNUNET_TRANSPORT_notify_transmit_ready (struct GNUNET_TRANSPORT_Handle - *handle, - const struct GNUNET_PeerIdentity - *target, size_t size, - uint32_t priority, - struct GNUNET_TIME_Relative - timeout, - GNUNET_CONNECTION_TransmitReadyNotify - notify, void *notify_cls); +struct GNUNET_TRANSPORT_TransmitHandle * +GNUNET_TRANSPORT_notify_transmit_ready (struct GNUNET_TRANSPORT_Handle *handle, + const struct GNUNET_PeerIdentity + *target, size_t size, uint32_t priority, + struct GNUNET_TIME_Relative timeout, + GNUNET_CONNECTION_TransmitReadyNotify + notify, void *notify_cls); /** * Cancel the specified transmission-ready notification. * - * @param h handle of the transmission notification request to cancel + * @param th handle of the transmission notification request to cancel */ void GNUNET_TRANSPORT_notify_transmit_ready_cancel (struct GNUNET_TRANSPORT_TransmitHandle - *h); + *th); @@ -227,8 +223,16 @@ GNUNET_TRANSPORT_notify_transmit_ready_cancel (struct * @param cls closure * @param hello our updated HELLO */ -typedef void (*GNUNET_TRANSPORT_HelloUpdateCallback)(void *cls, - const struct GNUNET_MessageHeader *hello); +typedef void (*GNUNET_TRANSPORT_HelloUpdateCallback) (void *cls, + const struct + GNUNET_MessageHeader * + hello); + + +/** + * Handle to cancel a 'GNUNET_TRANSPORT_get_hello' operation. + */ +struct GNUNET_TRANSPORT_GetHelloHandle; /** @@ -237,8 +241,9 @@ typedef void (*GNUNET_TRANSPORT_HelloUpdateCallback)(void *cls, * @param handle connection to transport service * @param rec function to call with the HELLO * @param rec_cls closure for rec + * @return handle to cancel the operation */ -void +struct GNUNET_TRANSPORT_GetHelloHandle * GNUNET_TRANSPORT_get_hello (struct GNUNET_TRANSPORT_Handle *handle, GNUNET_TRANSPORT_HelloUpdateCallback rec, void *rec_cls); @@ -247,55 +252,104 @@ GNUNET_TRANSPORT_get_hello (struct GNUNET_TRANSPORT_Handle *handle, /** * Stop receiving updates about changes to our HELLO message. * - * @param handle connection to transport service - * @param rec function previously registered to be called with the HELLOs - * @param rec_cls closure for rec + * @param ghh handle returned from 'GNUNET_TRANSPORT_get_hello') */ void -GNUNET_TRANSPORT_get_hello_cancel (struct GNUNET_TRANSPORT_Handle *handle, - GNUNET_TRANSPORT_HelloUpdateCallback rec, - void *rec_cls); +GNUNET_TRANSPORT_get_hello_cancel (struct GNUNET_TRANSPORT_GetHelloHandle *ghh); /** * Offer the transport service the HELLO of another peer. Note that * the transport service may just ignore this message if the HELLO is - * malformed or useless due to our local configuration. If the HELLO - * is working, we should add it to PEERINFO. + * malformed or useless due to our local configuration. * * @param handle connection to transport service * @param hello the hello message + * @param cont continuation to call when HELLO has been sent + * @param cls closure for continuation */ void GNUNET_TRANSPORT_offer_hello (struct GNUNET_TRANSPORT_Handle *handle, - const struct GNUNET_MessageHeader *hello); + const struct GNUNET_MessageHeader *hello, + GNUNET_SCHEDULER_Task cont, void *cls); + + +/** + * Handle to cancel a pending address lookup. + */ +struct GNUNET_TRANSPORT_AddressToStringContext; /** * Convert a binary address into a human readable address. * - * @param sched scheduler to use * @param cfg configuration to use * @param address address to convert (binary format) - * @param addressLen number of bytes in address - * @param numeric should (IP) addresses be displayed in numeric form + * @param numeric should (IP) addresses be displayed in numeric form * (otherwise do reverse DNS lookup) - * @param nameTrans name of the transport to which the address belongs * @param timeout how long is the lookup allowed to take at most * @param aluc function to call with the results * @param aluc_cls closure for aluc + * @return handle to cancel the operation, NULL on error + */ +struct GNUNET_TRANSPORT_AddressToStringContext * +GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle + *cfg, + const struct GNUNET_HELLO_Address *address, + int numeric, + struct GNUNET_TIME_Relative timeout, + GNUNET_TRANSPORT_AddressToStringCallback + aluc, void *aluc_cls); + + +/** + * Cancel request for address conversion. + * + * @param alc handle for the request to cancel */ void -GNUNET_TRANSPORT_address_lookup (struct GNUNET_SCHEDULER_Handle *sched, - const struct GNUNET_CONFIGURATION_Handle *cfg, - const char * address, - size_t addressLen, - int numeric, - const char * nameTrans, - struct GNUNET_TIME_Relative timeout, - GNUNET_TRANSPORT_AddressLookUpCallback aluc, - void *aluc_cls); +GNUNET_TRANSPORT_address_to_string_cancel (struct + GNUNET_TRANSPORT_AddressToStringContext + *alc); + +/** + * Return all the known addresses for a specific peer or all peers. + * Returns continuously all address if one_shot is set to GNUNET_NO + * + * CHANGE: Returns the address(es) that we are currently using for this + * peer. Upon completion, the 'AddressLookUpCallback' is called one more + * time with 'NULL' for the address and the peer. After this, the operation must no + * longer be explicitly cancelled. + * + * @param cfg configuration to use + * @param peer peer identity to look up the addresses of, CHANGE: allow NULL for all (connected) peers + * @param one_shot GNUNET_YES to return the current state and then end (with NULL+NULL), + * GNUNET_NO to monitor the set of addresses used (continuously, must be explicitly canceled, NOT implemented yet!) + * @param timeout how long is the lookup allowed to take at most + * @param peer_address_callback function to call with the results + * @param peer_address_callback_cls closure for peer_address_callback + */ +struct GNUNET_TRANSPORT_PeerIterateContext * +GNUNET_TRANSPORT_peer_get_active_addresses (const struct + GNUNET_CONFIGURATION_Handle *cfg, + const struct GNUNET_PeerIdentity + *peer, int one_shot, + struct GNUNET_TIME_Relative timeout, + GNUNET_TRANSPORT_PeerIterateCallback + peer_address_callback, + void *peer_address_callback_cls); + + +/** + * Cancel request for peer lookup. + * + * @param alc handle for the request to cancel + */ +void +GNUNET_TRANSPORT_peer_get_active_addresses_cancel (struct + GNUNET_TRANSPORT_PeerIterateContext + *alc); /** @@ -309,10 +363,11 @@ struct GNUNET_TRANSPORT_Blacklist; * * @param cls closure * @param pid peer to approve or disapproave - * @return GNUNET_OK if the connection is allowed + * @return GNUNET_OK if the connection is allowed, GNUNET_SYSERR if not */ -typedef int (*GNUNET_TRANSPORT_BlacklistCallback)(void *cls, - const struct GNUNET_PeerIdentity *pid); +typedef int (*GNUNET_TRANSPORT_BlacklistCallback) (void *cls, + const struct + GNUNET_PeerIdentity * pid); /** @@ -324,17 +379,15 @@ typedef int (*GNUNET_TRANSPORT_BlacklistCallback)(void *cls, * only way to re-enable connections from peers that were previously * blacklisted. * - * @param sched scheduler to use * @param cfg configuration to use * @param cb callback to invoke to check if connections are allowed * @param cb_cls closure for cb * @return NULL on error, otherwise handle for cancellation */ struct GNUNET_TRANSPORT_Blacklist * -GNUNET_TRANSPORT_blacklist (struct GNUNET_SCHEDULER_Handle *sched, - const struct GNUNET_CONFIGURATION_Handle *cfg, - GNUNET_TRANSPORT_BlacklistCallback cb, - void *cb_cls); +GNUNET_TRANSPORT_blacklist (const struct GNUNET_CONFIGURATION_Handle *cfg, + GNUNET_TRANSPORT_BlacklistCallback cb, + void *cb_cls); /**