/*
This file is part of GNUnet.
- (C) 2009-2014 Christian Grothoff (and other contributing authors)
+ Copyright (C) 2009-2014 GNUnet e.V.
GNUnet is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published
You should have received a copy of the GNU General Public License
along with GNUnet; see the file COPYING. If not, write to the
- Free Software Foundation, Inc., 59 Temple Place - Suite 330,
- Boston, MA 02111-1307, USA.
+ Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ Boston, MA 02110-1301, USA.
*/
/**
- * @file include/gnunet_transport_service.h
- * @brief low-level P2P IO
* @author Christian Grothoff
+ *
+ * @file
+ * Low-level P2P IO
+ *
+ * @defgroup transport Transport service
+ * Low-level P2P IO
+ *
+ * @see [Documentation](https://gnunet.org/transport-service)
+ *
+ * @{
*/
#ifndef GNUNET_TRANSPORT_SERVICE_H
/**
* Version number of the transport API.
*/
-#define GNUNET_TRANSPORT_VERSION 0x00000001
+#define GNUNET_TRANSPORT_VERSION 0x00000002
/**
GNUNET_TRANSPORT_disconnect (struct GNUNET_TRANSPORT_Handle *handle);
-/* ************************* Connections *********************** */
-
-/**
- * Opaque handle for a transmission-ready request.
- */
-struct GNUNET_TRANSPORT_TryConnectHandle;
-
-/**
- * Function to call with result of the try connect request.
- *
- * @param cls closure
- * @param result #GNUNET_OK if message was transmitted to transport service
- * #GNUNET_SYSERR if message was not transmitted to transport service
- */
-typedef void
-(*GNUNET_TRANSPORT_TryConnectCallback) (void *cls,
- const int result);
-
-
-/**
- * Ask the transport service to establish a connection to
- * the given peer.
- *
- * @param handle connection to transport service
- * @param target who we should try to connect to
- * @param cb callback to be called when request was transmitted to transport
- * service
- * @param cb_cls closure for the callback @a cb
- * @return a `struct GNUNET_TRANSPORT_TryConnectHandle` handle or
- * NULL on failure (@a cb will not be called)
- */
-struct GNUNET_TRANSPORT_TryConnectHandle *
-GNUNET_TRANSPORT_try_connect (struct GNUNET_TRANSPORT_Handle *handle,
- const struct GNUNET_PeerIdentity *target,
- GNUNET_TRANSPORT_TryConnectCallback cb,
- void *cb_cls);
-
-
-/**
- * Cancel the request to transport to try a connect
- * Callback will not be called
- *
- * @param tch handle to cancel
- */
-void
-GNUNET_TRANSPORT_try_connect_cancel (struct GNUNET_TRANSPORT_TryConnectHandle *tch);
-
-
-/**
- * Ask the transport service to disconnect from the given peer.
- *
- * @param handle connection to transport service
- * @param target who we should try to disconnect from
- * @param cb callback to be called when request was transmitted to transport
- * service
- * @param cb_cls closure for the callback @a cb
- * @return a `struct GNUNET_TRANSPORT_TryConnectHandle` handle or
- * NULL on failure (@a cb will not be called)
- */
-struct GNUNET_TRANSPORT_TryConnectHandle *
-GNUNET_TRANSPORT_try_disconnect (struct GNUNET_TRANSPORT_Handle *handle,
- const struct GNUNET_PeerIdentity *target,
- GNUNET_TRANSPORT_TryConnectCallback cb,
- void *cb_cls);
-
-
-/**
- * Cancel the request to transport to disconnect.
- * Callback will not be called anymore.
- *
- * @param tch handle for operation to cancel
- */
-void
-GNUNET_TRANSPORT_try_disconnect_cancel (struct GNUNET_TRANSPORT_TryConnectHandle *tch);
-
-
/* ************************* Sending *************************** */
/**
GNUNET_TRANSPORT_notify_transmit_ready_cancel (struct GNUNET_TRANSPORT_TransmitHandle *th);
-
/**
* Checks if a given peer is connected to us
*
*
* @param handle transport handle
* @param peer the peer to set the metric for
- * @param inbound set inbound direction (#GNUNET_YES or #GNUNET_NO)
- * @param outbound set outbound direction (#GNUNET_YES or #GNUNET_NO)
- * @param ats the metric as ATS information
- * @param ats_count the number of metrics
- *
- * Supported ATS values:
- * #GNUNET_ATS_QUALITY_NET_DELAY (value in ms)
- * #GNUNET_ATS_QUALITY_NET_DISTANCE (value in count(hops))
- *
- * Example
- * To enforce a delay of 10 ms for peer p1 in sending direction use:
+ * @param prop the performance metrics to set
+ * @param delay_in inbound delay to introduce
+ * @param delay_out outbound delay to introduce
*
- * struct GNUNET_ATS_Information ats;
- * ats.type = ntohl (GNUNET_ATS_QUALITY_NET_DELAY);
- * ats.value = ntohl (10);
- * GNUNET_TRANSPORT_set_traffic_metric (th, p1, TM_SEND, &ats, 1);
- *
- * Note:
- * Delay restrictions in receiving direction will be enforced with
- * 1 message delay.
+ * Note: Delay restrictions in receiving direction will be enforced
+ * with one message delay.
*/
void
GNUNET_TRANSPORT_set_traffic_metric (struct GNUNET_TRANSPORT_Handle *handle,
const struct GNUNET_PeerIdentity *peer,
- int inbound,
- int outbound,
- const struct GNUNET_ATS_Information *ats,
- size_t ats_count);
+ const struct GNUNET_ATS_Properties *prop,
+ struct GNUNET_TIME_Relative delay_in,
+ struct GNUNET_TIME_Relative delay_out);
/* *************************** HELLO *************************** */
*/
struct GNUNET_TRANSPORT_OfferHelloHandle;
+
/**
* Offer the transport service the HELLO of another peer. Note that
* the transport service may just ignore this message if the HELLO is
* @param cont continuation to call when HELLO has been sent,
* tc reason #GNUNET_SCHEDULER_REASON_TIMEOUT for fail
* tc reasong #GNUNET_SCHEDULER_REASON_READ_READY for success
- * @param cls closure for continuation
+ * @param cont_cls closure for @a cont
* @return a GNUNET_TRANSPORT_OfferHelloHandle handle or NULL on failure,
- * in case of failure cont will not be called
+ * in case of failure @a cont will not be called
*
*/
struct GNUNET_TRANSPORT_OfferHelloHandle *
GNUNET_TRANSPORT_offer_hello (struct GNUNET_TRANSPORT_Handle *handle,
const struct GNUNET_MessageHeader *hello,
- GNUNET_SCHEDULER_Task cont, void *cls);
+ GNUNET_SCHEDULER_TaskCallback cont,
+ void *cont_cls);
/**
* a final call with NULL for peer and address will follow when done.
* In this case state and timeout do not contain valid values.
*
- * The #GNUNET_TRANSPORT_monitor_peers_cancel call MUST not be called from
+ * The #GNUNET_TRANSPORT_monitor_peers_cancel() call MUST not be called from
* within this function!
*
*
* @param cls closure
* @param peer peer this update is about,
* NULL if this is the final last callback for a iteration operation
- * @param address address, NULL for disconnect notification in monitor mode
+ * @param address address, NULL if this is the final callback for iteration op
* @param state current state this peer is in
* @param state_timeout timeout for the current state of the peer
*/
* to communicate with this peer, the state this peer is currently in and the
* the current timeout for this state.
*
- * Upon completion, the 'GNUNET_TRANSPORT_PeerIterateCallback' is called one
- * more time with 'NULL'. After this, the operation must no longer be
+ * Upon completion, the #GNUNET_TRANSPORT_PeerIterateCallback is called one
+ * more time with `NULL`. After this, the operation must no longer be
* explicitly canceled.
*
* The #GNUNET_TRANSPORT_monitor_peers_cancel call MUST not be called in the
* indicate a change to a validation entry. The information included represent
* the current state of the validation entry,
*
- * If the monitoring was called with one_shot=GNUNET_YES, a final callback
- * with peer==NULL and address==NULL is executed.
+ * If the monitoring was called with `one_shot==GNUNET_YES`, a final callback
+ * with `address==NULL` is executed.
*
* @param cls closure
- * @param peer peer this update is about,
+ * @param address address this update is about,
* NULL if this is the final last callback for a iteration operation
- * @param address address,
- * NULL for disconnect notification in monitor mode
* @param last_validation when was this address last validated
* @param valid_until when does this address expire
* @param next_validation time of the next validation operation
*/
typedef void
(*GNUNET_TRANSPORT_ValidationIterateCallback) (void *cls,
- const struct GNUNET_PeerIdentity *peer,
const struct GNUNET_HELLO_Address *address,
struct GNUNET_TIME_Absolute last_validation,
struct GNUNET_TIME_Absolute valid_until,
/**
* Abstract representation of a plugin's session.
- * Corresponds to the `struct Session` within the TRANSPORT service.
+ * Corresponds to the `struct GNUNET_ATS_Session` within the TRANSPORT service.
*/
struct GNUNET_TRANSPORT_PluginSession;
const struct GNUNET_TRANSPORT_SessionInfo *info);
-
/**
* Install a plugin session state monitor callback. The callback
* will be notified whenever the session changes.
/* ifndef GNUNET_TRANSPORT_SERVICE_H */
#endif
-/* end of gnunet_transport_service.h */
+/** @} */ /* end of group */
+/* end of gnunet_transport_service.h */
projects / oweals / gnunet.git / blobdiff