/*
This file is part of GNUnet
- (C) 2009, 2010 Christian Grothoff (and other contributing authors)
+ Copyright (C) 2009-2014 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
*/
struct Session;
-/**
- * Every 'struct Session' must begin with this header.
- */
-struct SessionHeader
-{
- /* empty, for now */
-};
-
/**
* Function that will be called whenever the plugin internally
*
* @param cls closure
* @param peer which peer was the session for
- * @param session which session is being destoyed
+ * @param session which session is being destroyed
*/
typedef void
(*GNUNET_TRANSPORT_SessionEnd) (void *cls,
- const struct GNUNET_PeerIdentity *peer,
+ const struct GNUNET_HELLO_Address *address,
struct Session *session);
/**
- * Function that will be called whenever the plugin internally
- * creates a new session and hence transport need to tell ATS.
- * This happens when we have a inbound connection we did not
- * initiate.
+ * Plugin tells transport service about a new inbound session
*
- * @param cls closure
- * @param peer peer
- * @param plugin plugin
- * @param address address
- * @param address_len length of the @a address
- * @param session session
- * @param ats ATS information
- * @param ats_count number of entries in @a ats array
+ * @param cls unused
+ * @param address the address
+ * @param session the new session
+ * @param net network information
*/
typedef void
(*GNUNET_TRANSPORT_SessionStart) (void *cls,
- const struct GNUNET_PeerIdentity *peer,
- const char *plugin,
- const void *address,
- uint16_t address_len,
+ const struct GNUNET_HELLO_Address *address,
struct Session *session,
- const struct GNUNET_ATS_Information *ats,
- uint32_t ats_count);
+ enum GNUNET_ATS_Network_Type net);
/**
*/
typedef struct GNUNET_TIME_Relative
(*GNUNET_TRANSPORT_PluginReceiveCallback) (void *cls,
- const struct GNUNET_PeerIdentity *peer,
- const struct GNUNET_MessageHeader *message,
+ const struct GNUNET_HELLO_Address *address,
struct Session *session,
- const char *sender_address,
- uint16_t sender_address_len);
+ const struct GNUNET_MessageHeader *message);
/**
- * Function that will be called to figure if an address is an loopback,
- * LAN, WAN etc. address
+ * Function that can be called by plugins to figure if an address is
+ * an loopback, LAN or WAN address. Ultimately invokes
+ * #GNUNET_ATS_address_get_type().
*
* @param cls closure
* @param addr binary address
* @param addrlen length of the @a addr
- * @return ATS Information containing the network type
+ * @return type of the network the address belongs to
*/
-typedef struct GNUNET_ATS_Information
+typedef enum GNUNET_ATS_Network_Type
(*GNUNET_TRANSPORT_AddressToType) (void *cls,
const struct sockaddr *addr,
size_t addrlen);
/**
- * Function called when quality properties of an address change.
+ * Function called when distance of an address changes.
*
* @param cls closure
* @param peer peer
- * @param address address
- * @param address_len length of the @a address
- * @param session session
- * @param ats ATS information
- * @param ats_count number entries in the @a ats array
+ * @param distance new distance
*/
typedef void
-(*GNUNET_TRANSPORT_UpdateAddressMetrics) (void *cls,
- const struct GNUNET_PeerIdentity *peer,
- const void *address,
- uint16_t address_len,
- struct Session *session,
- const struct GNUNET_ATS_Information *ats,
- uint32_t ats_count);
+(*GNUNET_TRANSPORT_UpdateAddressDistance) (void *cls,
+ const struct GNUNET_HELLO_Address *address,
+ uint32_t distance);
+
/**
* Function that will be called for each address the transport
* @param cls closure
* @param add_remove should the address added (#GNUNET_YES) or removed (#GNUNET_NO) from the
* set of valid addresses?
- * @param addr one of the addresses of the host
- * the specific address format depends on the transport
- * @param addrlen length of the @a addr
- * @param dest_plugin plugin to use this address with
+ * @param address the address to add or remove
*/
typedef void
(*GNUNET_TRANSPORT_AddressNotification) (void *cls,
int add_remove,
- const void *addr,
- size_t addrlen,
- const char *dest_plugin);
+ const struct GNUNET_HELLO_Address *address);
/**
/**
* Function that returns a HELLO message.
+ *
+ * @return HELLO message (FIXME with what?)
*/
typedef const struct GNUNET_MessageHeader *
(*GNUNET_TRANSPORT_GetHelloCallback) (void);
* whenever a message is received. If this field is "NULL",
* the plugin should load in 'stub' mode and NOT fully
* initialize and instead only return an API with the
- * 'address_pretty_printer', 'address_to_string' and
- * 'string_to_address' functions.
+ * @e address_pretty_printer, @e address_to_string and
+ * @e string_to_address functions.
*/
GNUNET_TRANSPORT_PluginReceiveCallback receive;
GNUNET_TRANSPORT_AddressToType get_address_type;
/**
- * Function that will be called to figure if an address is an loopback,
- * LAN, WAN etc. address
+ * Function that will be called by DV to update distance for
+ * an address.
*/
- GNUNET_TRANSPORT_UpdateAddressMetrics update_address_metrics;
-
+ GNUNET_TRANSPORT_UpdateAddressDistance update_address_distance;
/**
* What is the maximum number of connections that this transport
struct Session *session);
+/**
+ * Function that is called to get the keepalive factor.
+ * #GNUNET_CONSTANTS_IDLE_CONNECTION_TIMEOUT is divided by this number to
+ * calculate the interval between keepalive packets.
+ *
+ * @param cls closure with the `struct Plugin`
+ * @return keepalive factor
+ */
+typedef unsigned int
+(*GNUNET_TRANSPORT_QueryKeepaliveFactorFunction) (void *cls);
+
+
/**
* Function that can be called to force a disconnect from the
* specified neighbour. This should also cancel all previously
/**
* Function called by the pretty printer for the resolved address for
- * each human-readable address obtained.
+ * each human-readable address obtained. The callback can be called
+ * several times. The last invocation must be with a @a address of
+ * NULL and a @a res of #GNUNET_OK. Thus, to indicate conversion
+ * errors, the callback might be called first with @a address NULL and
+ * @a res being #GNUNET_SYSERR. In that case, there must still be a
+ * subsequent call later with @a address NULL and @a res #GNUNET_OK.
*
* @param cls closure
- * @param address one of the names for the host, NULL
- * on the last call to the callback
+ * @param address one of the names for the host, NULL on last callback
+ * @param res #GNUNET_OK if conversion was successful, #GNUNET_SYSERR on failure,
+ * #GNUNET_OK on last callback
*/
typedef void
(*GNUNET_TRANSPORT_AddressStringCallback) (void *cls,
- const char *address);
+ const char *address,
+ int res);
/**
const struct GNUNET_HELLO_Address *address);
+/**
+ * Function that will be called whenever the transport service wants to
+ * notify the plugin that a session is still active and in use and
+ * therefore the session timeout for this session has to be updated
+ *
+ * @param cls closure
+ * @param peer which peer was the session for
+ * @param session which session is being updated
+ */
+typedef void
+(*GNUNET_TRANSPORT_UpdateSessionTimeout) (void *cls,
+ const struct GNUNET_PeerIdentity *peer,
+ struct Session *session);
+
+
+/**
+ * Function that will be called whenever the transport service wants to
+ * notify the plugin that the inbound quota changed and that the plugin
+ * should update it's delay for the next receive value
+ *
+ * @param cls closure
+ * @param peer which peer was the session for
+ * @param session which session is being updated
+ * @param delay new delay to use for receiving
+ */
+typedef void
+(*GNUNET_TRANSPORT_UpdateInboundDelay) (void *cls,
+ const struct GNUNET_PeerIdentity *peer,
+ struct Session *session,
+ struct GNUNET_TIME_Relative delay);
+
/**
* Function called for a quick conversion of the binary address to
* a numeric address. Note that the caller must not free the
/**
* Function to obtain the network type for a session
*
- * @param cls closure ('struct Plugin*')
+ * @param cls closure (`struct Plugin *`)
* @param session the session
* @return the network type
*/
struct Session *session);
+/**
+ * Function called by the plugin with information about the
+ * current sessions managed by the plugin (for monitoring).
+ *
+ * @param cls closure
+ * @param session session handle this information is about,
+ * NULL to indicate that we are "in sync" (initial
+ * iteration complete)
+ * @param info information about the state of the session,
+ * NULL if @a session is also NULL and we are
+ * merely signalling that the initial iteration is over
+ */
+typedef void
+(*GNUNET_TRANSPORT_SessionInfoCallback) (void *cls,
+ struct Session *session,
+ const struct GNUNET_TRANSPORT_SessionInfo *info);
+
+
+/**
+ * Begin monitoring sessions of a plugin. There can only
+ * be one active monitor per plugin (i.e. if there are
+ * multiple monitors, the transport service needs to
+ * multiplex the generated events over all of them).
+ *
+ * @param cls closure of the plugin
+ * @param sic callback to invoke, NULL to disable monitor;
+ * plugin will being by iterating over all active
+ * sessions immediately and then enter monitor mode
+ * @param sic_cls closure for @a sic
+ */
+typedef void
+(*GNUNET_TRANSPORT_SessionMonitorSetup) (void *cls,
+ GNUNET_TRANSPORT_SessionInfoCallback sic,
+ void *sic_cls);
+
+
/**
* Each plugin is required to return a pointer to a struct of this
* type as the return value from its entry point.
GNUNET_TRANSPORT_DisconnectSessionFunction disconnect_session;
/**
- * Function to pretty-print addresses. NOTE: this function is not
- * yet used by transport-service, but will be used in the future
- * once the transport-API has been completed.
+ * Function that will be called whenever the transport service wants to
+ * notify the plugin that a session is still active and in use and
+ * therefore the session timeout for this session has to be updated
+ */
+ GNUNET_TRANSPORT_UpdateSessionTimeout update_session_timeout;
+
+ /**
+ * Function that will be called whenever the transport service wants to
+ * notify the plugin that the inbound quota changed and that the plugin
+ * should update it's delay for the next receive value
+ */
+ GNUNET_TRANSPORT_UpdateInboundDelay update_inbound_delay;
+
+ /**
+ * Function that is used to query keepalive factor.
+ * #GNUNET_CONSTANTS_IDLE_CONNECTION_TIMEOUT is divided by this number to
+ * calculate the interval between keepalive packets.
+ */
+ GNUNET_TRANSPORT_QueryKeepaliveFactorFunction query_keepalive_factor;
+
+ /**
+ * Function to pretty-print addresses.
*/
GNUNET_TRANSPORT_AddressPrettyPrinter address_pretty_printer;
/**
* Function that will be called tell the plugin to create a session
- * object
+ * object.
*/
GNUNET_TRANSPORT_CreateSession get_session;
* Function to obtain the network type for a session
*/
GNUNET_TRANSPORT_GetNetworkType get_network;
+
+ /**
+ * Function to monitor the sessions managed by the plugin.
+ */
+ GNUNET_TRANSPORT_SessionMonitorSetup setup_monitor;
};
+/*#ifndef PLUGIN_TRANSPORT_H*/
#endif
+/* end of gnunet_transport_plugin.h */
projects / oweals / gnunet.git / blobdiff