From b2c3389e8de9d24794d4b4bb499e14408101d433 Mon Sep 17 00:00:00 2001 From: Bart Polot Date: Tue, 31 Jan 2017 02:57:46 +0100 Subject: [PATCH] CADET MQ API documentation improvements --- src/include/gnunet_cadet_service.h | 42 ++++++++++++++---------------- 1 file changed, 19 insertions(+), 23 deletions(-) diff --git a/src/include/gnunet_cadet_service.h b/src/include/gnunet_cadet_service.h index 99d74f223..1b3aac7c9 100644 --- a/src/include/gnunet_cadet_service.h +++ b/src/include/gnunet_cadet_service.h @@ -697,26 +697,26 @@ 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 @a GNUNET_CADET_open_porT. + * @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) (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. @@ -728,7 +728,6 @@ typedef void (*GNUNET_CADET_DisconnectEventHandler) (void *cls, const struct GNUNET_CADET_Channel *channel); - /** * Function called whenever an MQ-channel's transmission window size changes. * @@ -736,29 +735,27 @@ typedef void * and will mean the channel is connected to the destination. * * For an incoming channel it will be called immediately after the - * @a GNUNET_CADET_ConnectEventHandler, also with a non-zero value. + * #GNUNET_CADET_ConnectEventHandler, also with a non-zero value. * * @param cls Channel closure. * @param channel Connection to the other end (henceforth invalid). - * @param window_size New window size. + * @param window_size New window size. If the is more messages than buffer size + * this value will be 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. * @@ -767,21 +764,20 @@ GNUNET_CADET_connecT (const struct GNUNET_CONFIGURATION_Handle *cfg); * @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, + 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. * @@ -791,15 +787,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 * @@ -812,13 +810,11 @@ GNUNET_CADET_channel_creatE (struct GNUNET_CADET_Handle *h, 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. + * @return The message queue of the channel. */ struct GNUNET_MQ_Handle * GNUNET_CADET_get_mq (const struct GNUNET_CADET_Channel *channel); -- 2.25.1