X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_cadet_service.h;h=fd838df8d63d998911901478f8c22754c50fd532;hb=abdec5e11ff11bb10d32c013e11344a54786f80f;hp=a0d28b53154167b5185286075858f4cc06a93f71;hpb=c14ff64b5c9ca4cfc5004e30622499cc782694c5;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_cadet_service.h b/src/include/gnunet_cadet_service.h index a0d28b531..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. - Copyright (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 @@ -18,10 +18,19 @@ 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 @@ -40,7 +49,7 @@ extern "C" /** * Version number of GNUnet-cadet API. */ -#define GNUNET_CADET_VERSION 0x00000003 +#define GNUNET_CADET_VERSION 0x00000004 /** @@ -54,13 +63,9 @@ struct GNUNET_CADET_Handle; struct GNUNET_CADET_Channel; /** - * Hash to be used in Cadet communication. Only 256 bits needed, - * instead of the 512 from `struct GNUNET_HashCode`. + * Opaque handle to a port. */ -struct GNUNET_CADET_Hash -{ - unsigned char bits[256 / 8]; -}; +struct GNUNET_CADET_Port; /** @@ -88,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. @@ -171,7 +176,7 @@ typedef void * (GNUNET_CADET_InboundChannelNotificationHandler) (void *cls, struct GNUNET_CADET_Channel *channel, const struct GNUNET_PeerIdentity *initiator, - uint32_t port, + const struct GNUNET_HashCode *port, enum GNUNET_CADET_ChannelOption options); @@ -199,9 +204,6 @@ typedef void * @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. * It is called immediately if #GNUNET_CADET_channel_destroy * is called on the channel. @@ -209,8 +211,6 @@ typedef void * 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) @@ -218,10 +218,8 @@ typedef void 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); + const struct GNUNET_CADET_MessageHandler *handlers); /** @@ -235,6 +233,30 @@ GNUNET_CADET_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, 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. @@ -246,17 +268,17 @@ 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 */ struct GNUNET_CADET_Channel * GNUNET_CADET_channel_create (struct GNUNET_CADET_Handle *h, - void *channel_ctx, - const struct GNUNET_PeerIdentity *peer, - uint32_t port, - enum GNUNET_CADET_ChannelOption options); + void *channel_ctx, + const struct GNUNET_PeerIdentity *peer, + const struct GNUNET_HashCode *port, + enum GNUNET_CADET_ChannelOption options); /** @@ -300,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, + ...); /** @@ -340,6 +363,10 @@ 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 @@ -385,10 +412,10 @@ 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); + 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 @@ -429,7 +456,7 @@ typedef void int tunnel, int neighbor, unsigned int n_paths, - struct GNUNET_PeerIdentity *paths); + const struct GNUNET_PeerIdentity *paths); /** @@ -454,6 +481,33 @@ typedef void 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 * has established, o`r is trying to establish. @@ -472,8 +526,8 @@ typedef void const struct GNUNET_PeerIdentity *peer, unsigned int n_channels, unsigned int n_connections, - uint32_t *channels, - struct GNUNET_CADET_Hash *connections, + const struct GNUNET_CADET_ChannelTunnelNumber *channels, + const struct GNUNET_CADET_ConnectionTunnelIdentifier *connections, unsigned int estate, unsigned int cstate); @@ -492,7 +546,7 @@ typedef void void GNUNET_CADET_get_channel (struct GNUNET_CADET_Handle *h, struct GNUNET_PeerIdentity *peer, - uint32_t channel_number, + uint32_t /* UGH */ channel_number, GNUNET_CADET_ChannelCB callback, void *callback_cls); @@ -625,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 @@ -634,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 */