From aeece360025012e270a30d4cd174a60fca30af38 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Wed, 6 Jul 2016 23:09:59 +0000 Subject: [PATCH] -skeletons for transport-ng --- .../gnunet_transport_communication_service.h | 228 ++++++++++++++++++ src/include/gnunet_transport_core_service.h | 177 ++++++++++++++ src/include/gnunet_transport_hello_service.h | 142 +++++++++++ .../gnunet_transport_monitor_service.h | 192 +++++++++++++++ 4 files changed, 739 insertions(+) create mode 100644 src/include/gnunet_transport_communication_service.h create mode 100644 src/include/gnunet_transport_core_service.h create mode 100644 src/include/gnunet_transport_hello_service.h create mode 100644 src/include/gnunet_transport_monitor_service.h diff --git a/src/include/gnunet_transport_communication_service.h b/src/include/gnunet_transport_communication_service.h new file mode 100644 index 000000000..aa8cc1ba1 --- /dev/null +++ b/src/include/gnunet_transport_communication_service.h @@ -0,0 +1,228 @@ +/* + This file is part of GNUnet. + Copyright (C) 2009-2016 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 + 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 + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + 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., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ + +/** + * @author Christian Grothoff + * + * @file + * API of the transport service towards the communicator processes. + * + * @defgroup transport TRANSPORT service + * Low-level communication with other peers + * + * @see [Documentation](https://gnunet.org/transport-service) + * + * @{ + */ + +#ifndef GNUNET_TRANSPORT_COMMUNICATION_SERVICE_H +#define GNUNET_TRANSPORT_COMMUNICATION_SERVICE_H + +#ifdef __cplusplus +extern "C" +{ +#if 0 /* keep Emacsens' auto-indent happy */ +} +#endif +#endif + +#include "gnunet_util_lib.h" + +/** + * Version number of the transport communication API. + */ +#define GNUNET_TRANSPORT_COMMUNICATION_VERSION 0x00000000 + + +/** + * Function called by the transport service to initialize a + * message queue given address information about another peer. + * + * @param cls closure + * @param peer identity of the other peer + * @param address where to send the message, human-readable + * communicator-specific format, 0-terminated, UTF-8 + * @return NULL if the provided address is invalid, otherwise an MQ to + * send messages to that peer + */ +typedef struct GNUNET_MQ_Handle * +(*GNUNET_TRANSPORT_CommunicatorMqInit) (void *cls, + const struct GNUNET_PeerIdentity *peer, + const void *address); + + +/** + * Opaque handle to the transport service for communicators. + */ +struct GNUNET_TRANSPORT_CommunicatorHandle; + + +/** + * Connect to the transport service. + * + * @param cfg configuration to use + * @param name name of the communicator that is connecting + * @param mtu maximum message size supported by communicator, 0 if + * sending is not supported + * @param mq_init function to call to initialize a message queue given + * the address of another peer, can be NULL if the + * communicator only supports receiving messages + * @param mq_init_cls closure for @a mq_init + * @return NULL on error + */ +struct GNUNET_TRANSPORT_CommunicatorHandle * +GNUNET_TRANSPORT_communicator_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, + const char *name, + size_t mtu, + GNUNET_TRANSPORT_CommunicatorMqInit mq_init, + void *mq_init_cls); + + +/** + * Disconnect from the transport service. + * + * @param ch handle returned from connect + */ +void +GNUNET_TRANSPORT_communicator_disconnect (struct GNUNET_TRANSPORT_CommunicatorHandle *ch); + + +/* ************************* Receiving *************************** */ + +/** + * Function called to notify communicator that we have received + * and processed the message. + * + * @param cls closure + * @param success #GNUNET_SYSERR on failure (try to disconnect/reset connection) + * #GNUNET_OK on success + */ +typedef void +(*GNUNET_TRANSPORT_MessageCompletedCallback) (void *cls, + int success); + + +/** + * Notify transport service that the communicator has received + * a message. + * + * @param handle connection to transport service + * @param sender presumed sender of the message (details to be checked + * by higher layers) + * @param msg the message + * @param cb function to call once handling the message is done, NULL if + * flow control is not supported by this communicator + * @param cb_cls closure for @a cb + * @return #GNUNET_OK if all is well, #GNUNET_NO if the message was + * immediately dropped due to memory limitations (communicator + * should try to apply back pressure), + * #GNUNET_SYSERR if the message is ill formed and communicator + * should try to reset stream + */ +int +GNUNET_TRANSPORT_communicator_receive (struct GNUNET_TRANSPORT_CommunicatorHandle *handle, + const struct GNUNET_PeerIdentity *sender, + const struct GNUNET_MessageHeader *msg, + GNUNET_TRANSPORT_MessageCompletedCallback cb, + void *cb_cls); + + +/* ************************* Discovery *************************** */ + + +/** + * Notify transport service that an MQ became available due to an + * "inbound" connection or because the communicator discovered the + * presence of another peer. + * + * @param handle connection to transport service + * @param peer peer with which we can now communicate + * @param address address in human-readable format, 0-terminated, UTF-8 + * @param nt which network type does the @a address belong to? + * @param mq message queue of the @a peer + */ +void +GNUNET_TRANSPORT_communicator_mq_add (struct GNUNET_TRANSPORT_CommunicatorHandle *handle, + const struct GNUNET_PeerIdentity *peer, + const char *address, + enum GNUNET_ATS_Network_Type nt, + struct GNUNET_MQ_Handle *mq); + + +/** + * Notify transport service that an MQ became unavailable due to a + * disconnect or timeout. + * + * @param handle connection to transport service + * @param peer peer with which we can no longer communicate via the given mq + * @param address address in human-readable format, 0-terminated, UTF-8 + * @param nt which network type does the @a address belong to? + * @param mq message queue of the @a peer + */ +void +GNUNET_TRANSPORT_communicator_mq_remove (struct GNUNET_TRANSPORT_CommunicatorHandle *handle, + const struct GNUNET_PeerIdentity *peer, + const char *address, + enum GNUNET_ATS_Network_Type nt, + struct GNUNET_MQ_Handle *mq); + + +/** + * Notify transport service about an address that this communicator + * provides for this peer. + * + * @param handle connection to transport service + * @param address our address in human-readable format, 0-terminated, UTF-8 + * @param nt which network type does the address belong to? + * @param expiration when does the communicator forsee this address expiring? + */ +void +GNUNET_TRANSPORT_communicator_address_add (struct GNUNET_TRANSPORT_CommunicatorHandle *handle, + const char *address, + enum GNUNET_ATS_Network_Type nt, + struct GNUNET_TIME_Absolute expiration); + + +/** + * Notify transport service about an address that this communicator + * no longer provides for this peer. + * + * @param handle connection to transport service + * @param address our former address in human-readable format, + * 0-terminated, in UTF-8 + */ +void +GNUNET_TRANSPORT_communicator_address_remove (struct GNUNET_TRANSPORT_CommunicatorHandle *handle, + const char *address); + + +#if 0 /* keep Emacsens' auto-indent happy */ +{ +#endif +#ifdef __cplusplus +} +#endif + +/* ifndef GNUNET_TRANSPORT_COMMUNICATOR_SERVICE_H */ +#endif + +/** @} */ /* end of group */ + +/* end of gnunet_transport_communicator_service.h */ diff --git a/src/include/gnunet_transport_core_service.h b/src/include/gnunet_transport_core_service.h new file mode 100644 index 000000000..816d5efaa --- /dev/null +++ b/src/include/gnunet_transport_core_service.h @@ -0,0 +1,177 @@ +/* + This file is part of GNUnet. + Copyright (C) 2009-2016 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 + 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 + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + 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., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ +/** + * @author Christian Grothoff + * + * @file + * API of the transport service towards the CORE service. + * + * @defgroup transport TRANSPORT service + * Communication with other peers + * + * @see [Documentation](https://gnunet.org/transport-service) + * + * @{ + */ +#ifndef GNUNET_TRANSPORT_CORE_SERVICE_H +#define GNUNET_TRANSPORT_CORE_SERVICE_H + +#ifdef __cplusplus +extern "C" +{ +#if 0 /* keep Emacsens' auto-indent happy */ +} +#endif +#endif + +#include "gnunet_util_lib.h" + +/** + * Version number of the transport API. + */ +#define GNUNET_TRANSPORT_CORE_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 + */ +typedef void +(*GNUNET_TRANSPORT_ReceiveCallback) (void *cls, + const struct GNUNET_PeerIdentity *peer, + const struct GNUNET_MessageHeader *message); + + +/** + * Opaque handle to the service. + */ +struct GNUNET_TRANSPORT_Handle; + + +/** + * Function called to notify CORE service that another + * @a peer connected to us. + * + * @param cls closure + * @param peer the peer that connected, never NULL + * @param mq message queue for sending messages to this peer + */ +typedef void +(*GNUNET_TRANSPORT_NotifyConnect) (void *cls, + const struct GNUNET_PeerIdentity *peer, + struct GNUNET_MQ_Handle *mq); + + +/** + * Function called to notify CORE service that another + * @a peer disconnected from us. The associated message + * queue must not be used henceforth. + * + * @param cls closure + * @param peer the peer that disconnected, never NULL + */ +typedef void +(*GNUNET_TRANSPORT_NotifyDisconnect) (void *cls, + const struct GNUNET_PeerIdentity *peer); + + +/** + * Function called if we have "excess" bandwidth to a peer. + * The notification will happen the first time we have excess + * bandwidth, and then only again after the client has performed + * some transmission to the peer. + * + * Excess bandwidth is defined as being allowed (by ATS) to send + * more data, and us reaching the limit of the capacity build-up + * (which, if we go past it, means we don't use available bandwidth). + * See also the "max carry" in `struct GNUNET_BANDWIDTH_Tracker`. + * + * @param cls the closure + * @param neighbour peer that we have excess bandwidth to + */ +typedef void +(*GNUNET_TRANSPORT_NotifyExcessBandwidth)(void *cls, + const struct GNUNET_PeerIdentity *neighbour); + + +/** + * Connect to the transport service. + * + * @param cfg configuration to use + * @param self our own identity (if API should check that it matches + * the identity found by transport), or NULL (no check) + * @param cls closure for the callbacks + * @param rec_handlers NULL-terminated array of handlers for incoming + * messages, or NULL + * @param nc function to call on connect events, or NULL + * @param nd function to call on disconnect events, or NULL + * @param neb function to call if we have excess bandwidth to a peer + * @return NULL on error + */ +struct GNUNET_TRANSPORT_Handle * +GNUNET_TRANSPORT_core_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, + const struct GNUNET_PeerIdentity *self, + void *cls, + GNUNET_MQ_MessageHandler *rec_handlers, + GNUNET_TRANSPORT_NotifyConnect nc, + GNUNET_TRANSPORT_NotifyDisconnect nd, + GNUNET_TRANSPORT_NotifyExcessBandwidth neb); + + +/** + * Disconnect from the transport service. + * + * @param handle handle returned from connect + */ +void +GNUNET_TRANSPORT_disconnect (struct GNUNET_TRANSPORT_Handle *handle); + + +/** + * Checks if a given peer is connected to us. Convenience + * API in case a client does not track connect/disconnect + * events internally. + * + * @param handle connection to transport service + * @param peer the peer to check + * @return #GNUNET_YES (connected) or #GNUNET_NO (disconnected) + */ +int +GNUNET_TRANSPORT_check_peer_connected (struct GNUNET_TRANSPORT_Handle *handle, + const struct GNUNET_PeerIdentity *peer); + + + +#if 0 /* keep Emacsens' auto-indent happy */ +{ +#endif +#ifdef __cplusplus +} +#endif + +/* ifndef GNUNET_TRANSPORT_CORE_SERVICE_H */ +#endif + +/** @} */ /* end of group */ + +/* end of gnunet_transport_core_service.h */ diff --git a/src/include/gnunet_transport_hello_service.h b/src/include/gnunet_transport_hello_service.h new file mode 100644 index 000000000..8fc558d3f --- /dev/null +++ b/src/include/gnunet_transport_hello_service.h @@ -0,0 +1,142 @@ +/* + This file is part of GNUnet. + Copyright (C) 2009-2016 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 + 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 + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + 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., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ + +/** + * @author Christian Grothoff + * + * @file + * obtain information about our current address + * + * @defgroup transport Transport service + * address information + * + * @see [Documentation](https://gnunet.org/transport-service) + * + * @{ + */ +#ifndef GNUNET_TRANSPORT_HELLO_SERVICE_H +#define GNUNET_TRANSPORT_HELLO_SERVICE_H + +#ifdef __cplusplus +extern "C" +{ +#if 0 /* keep Emacsens' auto-indent happy */ +} +#endif +#endif + +#include "gnunet_util_lib.h" +#include "gnunet_ats_service.h" + +/** + * Version number of the transport API. + */ +#define GNUNET_TRANSPORT_HELLO_VERSION 0x00000000 + + +/** + * Function called whenever there is an update to the + * HELLO of this peer. + * + * @param cls closure + * @param hello our updated HELLO + */ +typedef void +(*GNUNET_TRANSPORT_HelloUpdateCallback) (void *cls, + const struct GNUNET_MessageHeader *hello); + + +/** + * Handle to cancel a #GNUNET_TRANSPORT_hello_get() operation. + */ +struct GNUNET_TRANSPORT_GetHelloHandle; + + +/** + * Obtain updates on changes to the HELLO message for this peer. The callback + * given in this function is never called synchronously. + * + * @param cfg configuration to use + * @param nt which network type should the addresses from the HELLO belong to? + * @param rec function to call with the HELLO + * @param rec_cls closure for @a rec + * @return handle to cancel the operation + */ +struct GNUNET_TRANSPORT_GetHelloHandle * +GNUNET_TRANSPORT_hello_get (struct GNUNET_CONFIGURATION_Handle *cfg, + enum GNUNET_ATS_Network_Type nt, + GNUNET_TRANSPORT_HelloUpdateCallback rec, + void *rec_cls); + + +/** + * Stop receiving updates about changes to our HELLO message. + * + * @param ghh handle to cancel + */ +void +GNUNET_TRANSPORT_hello_get_cancel (struct GNUNET_TRANSPORT_GetHelloHandle *ghh); + + +/** + * Function with addresses found in a HELLO. + * + * @param cls closure + * @param peer identity of the peer + * @param address the address (UTF-8, 0-terminated) + * @param nt network type of the address + * @param expiration when does this address expire? + */ +typedef void +(*GNUNET_TRANSPORT_AddressCallback) (void *cls, + const struct GNUNET_PeerIdentity *peer, + const char *address, + enum GNUNET_ATS_Network_Type nt, + struct GNUNET_TIME_Absolute expiration); + + +/** + * Parse a HELLO message that we have received into its + * constituent addresses. + * + * @param hello message to parse + * @param cb function to call on each address found + * @param cb_cls closure for @a cb + * @return #GNUNET_OK if hello was well-formed, #GNUNET_SYSERR if not + */ +int +GNUNET_TRANSPORT_hello_parse (const struct GNUNET_MessageHeader *hello, + GNUNET_TRANSPORT_AddressCallback cb, + void *cb_cls); + + +#if 0 /* keep Emacsens' auto-indent happy */ +{ +#endif +#ifdef __cplusplus +} +#endif + +/* ifndef GNUNET_TRANSPORT_HELLO_SERVICE_H */ +#endif + +/** @} */ /* end of group */ + +/* end of gnunet_transport_hello_service.h */ diff --git a/src/include/gnunet_transport_monitor_service.h b/src/include/gnunet_transport_monitor_service.h new file mode 100644 index 000000000..a12cc4ed7 --- /dev/null +++ b/src/include/gnunet_transport_monitor_service.h @@ -0,0 +1,192 @@ +/* + This file is part of GNUnet. + Copyright (C) 2009-2016 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 + 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 + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + 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., 51 Franklin Street, Fifth Floor, + Boston, MA 02110-1301, USA. +*/ + +/** + * @author Christian Grothoff + * + * @file + * Monitoring / diagnostics API for the transport service + * + * @defgroup transport TRANSPORT service + * Communication with other peers + * + * @see [Documentation](https://gnunet.org/transport-service) + * + * @{ + */ + +#ifndef GNUNET_TRANSPORT_MONITOR_SERVICE_H +#define GNUNET_TRANSPORT_MONITOR_SERVICE_H + +#ifdef __cplusplus +extern "C" +{ +#if 0 /* keep Emacsens' auto-indent happy */ +} +#endif +#endif + +#include "gnunet_util_lib.h" + +/** + * Version number of the transport API. + */ +#define GNUNET_TRANSPORT_MONITOR_VERSION 0x00000000 + + +/** + * Information about another peer's address. + */ +struct GNUNET_TRANSPORT_MonitorInformation +{ + + /** + * Address we have for the peer, human-readable, 0-terminated, in UTF-8. + */ + const char *address; + + /** + * Network type of the address. + */ + enum GNUNET_ATS_Network_Type nt; + + /** + * #GNUNET_YES if this is an inbound connection (communicator initiated) + * #GNUNET_NO if this is an outbound connection (transport initiated) + */ + int is_inbound; + + /** + * Number of messages pending transmission for this @e address. + */ + uint32_t num_msg_pending; + + /** + * Number of bytes pending transmission for this @e address. + */ + uint32_t num_bytes_pending; + + /** + * When was this address last validated. + */ + struct GNUNET_TIME_Absolute last_validation; + + /** + * When does this address expire. + */ + struct GNUNET_TIME_Absolute valid_until; + + /** + * Time of the next validation operation. + */ + struct GNUNET_TIME_Absolute next_validation; + + /** + * Current estimate of the RTT. + */ + struct GNUNET_TIME_Relative rtt; + +}; + + +/** + * Function to call with information about a peer. + * + * If one_shot was set to #GNUNET_YES to iterate over all peers once, + * 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 + * 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 mi monitoring data on the peer + */ +typedef void +(*GNUNET_TRANSPORT_MontiorCallback) (void *cls, + const struct GNUNET_PeerIdentity *peer, + const struct GNUNET_TRANSPORT_MonitorInformation *mi); + + +/** + * Handle for a #GNUNET_TRANSPORT_monitor() operation. + */ +struct GNUNET_TRANSPORT_MonitorContext; + + +/** + * Return information about a specific peer or all peers currently known to + * transport service once or in monitoring mode. To obtain information about + * a specific peer, a peer identity can be passed. To obtain information about + * all peers currently known to transport service, NULL can be passed as peer + * identity. + * + * For each peer, the callback is called with information about the address used + * 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 + * explicitly canceled. + * + * The #GNUNET_TRANSPORT_monitor_peers_cancel call MUST not be called in the + * the peer_callback! + * + * @param cfg configuration to use + * @param peer a specific peer identity to obtain information for, + * NULL for all peers + * @param one_shot #GNUNET_YES to return the current state and then end (with NULL+NULL), + * #GNUNET_NO to monitor peers continuously + * @param mc function to call with the results + * @param mc_cls closure for @a mc + */ +struct GNUNET_TRANSPORT_MonitorContext * +GNUNET_TRANSPORT_monitor (const struct GNUNET_CONFIGURATION_Handle *cfg, + const struct GNUNET_PeerIdentity *peer, + int one_shot, + GNUNET_TRANSPORT_MonitorCallback mc, + void *mc_cls); + + +/** + * Cancel request to monitor peers + * + * @param pmc handle for the request to cancel + */ +void +GNUNET_TRANSPORT_monitor_cancel (struct GNUNET_TRANSPORT_MonitorContext *pmc); + + +#if 0 /* keep Emacsens' auto-indent happy */ +{ +#endif +#ifdef __cplusplus +} +#endif + +/* ifndef GNUNET_TRANSPORT_MONITOR_SERVICE_H */ +#endif + +/** @} */ /* end of group */ + +/* end of gnunet_transport_monitor_service.h */ -- 2.25.1