From fdf369790b040af2ab491e80dab8eb1bb95151a2 Mon Sep 17 00:00:00 2001 From: Christian Grothoff Date: Sun, 2 Feb 2014 17:25:33 +0000 Subject: -indentation, doxygen --- src/include/gnunet_connection_lib.h | 19 ++-- src/include/gnunet_transport_service.h | 184 ++++++++++++++++----------------- 2 files changed, 100 insertions(+), 103 deletions(-) diff --git a/src/include/gnunet_connection_lib.h b/src/include/gnunet_connection_lib.h index ed9ca9167..0051e5fb5 100644 --- a/src/include/gnunet_connection_lib.h +++ b/src/include/gnunet_connection_lib.h @@ -273,18 +273,19 @@ GNUNET_CONNECTION_receive_cancel (struct GNUNET_CONNECTION_Handle *connection); /** - * Function called to notify a client about the connection - * begin ready to queue more data. "buf" will be - * NULL and "size" zero if the connection was closed for - * writing in the meantime. + * Function called to notify a client about the connection begin ready + * to queue more data. @a buf will be NULL and @a size zero if the + * connection was closed for writing in the meantime. * * @param cls closure - * @param size number of bytes available in buf + * @param size number of bytes available in @a buf * @param buf where the callee should write the message - * @return number of bytes written to buf + * @return number of bytes written to @a buf */ -typedef size_t (*GNUNET_CONNECTION_TransmitReadyNotify) (void *cls, size_t size, - void *buf); +typedef size_t +(*GNUNET_CONNECTION_TransmitReadyNotify) (void *cls, + size_t size, + void *buf); /** @@ -298,7 +299,7 @@ struct GNUNET_CONNECTION_TransmitHandle; * are free in the transmission buffer. May call the notify * method immediately if enough space is available. Note that * this function will abort if "size" is greater than - * GNUNET_SERVER_MAX_MESSAGE_SIZE. + * #GNUNET_SERVER_MAX_MESSAGE_SIZE. * * Note that "notify" will be called either when enough * buffer space is available OR when the connection is destroyed. diff --git a/src/include/gnunet_transport_service.h b/src/include/gnunet_transport_service.h index 989a33d16..7b94f2209 100644 --- a/src/include/gnunet_transport_service.h +++ b/src/include/gnunet_transport_service.h @@ -1,6 +1,6 @@ /* This file is part of GNUnet. - (C) 2009, 2010, 2011 Christian Grothoff (and other contributing authors) + (C) 2009-2014 Christian Grothoff (and other contributing authors) GNUnet is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published @@ -206,6 +206,7 @@ enum GNUNET_TRANSPORT_PeerState GNUNET_TRANSPORT_PS_DISCONNECT_FINISHED }; + /** * Current state of a validation process */ @@ -244,9 +245,10 @@ enum GNUNET_TRANSPORT_ValidationState * * The validation entry is getting removed due to a failed validation */ - GNUNET_TRANSPORT_VS_REMOVE, + GNUNET_TRANSPORT_VS_REMOVE }; + /** * Function called by the transport for each received message. * @@ -254,14 +256,12 @@ enum GNUNET_TRANSPORT_ValidationState * @param peer (claimed) identity of the other peer * @param message the message * @param ats performance data - * @param ats_count number of entries in ats + * @param ats_count number of entries in @a ats */ -typedef void (*GNUNET_TRANSPORT_ReceiveCallback) (void *cls, - const struct - GNUNET_PeerIdentity * peer, - const struct - GNUNET_MessageHeader * - message); +typedef void +(*GNUNET_TRANSPORT_ReceiveCallback) (void *cls, + const struct GNUNET_PeerIdentity *peer, + const struct GNUNET_MessageHeader *message); /** @@ -277,11 +277,11 @@ struct GNUNET_TRANSPORT_Handle; * @param cls closure * @param peer the peer that connected * @param ats performance data - * @param ats_count number of entries in ats (excluding 0-termination) + * @param ats_count number of entries in @a ats (excluding 0-termination) */ -typedef void (*GNUNET_TRANSPORT_NotifyConnect) (void *cls, - const struct GNUNET_PeerIdentity - * peer); +typedef void +(*GNUNET_TRANSPORT_NotifyConnect) (void *cls, + const struct GNUNET_PeerIdentity *peer); /** * Function called to notify transport users that another @@ -290,9 +290,9 @@ typedef void (*GNUNET_TRANSPORT_NotifyConnect) (void *cls, * @param cls closure * @param peer the peer that disconnected */ -typedef void (*GNUNET_TRANSPORT_NotifyDisconnect) (void *cls, - const struct - GNUNET_PeerIdentity * peer); +typedef void +(*GNUNET_TRANSPORT_NotifyDisconnect) (void *cls, + const struct GNUNET_PeerIdentity *peer); /** @@ -300,11 +300,12 @@ typedef void (*GNUNET_TRANSPORT_NotifyDisconnect) (void *cls, * * * @param cls closure - * @param result GNUNET_OK if message was transmitted to transport service - * GNUNET_SYSERR if message was not transmitted to transport service + * @param result #GNUNET_OK if message was transmitted to transport service + * #GNUNET_SYSERR if message was not transmitted to transport service */ -typedef void (*GNUNET_TRANSPORT_TryConnectCallback) (void *cls, - const int result); +typedef void +(*GNUNET_TRANSPORT_TryConnectCallback) (void *cls, + const int result); /** @@ -317,14 +318,15 @@ typedef void (*GNUNET_TRANSPORT_TryConnectCallback) (void *cls, * @param address NULL on error or end of iteration, * otherwise 0-terminated printable UTF-8 string */ -typedef void (*GNUNET_TRANSPORT_AddressToStringCallback) (void *cls, - const char *address); +typedef void +(*GNUNET_TRANSPORT_AddressToStringCallback) (void *cls, + const char *address); /** * Function to call with information about a peer * - * If one_shot was set to GNUNET_YES to iterate over all peers once, + * If one_shot was set to #GNUNET_YES to iterate over all peers once, * a final call with NULL for peer and address will follow when done. * In this case state and timeout do not contain valid values. * @@ -339,11 +341,12 @@ typedef void (*GNUNET_TRANSPORT_AddressToStringCallback) (void *cls, * @param state current state this peer is in * @param state_timeout timeout for the current state of the peer */ -typedef void (*GNUNET_TRANSPORT_PeerIterateCallback) (void *cls, - const struct GNUNET_PeerIdentity *peer, - const struct GNUNET_HELLO_Address *address, - enum GNUNET_TRANSPORT_PeerState state, - struct GNUNET_TIME_Absolute state_timeout); +typedef void +(*GNUNET_TRANSPORT_PeerIterateCallback) (void *cls, + const struct GNUNET_PeerIdentity *peer, + const struct GNUNET_HELLO_Address *address, + enum GNUNET_TRANSPORT_PeerState state, + struct GNUNET_TIME_Absolute state_timeout); /** @@ -365,14 +368,14 @@ typedef void (*GNUNET_TRANSPORT_PeerIterateCallback) (void *cls, * @param next_validation time of the next validation operation * */ -typedef void (*GNUNET_TRANSPORT_ValidationIterateCallback) (void *cls, - const struct GNUNET_PeerIdentity *peer, - const struct GNUNET_HELLO_Address *address, - struct GNUNET_TIME_Absolute last_validation, - struct GNUNET_TIME_Absolute valid_until, - struct GNUNET_TIME_Absolute next_validation, - enum GNUNET_TRANSPORT_ValidationState state); - +typedef void +(*GNUNET_TRANSPORT_ValidationIterateCallback) (void *cls, + const struct GNUNET_PeerIdentity *peer, + const struct GNUNET_HELLO_Address *address, + struct GNUNET_TIME_Absolute last_validation, + struct GNUNET_TIME_Absolute valid_until, + struct GNUNET_TIME_Absolute next_validation, + enum GNUNET_TRANSPORT_ValidationState state); /** @@ -390,7 +393,8 @@ typedef void (*GNUNET_TRANSPORT_ValidationIterateCallback) (void *cls, */ struct GNUNET_TRANSPORT_Handle * GNUNET_TRANSPORT_connect (const struct GNUNET_CONFIGURATION_Handle *cfg, - const struct GNUNET_PeerIdentity *self, void *cls, + const struct GNUNET_PeerIdentity *self, + void *cls, GNUNET_TRANSPORT_ReceiveCallback rec, GNUNET_TRANSPORT_NotifyConnect nc, GNUNET_TRANSPORT_NotifyDisconnect nd); @@ -419,9 +423,9 @@ struct GNUNET_TRANSPORT_TryConnectHandle; * @param target who we should try to connect to * @param cb callback to be called when request was transmitted to transport * service - * @param cb_cls closure for the callback - * @return a GNUNET_TRANSPORT_TryConnectHandle handle or - * NULL on failure (cb will not be called) + * @param cb_cls closure for the callback @a cb + * @return a `struct GNUNET_TRANSPORT_TryConnectHandle` handle or + * NULL on failure (@a cb will not be called) */ struct GNUNET_TRANSPORT_TryConnectHandle * GNUNET_TRANSPORT_try_connect (struct GNUNET_TRANSPORT_Handle *handle, @@ -460,18 +464,19 @@ struct GNUNET_TRANSPORT_TransmitHandle; * notify with buf NULL and size 0)? * @param notify function to call when we are ready to * send such a message - * @param notify_cls closure for notify + * @param notify_cls closure for @a notify * @return NULL if someone else is already waiting to be notified * non-NULL if the notify callback was queued (can be used to cancel * using GNUNET_TRANSPORT_notify_transmit_ready_cancel) */ struct GNUNET_TRANSPORT_TransmitHandle * GNUNET_TRANSPORT_notify_transmit_ready (struct GNUNET_TRANSPORT_Handle *handle, - const struct GNUNET_PeerIdentity - *target, size_t size, uint32_t priority, + const struct GNUNET_PeerIdentity *target, + size_t size, + uint32_t priority, struct GNUNET_TIME_Relative timeout, - GNUNET_CONNECTION_TransmitReadyNotify - notify, void *notify_cls); + GNUNET_CONNECTION_TransmitReadyNotify notify, + void *notify_cls); /** @@ -480,10 +485,7 @@ GNUNET_TRANSPORT_notify_transmit_ready (struct GNUNET_TRANSPORT_Handle *handle, * @param th handle of the transmission notification request to cancel */ void -GNUNET_TRANSPORT_notify_transmit_ready_cancel (struct - GNUNET_TRANSPORT_TransmitHandle - *th); - +GNUNET_TRANSPORT_notify_transmit_ready_cancel (struct GNUNET_TRANSPORT_TransmitHandle *th); /** @@ -493,14 +495,13 @@ GNUNET_TRANSPORT_notify_transmit_ready_cancel (struct * @param cls closure * @param hello our updated HELLO */ -typedef void (*GNUNET_TRANSPORT_HelloUpdateCallback) (void *cls, - const struct - GNUNET_MessageHeader * - hello); +typedef void +(*GNUNET_TRANSPORT_HelloUpdateCallback) (void *cls, + const struct GNUNET_MessageHeader *hello); /** - * Handle to cancel a 'GNUNET_TRANSPORT_get_hello' operation. + * Handle to cancel a #GNUNET_TRANSPORT_get_hello() operation. */ struct GNUNET_TRANSPORT_GetHelloHandle; @@ -514,7 +515,7 @@ struct GNUNET_TRANSPORT_GetHelloHandle; */ int GNUNET_TRANSPORT_check_peer_connected (struct GNUNET_TRANSPORT_Handle *handle, - const struct GNUNET_PeerIdentity *peer); + const struct GNUNET_PeerIdentity *peer); /** @@ -522,14 +523,14 @@ GNUNET_TRANSPORT_check_peer_connected (struct GNUNET_TRANSPORT_Handle *handle, * * @param handle transport handle * @param peer the peer to set the metric for - * @param inbound set inbound direction (GNUNET_YES or GNUNET_NO) - * @param outbound set outbound direction (GNUNET_YES or GNUNET_NO) + * @param inbound set inbound direction (#GNUNET_YES or #GNUNET_NO) + * @param outbound set outbound direction (#GNUNET_YES or #GNUNET_NO) * @param ats the metric as ATS information * @param ats_count the number of metrics * * Supported ATS values: - * GNUNET_ATS_QUALITY_NET_DELAY (value in ms) - * GNUNET_ATS_QUALITY_NET_DISTANCE (value in count(hops)) + * #GNUNET_ATS_QUALITY_NET_DELAY (value in ms) + * #GNUNET_ATS_QUALITY_NET_DISTANCE (value in count(hops)) * * Example * To enforce a delay of 10 ms for peer p1 in sending direction use: @@ -558,7 +559,7 @@ GNUNET_TRANSPORT_set_traffic_metric (struct GNUNET_TRANSPORT_Handle *handle, * * @param handle connection to transport service * @param rec function to call with the HELLO - * @param rec_cls closure for rec + * @param rec_cls closure for @a rec * @return handle to cancel the operation */ struct GNUNET_TRANSPORT_GetHelloHandle * @@ -584,8 +585,8 @@ GNUNET_TRANSPORT_get_hello_cancel (struct GNUNET_TRANSPORT_GetHelloHandle *ghh); * @param handle connection to transport service * @param hello the hello message * @param cont continuation to call when HELLO has been sent, - * tc reason GNUNET_SCHEDULER_REASON_TIMEOUT for fail - * tc reasong GNUNET_SCHEDULER_REASON_READ_READY for success + * tc reason #GNUNET_SCHEDULER_REASON_TIMEOUT for fail + * tc reasong #GNUNET_SCHEDULER_REASON_READ_READY for success * @param cls closure for continuation * @return a GNUNET_TRANSPORT_OfferHelloHandle handle or NULL on failure, * in case of failure cont will not be called @@ -600,7 +601,7 @@ GNUNET_TRANSPORT_offer_hello (struct GNUNET_TRANSPORT_Handle *handle, /** * Cancel the request to transport to offer the HELLO message * - * @param ohh the GNUNET_TRANSPORT_OfferHelloHandle to cancel + * @param ohh the `struct GNUNET_TRANSPORT_OfferHelloHandle` to cancel */ void GNUNET_TRANSPORT_offer_hello_cancel (struct GNUNET_TRANSPORT_OfferHelloHandle *ohh); @@ -621,17 +622,16 @@ struct GNUNET_TRANSPORT_AddressToStringContext; * (otherwise do reverse DNS lookup) * @param timeout how long is the lookup allowed to take at most * @param aluc function to call with the results - * @param aluc_cls closure for aluc + * @param aluc_cls closure for @a aluc * @return handle to cancel the operation, NULL on error */ struct GNUNET_TRANSPORT_AddressToStringContext * -GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle - *cfg, +GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle *cfg, const struct GNUNET_HELLO_Address *address, int numeric, struct GNUNET_TIME_Relative timeout, - GNUNET_TRANSPORT_AddressToStringCallback - aluc, void *aluc_cls); + GNUNET_TRANSPORT_AddressToStringCallback aluc, + void *aluc_cls); /** @@ -640,9 +640,8 @@ GNUNET_TRANSPORT_address_to_string (const struct GNUNET_CONFIGURATION_Handle * @param pic the context handle */ void -GNUNET_TRANSPORT_address_to_string_cancel (struct - GNUNET_TRANSPORT_AddressToStringContext - *pic); +GNUNET_TRANSPORT_address_to_string_cancel (struct GNUNET_TRANSPORT_AddressToStringContext *pic); + /** * Convert a transport state to a human readable string. @@ -657,7 +656,7 @@ GNUNET_TRANSPORT_ps2s (enum GNUNET_TRANSPORT_PeerState state); * Check if a state is defined as connected * * @param state the state value - * @return GNUNET_YES or GNUNET_NO + * @return #GNUNET_YES or #GNUNET_NO */ int GNUNET_TRANSPORT_is_connected (enum GNUNET_TRANSPORT_PeerState state); @@ -694,15 +693,14 @@ GNUNET_TRANSPORT_vs2s (enum GNUNET_TRANSPORT_ValidationState state); * @param cfg configuration to use * @param peer a specific peer identity to obtain information for, * NULL for all peers - * @param one_shot GNUNET_YES to return the current state and then end (with NULL+NULL), - * GNUNET_NO to monitor peers continuously + * @param one_shot #GNUNET_YES to return the current state and then end (with NULL+NULL), + * #GNUNET_NO to monitor peers continuously * @param timeout how long is the lookup allowed to take at most * @param peer_callback function to call with the results - * @param peer_callback_cls closure for peer_address_callback + * @param peer_callback_cls closure for @a peer_callback */ struct GNUNET_TRANSPORT_PeerMonitoringContext * -GNUNET_TRANSPORT_monitor_peers (const struct - GNUNET_CONFIGURATION_Handle *cfg, +GNUNET_TRANSPORT_monitor_peers (const struct GNUNET_CONFIGURATION_Handle *cfg, const struct GNUNET_PeerIdentity *peer, int one_shot, struct GNUNET_TIME_Relative timeout, @@ -719,7 +717,6 @@ void GNUNET_TRANSPORT_monitor_peers_cancel (struct GNUNET_TRANSPORT_PeerMonitoringContext *pic); - /** * Return information about pending address validation operations for a specific * or all peers @@ -727,20 +724,19 @@ GNUNET_TRANSPORT_monitor_peers_cancel (struct GNUNET_TRANSPORT_PeerMonitoringCon * @param cfg configuration to use * @param peer a specific peer identity to obtain validation entries for, * NULL for all peers - * @param one_shot GNUNET_YES to return all entries and then end (with NULL+NULL), - * GNUNET_NO to monitor validation entries continuously + * @param one_shot #GNUNET_YES to return all entries and then end (with NULL+NULL), + * #GNUNET_NO to monitor validation entries continuously * @param timeout how long is the lookup allowed to take at most * @param validation_callback function to call with the results - * @param validation_callback_cls closure for peer_address_callback + * @param validation_callback_cls closure for @a validation_callback */ struct GNUNET_TRANSPORT_ValidationMonitoringContext * -GNUNET_TRANSPORT_monitor_validation_entries (const struct - GNUNET_CONFIGURATION_Handle *cfg, - const struct GNUNET_PeerIdentity *peer, - int one_shot, - struct GNUNET_TIME_Relative timeout, - GNUNET_TRANSPORT_ValidationIterateCallback validation_callback, - void *validation_callback_cls); +GNUNET_TRANSPORT_monitor_validation_entries (const struct GNUNET_CONFIGURATION_Handle *cfg, + const struct GNUNET_PeerIdentity *peer, + int one_shot, + struct GNUNET_TIME_Relative timeout, + GNUNET_TRANSPORT_ValidationIterateCallback validation_callback, + void *validation_callback_cls); /** @@ -752,7 +748,6 @@ void GNUNET_TRANSPORT_monitor_validation_entries_cancel (struct GNUNET_TRANSPORT_ValidationMonitoringContext *vic); - /** * Handle for blacklisting peers. */ @@ -764,11 +759,12 @@ struct GNUNET_TRANSPORT_Blacklist; * * @param cls closure * @param pid peer to approve or disapproave - * @return GNUNET_OK if the connection is allowed, GNUNET_SYSERR if not + * @return #GNUNET_OK if the connection is allowed, #GNUNET_SYSERR if not */ -typedef int (*GNUNET_TRANSPORT_BlacklistCallback) (void *cls, - const struct - GNUNET_PeerIdentity * pid); +typedef int +(*GNUNET_TRANSPORT_BlacklistCallback) (void *cls, + const struct + GNUNET_PeerIdentity * pid); /** @@ -782,7 +778,7 @@ typedef int (*GNUNET_TRANSPORT_BlacklistCallback) (void *cls, * * @param cfg configuration to use * @param cb callback to invoke to check if connections are allowed - * @param cb_cls closure for cb + * @param cb_cls closure for @a cb * @return NULL on error, otherwise handle for cancellation */ struct GNUNET_TRANSPORT_Blacklist * -- cgit v1.2.3