X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_cadet_service.h;h=fd838df8d63d998911901478f8c22754c50fd532;hb=abdec5e11ff11bb10d32c013e11344a54786f80f;hp=7090d44108e6fcdfb7e453716ff4cd822c538dee;hpb=dfde8ea01a08a32340a47df29ffc2571c031488b;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_cadet_service.h b/src/include/gnunet_cadet_service.h index 7090d4410..fd838df8d 100644 --- a/src/include/gnunet_cadet_service.h +++ b/src/include/gnunet_cadet_service.h @@ -456,7 +456,7 @@ typedef void int tunnel, int neighbor, unsigned int n_paths, - struct GNUNET_PeerIdentity *paths); + const struct GNUNET_PeerIdentity *paths); /** @@ -497,7 +497,12 @@ struct GNUNET_CADET_ChannelTunnelNumber { /** * Which number does this channel have that uniquely identfies - * it within its tunnel? + * 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; }; @@ -687,6 +692,145 @@ 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