X-Git-Url: https://git.librecmc.org/?a=blobdiff_plain;f=src%2Finclude%2Fgnunet_cadet_service.h;h=fd838df8d63d998911901478f8c22754c50fd532;hb=abdec5e11ff11bb10d32c013e11344a54786f80f;hp=5d6e1c1d1b9fdc65450253609617105e9aabdb91;hpb=356cd09ec4f7d2c02300d5eae8bec8e6b8e49635;p=oweals%2Fgnunet.git diff --git a/src/include/gnunet_cadet_service.h b/src/include/gnunet_cadet_service.h index 5d6e1c1d1..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); /** @@ -697,43 +697,63 @@ GC_u2h (uint32_t port); /******************************************************************************/ /** - * Method called whenever a given peer connects in MQ-based CADET. + * 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 channel. It's given to: - * - The @a GNUNET_CADET_DisconnectEventHandler when the channel dies. - * - Each the @a GNUNET_MQ_MessageCallback for each message. + * @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) (struct GNUNET_CADET_Channel *channel, +(*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 @a GNUNET_CADET_channel_destroy. - * It must NOT call @a GNUNET_CADET_channel_destroy on the channel. + * 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. * - * FIXME: what about MQ-pending transmissions? - * * @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); +(*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 * @@ -746,20 +766,22 @@ GNUNET_CADET_connecT (const struct GNUNET_CONFIGURATION_Handle *cfg); * @param h CADET handle. * @param port Hash identifying the port. * @param connects Function called when an incoming channel is connected. - * FIXME: add connects_cls to give the incoming handler a closure? + * @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. * @@ -769,14 +791,17 @@ GNUNET_CADET_open_porT (struct GNUNET_CADET_Handle *h, * * @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 * @@ -785,18 +810,16 @@ GNUNET_CADET_channel_creatE (struct GNUNET_CADET_Handle *h, 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 peer. + * Obtain the message queue for a connected channel. * * @param channel The channel handle from which to get the MQ. - * - * @return NULL if @a channel is not yet connected. - * FIXME: provide an mq before a channel is connected? - * provide a callback to notify a client a channel connected? + * @return The message queue of the channel. */ struct GNUNET_MQ_Handle * GNUNET_CADET_get_mq (const struct GNUNET_CADET_Channel *channel);