X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_cadet_service.h;h=fd838df8d63d998911901478f8c22754c50fd532;hb=abdec5e11ff11bb10d32c013e11344a54786f80f;hp=264bc315401d5ec5b15f15d673dbd4abf2bf72c0;hpb=bb5fe91d23b0938baa3c4f0e92a83df659df216a;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_cadet_service.h b/src/include/gnunet_cadet_service.h index 264bc3154..fd838df8d 100644 --- a/src/include/gnunet_cadet_service.h +++ b/src/include/gnunet_cadet_service.h @@ -49,7 +49,7 @@ extern "C" /** * Version number of GNUnet-cadet API. */ -#define GNUNET_CADET_VERSION 0x00000003 +#define GNUNET_CADET_VERSION 0x00000004 /** @@ -63,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; /** @@ -97,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. @@ -180,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); @@ -208,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. @@ -218,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) @@ -227,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); /** @@ -244,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. @@ -255,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); /** @@ -309,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, + ...); /** @@ -349,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 @@ -394,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 @@ -438,7 +456,7 @@ typedef void int tunnel, int neighbor, unsigned int n_paths, - struct GNUNET_PeerIdentity *paths); + const struct GNUNET_PeerIdentity *paths); /** @@ -463,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. @@ -481,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); @@ -501,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); @@ -634,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