* @file include/gnunet_transport_service.h
* @brief low-level P2P IO
* @author Christian Grothoff
+ *
+ * TODO:
+ * - define API for blacklisting, un-blacklisting and notifications
+ * about blacklisted peers
*/
#ifndef GNUNET_TRANSPORT_SERVICE_H
* Function called by the transport for each received message.
*
* @param cls closure
- * @param latency estimated latency for communicating with the
- * given peer
* @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
*/
typedef void (*GNUNET_TRANSPORT_ReceiveCallback) (void *cls,
- struct GNUNET_TIME_Relative
- latency,
const struct
GNUNET_PeerIdentity * peer,
const struct
GNUNET_MessageHeader *
- message);
+ message,
+ struct GNUNET_TIME_Relative
+ latency,
+ unsigned int distance);
/**
*
* @param cls closure
* @param peer the peer that connected
- * @param latency current latency of the connection
+ * @param latency estimated latency for communicating with the
+ * given peer (round-trip)
+ * @param distance in overlay hops, as given by transport plugin
*/
typedef void
(*GNUNET_TRANSPORT_NotifyConnect) (void *cls,
const struct GNUNET_PeerIdentity * peer,
- struct GNUNET_TIME_Relative latency);
+ struct GNUNET_TIME_Relative latency,
+ unsigned int distance);
/**
* Function called to notify transport users that another
peer);
+/**
+ * Function to call with a human-readable format of an address
+ *
+ * @param cls closure
+ * @param address NULL on error, otherwise 0-terminated printable UTF-8 string
+ */
typedef void
(*GNUNET_TRANSPORT_AddressLookUpCallback) (void *cls,
- const char *address);
+ const char *address);
+
/**
* Connect to the transport service. Note that the connection may
* @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
/**
* Disconnect from the transport service.
+ *
+ * @param handle handle returned from connect
*/
void GNUNET_TRANSPORT_disconnect (struct GNUNET_TRANSPORT_Handle *handle);
*handle,
const struct GNUNET_PeerIdentity
*target, size_t size,
- unsigned int priority,
+ unsigned int priority,
struct GNUNET_TIME_Relative
timeout,
GNUNET_CONNECTION_TransmitReadyNotify
*h);
+
+typedef void (*GNUNET_TRANSPORT_HelloUpdateCallback)(void *cls,
+ const struct GNUNET_MessageHeader *hello);
+
+
/**
- * Obtain the HELLO message for this peer.
+ * Obtain updates on changes to the HELLO message for this peer.
*
* @param handle connection to transport service
- * @param timeout how long to wait for the HELLO
- * @param rec function to call with the HELLO, sender will be our peer
- * identity; message and sender will be NULL on timeout
- * (handshake with transport service pending/failed).
- * cost estimate will be 0.
+ * @param rec function to call with the HELLO
* @param rec_cls closure for rec
*/
void
GNUNET_TRANSPORT_get_hello (struct GNUNET_TRANSPORT_Handle *handle,
- struct GNUNET_TIME_Relative timeout,
- GNUNET_TRANSPORT_ReceiveCallback rec,
+ GNUNET_TRANSPORT_HelloUpdateCallback rec,
void *rec_cls);
+/**
+ * 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
+ */
+void
+GNUNET_TRANSPORT_get_hello_cancel (struct GNUNET_TRANSPORT_Handle *handle,
+ GNUNET_TRANSPORT_HelloUpdateCallback rec,
+ void *rec_cls);
+
+
/**
* 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.
+ * malformed or useless due to our local configuration. If the HELLO
+ * is working, we should add it to PEERINFO.
*
* @param handle connection to transport service
* @param hello the hello message
GNUNET_TRANSPORT_offer_hello (struct GNUNET_TRANSPORT_Handle *handle,
const struct GNUNET_MessageHeader *hello);
+
/**
- * Convert a binary address into a human
- * readable address.
+ * 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
+ * (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
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,
/* ifndef GNUNET_TRANSPORT_SERVICE_H */
#endif
/* end of gnunet_transport_service.h */
-
-
/*
This file is part of GNUnet
- (C) 2009 Christian Grothoff (and other contributing authors)
+ (C) 2009, 2010 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
#include "gnunet_scheduler_lib.h"
#include "gnunet_transport_service.h"
+
/**
* Function called by the transport for each received message.
* This function should also be called with "NULL" for the
* message to signal that the other peer disconnected.
*
* @param cls closure
- * @param latency estimated latency for communicating with the
- * given peer; should be set to GNUNET_TIME_UNIT_FOREVER_REL
- * until the transport has seen messages transmitted in
- * BOTH directions (and hence been able to do an actual
- * round-trip observation); a non-FOREVER latency is also used
- * by the transport to know that communication in both directions
- * using this one plugin actually works
+ * @param distance in overlay hops; use 1 unless DV
+ * @param sender_address binary address of the sender (if observed)
+ * @param sender_address_len number of bytes in sender_address
* @param peer (claimed) identity of the other peer
* @param message the message, NULL if peer was disconnected
*/
typedef void (*GNUNET_TRANSPORT_PluginReceiveCallback) (void *cls,
- struct
- GNUNET_TIME_Relative
- latency,
+ unsigned int distance,
+ const char *sender_address,
+ size_t sender_address_len,
const struct
GNUNET_PeerIdentity *
peer,
message);
-/**
- * Function that will be called if we receive a validation
- * of an address challenge that we transmitted to another
- * peer. Note that the validation should only be considered
- * acceptable if the challenge matches AND if the sender
- * address is at least a plausible address for this peer
- * (otherwise we may be seeing a MiM attack).
- *
- * @param cls closure
- * @param name name of the transport that generated the address
- * @param peer who responded to our challenge
- * @param challenge the challenge number we presumably used
- * @param sender_addr string describing our sender address (as observed
- * by the other peer in human-readable format)
- */
-typedef void (*GNUNET_TRANSPORT_ValidationNotification) (void *cls,
- const char *name,
- const struct
- GNUNET_PeerIdentity *
- peer,
- uint32_t challenge,
- const char
- *sender_addr);
-
-
/**
* Function that will be called for each address the transport
expires);
-/**
- * Function that will be called for each address obtained from the HELLO.
- *
- * @param cls closure
- * @param name name of the transport that generated the address
- * @param addr one of the addresses of the host, NULL for the last address
- * the specific address format depends on the transport
- * @param addrlen length of the address
- */
-typedef void (*GNUNET_TRANSPORT_AddressCallback) (void *cls,
- const char *name,
- const void *addr,
- size_t addrlen);
-
-
/**
* The transport service will pass a pointer to a struct
* of this type as the first and only argument to the
*/
struct GNUNET_SCHEDULER_Handle *sched;
- /**
- * Our public key.
- */
- struct GNUNET_CRYPTO_RsaPublicKeyBinaryEncoded *my_public_key;
-
- /**
- * Our private key.
- */
- struct GNUNET_CRYPTO_RsaPrivateKey *my_private_key;
-
/**
* Identity of this peer.
*/
*/
GNUNET_TRANSPORT_AddressNotification notify_address;
- /**
- * Function that must be called by each plugin to notify the
- * transport service about a successful validation of an
- * address of another peer (or at least likely successful
- * validation).
- */
- GNUNET_TRANSPORT_ValidationNotification notify_validation;
-
/**
* What is the default quota (in terms of incoming bytes per
* ms) for new connections?
};
-/**
- * Function that can be used by the transport service to validate
- * the address of another peer. Even if
- * we already have a connection to this peer, this function is
- * required to establish a new one.
- *
- * @param cls closure
- * @param target who should receive this message
- * @param challenge challenge code to use
- * @param timeout how long should we try to transmit these?
- * @param addrlen length of the address
- * @param addr the address
- * @return GNUNET_OK on success, GNUNET_SYSERR if the address
- * format is invalid
- */
-typedef int
- (*GNUNET_TRANSPORT_ValidationFunction) (void *cls,
- const struct
- GNUNET_PeerIdentity * target,
- uint32_t challenge,
- struct GNUNET_TIME_Relative
- timeout, const void *addr,
- size_t addrlen);
-
/**
* Function called by the GNUNET_TRANSPORT_TransmitFunction
* upon "completion".
*
* @param cls closure
* @param target who should receive this message
- * @param priority how important is the message?
* @param msg the message to transmit
- * @param timeout how long to wait at most for the transmission
+ * @param priority how important is the message (most plugins will
+ * ignore message priority and just FIFO)
+ * @param timeout how long to wait at most for the transmission (does not
+ * require plugins to discard the message after the timeout,
+ * just advisory for the desired delay; most plugins will ignore
+ * this as well)
+ * @param addr the address to use (can be NULL if the plugin
+ * is "on its own" (i.e. re-use existing TCP connection))
+ * @param addrlen length of the address in bytes
+ * @param force_address GNUNET_YES if the plugin MUST use the given address,
+ * otherwise the plugin may use other addresses or
+ * existing connections (if available)
* @param cont continuation to call once the message has
* been transmitted (or if the transport is ready
* for the next transmission call; or if the
* peer disconnected...); can be NULL
* @param cont_cls closure for cont
+ * @return number of bytes used (on the physical network, with overheads);
+ * -1 on hard errors (i.e. address invalid); 0 is a legal value
+ * and does NOT mean that the message was not transmitted (DV)
*/
-typedef void
+typedef ssize_t
(*GNUNET_TRANSPORT_TransmitFunction) (void *cls,
const struct GNUNET_PeerIdentity *
target,
+ const struct GNUNET_MessageHeader *msg,
unsigned int priority,
- const struct GNUNET_MessageHeader *
- msg,
struct GNUNET_TIME_Relative timeout,
- GNUNET_TRANSPORT_TransmitContinuation
+ const void *addr,
+ size_t addrlen,
+ int force_address,
+ GNUNET_TRANSPORT_TransmitContinuation
cont, void *cont_cls);
/**
- * Another peer has suggested an address for this
- * peer and transport plugin. Check that this could be a valid
- * address. If so, consider adding it to the list
- * of addresses.
+ * Another peer has suggested an address for this peer and transport
+ * plugin. Check that this could be a valid address. This function
+ * is not expected to 'validate' the address in the sense of trying to
+ * connect to it but simply to see if the binary format is technically
+ * legal for establishing a connection.
*
* @param addr pointer to the address
* @param addrlen length of addr
* @return GNUNET_OK if this is a plausible address for this peer
- * and transport
+ * and transport, GNUNET_SYSERR if not
*/
typedef int
- (*GNUNET_TRANSPORT_SuggestAddress) (void *cls,
- const void *addr, size_t addrlen);
+ (*GNUNET_TRANSPORT_CheckAddress) (void *cls,
+ const void *addr, size_t addrlen);
/**
* Each plugin is required to return a pointer to a struct of this
*/
void *cls;
- /**
- * Function used to send a single message to a particular
- * peer using the specified address. Used to validate
- * HELLOs.
- */
- GNUNET_TRANSPORT_ValidationFunction validate;
-
/**
* Function that the transport service will use to transmit data to
* another peer. May be null for plugins that only support
GNUNET_TRANSPORT_SetQuota set_receive_quota;
/**
- * Function that will be called if another peer suggested that
- * we should use a particular address (since he is reaching
- * us at that address) for this transport.
+ * Function that will be called to check if a binary address
+ * for this plugin is well-formed.
*/
- GNUNET_TRANSPORT_SuggestAddress address_suggested;
+ GNUNET_TRANSPORT_CheckAddress check_address;
+
- /**
- * Relative cost of this transport compared to others. This
- * is supposed to be a static cost estimate which determines
- * which plugins should not even be attempted if other,
- * cheaper transports are already working. The idea is that
- * the costs have roughly this relationship:
- * <pre>
- * TCP < UDP < HTTP == HTTPS < SMTP
- * </pre>
- */
- unsigned int cost_estimate;
};
projects / oweals / gnunet.git / commitdiff