X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_cadet_service.h;h=fd838df8d63d998911901478f8c22754c50fd532;hb=abdec5e11ff11bb10d32c013e11344a54786f80f;hp=e69c9eaa71c642ce4642d32b8d0baba4e67adde7;hpb=d675b12cbb54900e6ac6e63ced5e06795996cb97;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_cadet_service.h b/src/include/gnunet_cadet_service.h index e69c9eaa7..fd838df8d 100644 --- a/src/include/gnunet_cadet_service.h +++ b/src/include/gnunet_cadet_service.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet. - (C) 2009 - 2013 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 @@ -14,16 +14,24 @@ 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_cadet_service.h - * @brief cadet service; establish channels to distant peers * @author Christian Grothoff + * @author Bart Polot + * + * @file + * CADET service; establish channels to distant peers + * + * @defgroup cadet CADET service + * Confidential Ad-hoc Decentralized End-to-End Transport + * + * @see [Documentation](https://gnunet.org/cadet-subsystem) + * @see [Paper](https://gnunet.org/cadet) + * + * @{ */ - #ifndef GNUNET_CADET_SERVICE_H #define GNUNET_CADET_SERVICE_H @@ -41,7 +49,7 @@ extern "C" /** * Version number of GNUnet-cadet API. */ -#define GNUNET_CADET_VERSION 0x00000003 +#define GNUNET_CADET_VERSION 0x00000004 /** @@ -55,18 +63,14 @@ struct GNUNET_CADET_Handle; struct GNUNET_CADET_Channel; /** - * Hash to be used in Cadet communication. Only 256 bits needed, - * instead of the 512 from @c GNUNET_HashCode. - * + * Opaque handle to a port. */ -struct GNUNET_CADET_Hash -{ - unsigned char bits[256 / 8]; -}; +struct GNUNET_CADET_Port; + /** - * Channel options. - * Second line indicates filed in the CadetChannelInfo union carrying the answer. + * Channel options. Second line indicates filed in the + * CadetChannelInfo union carrying the answer. */ enum GNUNET_CADET_ChannelOption { @@ -89,9 +93,9 @@ enum GNUNET_CADET_ChannelOption /** * Enable out of order delivery of messages. - * Yes/No. + * Set bit for out-of-order delivery. */ - GNUNET_CADET_OPTION_OOORDER = 0x4, + GNUNET_CADET_OPTION_OUT_OF_ORDER = 0x4, /** * Who is the peer at the other end of the channel. @@ -118,10 +122,11 @@ enum GNUNET_CADET_ChannelOption * @return #GNUNET_OK to keep the channel open, * #GNUNET_SYSERR to close it (signal serious error). */ -typedef int (*GNUNET_CADET_MessageCallback) (void *cls, - struct GNUNET_CADET_Channel *channel, - void **channel_ctx, - const struct GNUNET_MessageHeader *message); +typedef int +(*GNUNET_CADET_MessageCallback) (void *cls, + struct GNUNET_CADET_Channel *channel, + void **channel_ctx, + const struct GNUNET_MessageHeader *message); /** @@ -131,7 +136,7 @@ typedef int (*GNUNET_CADET_MessageCallback) (void *cls, struct GNUNET_CADET_MessageHandler { /** - * Function to call for messages of "type". + * Function to call for messages of type @e type. */ GNUNET_CADET_MessageCallback callback; @@ -167,21 +172,18 @@ struct GNUNET_CADET_MessageHandler * @return initial channel context for the channel * (can be NULL -- that's not an error) */ -typedef void *(GNUNET_CADET_InboundChannelNotificationHandler) (void *cls, - struct - GNUNET_CADET_Channel - * channel, - const struct - GNUNET_PeerIdentity - * initiator, - uint32_t port, - enum GNUNET_CADET_ChannelOption - options); +typedef void * +(GNUNET_CADET_InboundChannelNotificationHandler) (void *cls, + struct GNUNET_CADET_Channel *channel, + const struct GNUNET_PeerIdentity *initiator, + const struct GNUNET_HashCode *port, + enum GNUNET_CADET_ChannelOption options); /** * Function called whenever a channel is destroyed. Should clean up - * any associated state. + * any associated state, including cancelling any pending transmission on this + * channel. * * It must NOT call #GNUNET_CADET_channel_destroy on the channel. * @@ -190,10 +192,10 @@ typedef void *(GNUNET_CADET_InboundChannelNotificationHandler) (void *cls, * @param channel_ctx place where local state associated * with the channel is stored */ -typedef void (GNUNET_CADET_ChannelEndHandler) (void *cls, - const struct GNUNET_CADET_Channel * - channel, - void *channel_ctx); +typedef void +(GNUNET_CADET_ChannelEndHandler) (void *cls, + const struct GNUNET_CADET_Channel *channel, + void *channel_ctx); /** @@ -202,28 +204,22 @@ typedef void (GNUNET_CADET_ChannelEndHandler) (void *cls, * @param cfg Configuration to use. * @param cls Closure for the various callbacks that follow (including * handlers in the handlers array). - * @param new_channel Function called when an *incoming* channel is created. - * Can be NULL if no inbound channels are desired. - * See @a ports. - * @param cleaner Function called when a channel is destroyed by the remote peer. - * It is NOT called if #GNUNET_CADET_channel_destroy is called on - * the channel. + * @param cleaner Function called when a channel is destroyed. + * It is called immediately if #GNUNET_CADET_channel_destroy + * is called on the channel. * @param handlers Callbacks for messages we care about, NULL-terminated. Each * one must call #GNUNET_CADET_receive_done on the channel to * receive the next message. Messages of a type that is not * in the handlers array are ignored if received. - * @param ports NULL or 0-terminated array of port numbers for incoming channels. - * See @a new_channel. * * @return handle to the cadet service NULL on error * (in this case, init is never called) */ struct GNUNET_CADET_Handle * -GNUNET_CADET_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, void *cls, - GNUNET_CADET_InboundChannelNotificationHandler new_channel, - GNUNET_CADET_ChannelEndHandler cleaner, - const struct GNUNET_CADET_MessageHandler *handlers, - const uint32_t *ports); +GNUNET_CADET_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, + void *cls, + GNUNET_CADET_ChannelEndHandler cleaner, + const struct GNUNET_CADET_MessageHandler *handlers); /** @@ -237,6 +233,30 @@ GNUNET_CADET_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, void *cls, void GNUNET_CADET_disconnect (struct GNUNET_CADET_Handle *handle); +/** + * Open a port to receive incomming channels. + * + * @param h CADET handle. + * @param port Hash representing the port number. + * @param new_channel Function called when an channel is received. + * @param new_channel_cls Closure for @a new_channel. + * + * @return Port handle. + */ +struct GNUNET_CADET_Port * +GNUNET_CADET_open_port (struct GNUNET_CADET_Handle *h, + const struct GNUNET_HashCode *port, + GNUNET_CADET_InboundChannelNotificationHandler new_channel, + void *new_channel_cls); + +/** + * Close a port opened with @a GNUNET_CADET_open_port. + * The @a new_channel callback will no longer be called. + * + * @param p Port handle. + */ +void +GNUNET_CADET_close_port (struct GNUNET_CADET_Port *p); /** * Create a new channel towards a remote peer. @@ -248,7 +268,7 @@ GNUNET_CADET_disconnect (struct GNUNET_CADET_Handle *handle); * @param h cadet handle * @param channel_ctx client's channel context to associate with the channel * @param peer peer identity the channel should go to - * @param port Port number. + * @param port Port hash (port number). * @param options CadetOption flag field, with all desired option bits set to 1. * * @return handle to the channel @@ -257,7 +277,7 @@ struct GNUNET_CADET_Channel * GNUNET_CADET_channel_create (struct GNUNET_CADET_Handle *h, void *channel_ctx, const struct GNUNET_PeerIdentity *peer, - uint32_t port, + const struct GNUNET_HashCode *port, enum GNUNET_CADET_ChannelOption options); @@ -302,7 +322,8 @@ union GNUNET_CADET_ChannelInfo */ const union GNUNET_CADET_ChannelInfo * GNUNET_CADET_channel_get_info (struct GNUNET_CADET_Channel *channel, - enum GNUNET_CADET_ChannelOption option, ...); + enum GNUNET_CADET_ChannelOption option, + ...); /** @@ -342,11 +363,14 @@ GNUNET_CADET_notify_transmit_ready (struct GNUNET_CADET_Channel *channel, /** * Cancel the specified transmission-ready notification. * + * #DEPRECATED + * Since soon we will send immediately with mq (via request_data), + * there will be time or need to cancel a "pending" transmission. + * * @param th handle that was returned by "notify_transmit_ready". */ void -GNUNET_CADET_notify_transmit_ready_cancel (struct GNUNET_CADET_TransmitHandle - *th); +GNUNET_CADET_notify_transmit_ready_cancel (struct GNUNET_CADET_TransmitHandle *th); /** @@ -384,13 +408,14 @@ GNUNET_CADET_receive_done (struct GNUNET_CADET_Channel *channel); * @param dest_channel_number Local number for dest, if known. * @param public_channel_numbe Number for P2P, always known. */ -typedef void (*GNUNET_CADET_ChannelCB) (void *cls, - const struct GNUNET_PeerIdentity *root, - const struct GNUNET_PeerIdentity *dest, - uint32_t port, - uint32_t root_channel_number, - uint32_t dest_channel_number, - uint32_t public_channel_number); +typedef void +(*GNUNET_CADET_ChannelCB) (void *cls, + const struct GNUNET_PeerIdentity *root, + const struct GNUNET_PeerIdentity *dest, + uint32_t /* UGH */ port, + uint32_t /* ugh */ root_channel_number, + uint32_t /* ugh */ dest_channel_number, + uint32_t /* ugh */ public_channel_number); /** * Method called to retrieve information about all peers in CADET, called @@ -405,10 +430,12 @@ typedef void (*GNUNET_CADET_ChannelCB) (void *cls, * @param best_path How long is the best path? * (0 = unknown, 1 = ourselves, 2 = neighbor) */ -typedef void (*GNUNET_CADET_PeersCB) (void *cls, - const struct GNUNET_PeerIdentity *peer, - int tunnel, unsigned int n_paths, - unsigned int best_path); +typedef void +(*GNUNET_CADET_PeersCB) (void *cls, + const struct GNUNET_PeerIdentity *peer, + int tunnel, + unsigned int n_paths, + unsigned int best_path); /** * Method called to retrieve information about a specific peer @@ -420,15 +447,16 @@ typedef void (*GNUNET_CADET_PeersCB) (void *cls, * @param neighbor Is this a direct neighbor? #GNUNET_YES/#GNUNET_NO * @param n_paths Number of paths known towards peer. * @param paths Array of PEER_IDs representing all paths to reach the peer. - * Each path starts with the local peer. + * Each path starts with the first hop (local peer not included). * Each path ends with the destination peer (given in @c peer). */ -typedef void (*GNUNET_CADET_PeerCB) (void *cls, - const struct GNUNET_PeerIdentity *peer, - int tunnel, - int neighbor, - unsigned int n_paths, - struct GNUNET_PeerIdentity *paths); +typedef void +(*GNUNET_CADET_PeerCB) (void *cls, + const struct GNUNET_PeerIdentity *peer, + int tunnel, + int neighbor, + unsigned int n_paths, + const struct GNUNET_PeerIdentity *paths); /** @@ -444,14 +472,41 @@ typedef void (*GNUNET_CADET_PeerCB) (void *cls, * @param estate Encryption state. * @param cstate Connectivity state. */ -typedef void (*GNUNET_CADET_TunnelsCB) (void *cls, - const struct GNUNET_PeerIdentity *peer, - unsigned int channels, - unsigned int connections, - uint16_t estate, - uint16_t cstate); +typedef void +(*GNUNET_CADET_TunnelsCB) (void *cls, + const struct GNUNET_PeerIdentity *peer, + unsigned int channels, + unsigned int connections, + uint16_t estate, + uint16_t cstate); +/** + * Hash uniquely identifying a connection below a tunnel. + */ +struct GNUNET_CADET_ConnectionTunnelIdentifier +{ + struct GNUNET_ShortHashCode connection_of_tunnel; +}; + + +/** + * Number identifying a CADET channel within a tunnel. + */ +struct GNUNET_CADET_ChannelTunnelNumber +{ + /** + * Which number does this channel have that uniquely identfies + * it within its tunnel, in network byte order. + * + * Given two peers, both may initiate channels over the same tunnel. + * The @e cn must be greater or equal to 0x80000000 (high-bit set) + * for tunnels initiated with the peer that has the larger peer + * identity as compared using #GNUNET_CRYPTO_cmp_peer_identity(). + */ + uint32_t cn GNUNET_PACKED; +}; + /** * Method called to retrieve information about a specific tunnel the cadet peer @@ -466,14 +521,16 @@ typedef void (*GNUNET_CADET_TunnelsCB) (void *cls, * @param estate Encryption state. * @param cstate Connectivity state. */ -typedef void (*GNUNET_CADET_TunnelCB) (void *cls, - const struct GNUNET_PeerIdentity *peer, - unsigned int n_channels, - unsigned int n_connections, - uint32_t *channels, - struct GNUNET_CADET_Hash *connections, - unsigned int estate, - unsigned int cstate); +typedef void +(*GNUNET_CADET_TunnelCB) (void *cls, + const struct GNUNET_PeerIdentity *peer, + unsigned int n_channels, + unsigned int n_connections, + const struct GNUNET_CADET_ChannelTunnelNumber *channels, + const struct GNUNET_CADET_ConnectionTunnelIdentifier *connections, + unsigned int estate, + unsigned int cstate); + /** * Request information about a specific channel of the running cadet peer. @@ -488,10 +545,21 @@ typedef void (*GNUNET_CADET_TunnelCB) (void *cls, */ void GNUNET_CADET_get_channel (struct GNUNET_CADET_Handle *h, - struct GNUNET_PeerIdentity *peer, - uint32_t channel_number, - GNUNET_CADET_ChannelCB callback, - void *callback_cls); + struct GNUNET_PeerIdentity *peer, + uint32_t /* UGH */ channel_number, + GNUNET_CADET_ChannelCB callback, + void *callback_cls); + + +/** + * Request a debug dump on the service's STDERR. + * + * WARNING: unstable API, likely to change in the future! + * + * @param h cadet handle + */ +void +GNUNET_CADET_request_dump (struct GNUNET_CADET_Handle *h); /** @@ -510,8 +578,9 @@ GNUNET_CADET_get_channel (struct GNUNET_CADET_Handle *h, */ int GNUNET_CADET_get_peers (struct GNUNET_CADET_Handle *h, - GNUNET_CADET_PeersCB callback, - void *callback_cls); + GNUNET_CADET_PeersCB callback, + void *callback_cls); + /** * Cancel a peer info request. The callback will not be called (anymore). @@ -520,7 +589,7 @@ GNUNET_CADET_get_peers (struct GNUNET_CADET_Handle *h, * * @param h Cadet handle. * - * @return Closure given to GNUNET_CADET_get_peers. + * @return Closure that was given to #GNUNET_CADET_get_peers(). */ void * GNUNET_CADET_get_peers_cancel (struct GNUNET_CADET_Handle *h); @@ -546,6 +615,7 @@ GNUNET_CADET_get_peer (struct GNUNET_CADET_Handle *h, GNUNET_CADET_PeerCB callback, void *callback_cls); + /** * Request information about tunnels of the running cadet peer. * The callback will be called for every tunnel of the service. @@ -561,15 +631,16 @@ GNUNET_CADET_get_peer (struct GNUNET_CADET_Handle *h, */ int GNUNET_CADET_get_tunnels (struct GNUNET_CADET_Handle *h, - GNUNET_CADET_TunnelsCB callback, - void *callback_cls); + GNUNET_CADET_TunnelsCB callback, + void *callback_cls); + /** * Cancel a monitor request. The monitor callback will not be called. * * @param h Cadet handle. * - * @return Closure given to GNUNET_CADET_monitor, if any. + * @return Closure given to #GNUNET_CADET_get_tunnels(), if any. */ void * GNUNET_CADET_get_tunnels_cancel (struct GNUNET_CADET_Handle *h); @@ -591,9 +662,10 @@ GNUNET_CADET_get_tunnels_cancel (struct GNUNET_CADET_Handle *h); */ int GNUNET_CADET_get_tunnel (struct GNUNET_CADET_Handle *h, - const struct GNUNET_PeerIdentity *id, - GNUNET_CADET_TunnelCB callback, - void *callback_cls); + const struct GNUNET_PeerIdentity *id, + GNUNET_CADET_TunnelCB callback, + void *callback_cls); + /** * Create a message queue for a cadet channel. @@ -607,6 +679,158 @@ struct GNUNET_MQ_Handle * GNUNET_CADET_mq_create (struct GNUNET_CADET_Channel *channel); +/** + * Transitional function to convert an unsigned int port to a hash value. + * WARNING: local static value returned, NOT reentrant! + * WARNING: do not use this function for new code! + * + * @param port Numerical port (unsigned int format). + * + * @return A GNUNET_HashCode usable for the new CADET API. + */ +const struct GNUNET_HashCode * +GC_u2h (uint32_t port); + + +/******************************************************************************/ +/******************************* MQ-BASED API *********************************/ +/******************************************************************************/ + +/** + * Method called whenever a peer connects to a port in MQ-based CADET. + * + * @param cls Closure from #GNUNET_CADET_open_porT. + * @param channel New handle to the channel. + * @param source Peer that started this channel. + * @return Closure for the incoming @a channel. It's given to: + * - The #GNUNET_CADET_DisconnectEventHandler (given to + * #GNUNET_CADET_open_porT) when the channel dies. + * - Each the #GNUNET_MQ_MessageCallback handlers for each message + * received on the @a channel. + */ +typedef void * +(*GNUNET_CADET_ConnectEventHandler) (void *cls, + struct GNUNET_CADET_Channel *channel, + const struct GNUNET_PeerIdentity *source); + + +/** + * Function called whenever an MQ-channel is destroyed, even if the destruction + * was requested by #GNUNET_CADET_channel_destroy. + * It must NOT call #GNUNET_CADET_channel_destroy on the channel. + * + * It should clean up any associated state, including cancelling any pending + * transmission on this channel. + * + * @param cls Channel closure. + * @param channel Connection to the other end (henceforth invalid). + */ +typedef void +(*GNUNET_CADET_DisconnectEventHandler) (void *cls, + const struct GNUNET_CADET_Channel *channel); + + +/** + * Function called whenever an MQ-channel's transmission window size changes. + * + * The first callback in an outgoing channel will be with a non-zero value + * and will mean the channel is connected to the destination. + * + * For an incoming channel it will be called immediately after the + * #GNUNET_CADET_ConnectEventHandler, also with a non-zero value. + * + * @param cls Channel closure. + * @param channel Connection to the other end --- FIXME: drop? + * @param window_size New window size. If the is more messages than buffer size + * this value will be negative. -- FIXME: make unsigned, we never call negative? + */ +typedef void +(*GNUNET_CADET_WindowSizeEventHandler) (void *cls, + const struct GNUNET_CADET_Channel *channel, + int window_size); + + +/** + * Connect to the MQ-based cadet service. + * + * @param cfg Configuration to use. + * @return Handle to the cadet service NULL on error. + */ +struct GNUNET_CADET_Handle * +GNUNET_CADET_connecT (const struct GNUNET_CONFIGURATION_Handle *cfg); + + +/** + * Open a port to receive incomming MQ-based channels. + * + * @param h CADET handle. + * @param port Hash identifying the port. + * @param connects Function called when an incoming channel is connected. + * @param connects_cls Closure for the @a connects handler. + * @param window_changes Function called when the transmit window size changes. + * Can be NULL. + * @param disconnects Function called when a channel is disconnected. + * @param handlers Callbacks for messages we care about, NULL-terminated. + * @return Port handle. + */ +struct GNUNET_CADET_Port * +GNUNET_CADET_open_porT (struct GNUNET_CADET_Handle *h, + const struct GNUNET_HashCode *port, + GNUNET_CADET_ConnectEventHandler connects, + void *connects_cls, + GNUNET_CADET_WindowSizeEventHandler window_changes, + GNUNET_CADET_DisconnectEventHandler disconnects, + const struct GNUNET_MQ_MessageHandler *handlers); + +/** + * Create a new channel towards a remote peer. + * + * If the destination port is not open by any peer or the destination peer + * does not accept the channel, #GNUNET_CADET_ChannelEndHandler will be called + * for this channel. + * + * @param h CADET handle. + * @param channel_cls Closure for the channel. It's given to: + * - The management handler @a window_changes. + * - The disconnect handler @a disconnects + * - Each message type callback in @a handlers + * @param destination Peer identity the channel should go to. + * @param port Identification of the destination port. + * @param options CadetOption flag field, with all desired option bits set to 1. + * @param window_changes Function called when the transmit window size changes. + * Can be NULL if this data is of no interest. + * TODO Not yet implemented. + * @param disconnects Function called when the channel is disconnected. + * @param handlers Callbacks for messages we care about, NULL-terminated. + * @return Handle to the channel. + */ +struct GNUNET_CADET_Channel * +GNUNET_CADET_channel_creatE (struct GNUNET_CADET_Handle *h, + void *channel_cls, + const struct GNUNET_PeerIdentity *destination, + const struct GNUNET_HashCode *port, + enum GNUNET_CADET_ChannelOption options, + GNUNET_CADET_WindowSizeEventHandler window_changes, + GNUNET_CADET_DisconnectEventHandler disconnects, + const struct GNUNET_MQ_MessageHandler *handlers); + + +/** + * Obtain the message queue for a connected channel. + * + * @param channel The channel handle from which to get the MQ. + * @return The message queue of the channel. + */ +struct GNUNET_MQ_Handle * +GNUNET_CADET_get_mq (const struct GNUNET_CADET_Channel *channel); + + +/******************************************************************************/ +/******************************* MQ-BASED API *********************************/ +/******************************************************************************/ + + + #if 0 /* keep Emacsens' auto-indent happy */ { #endif @@ -616,4 +840,7 @@ GNUNET_CADET_mq_create (struct GNUNET_CADET_Channel *channel); /* ifndef GNUNET_CADET_SERVICE_H */ #endif + +/** @} */ /* end of group */ + /* end of gnunet_cadet_service.h */