From 821e1221afc9f9fd127379865bd2e470232bd918 Mon Sep 17 00:00:00 2001 From: Matthias Wachs Date: Thu, 24 Jul 2014 12:58:10 +0000 Subject: fixing documentation --- src/transport/gnunet-transport.c | 119 +++++++++++++++++++++++++-- src/transport/plugin_transport_http_client.c | 16 ++-- src/transport/plugin_transport_http_common.c | 10 ++- src/transport/plugin_transport_http_server.c | 22 +++-- src/transport/plugin_transport_unix.c | 4 +- 5 files changed, 134 insertions(+), 37 deletions(-) diff --git a/src/transport/gnunet-transport.c b/src/transport/gnunet-transport.c index 0fef7784e..354060ac8 100644 --- a/src/transport/gnunet-transport.c +++ b/src/transport/gnunet-transport.c @@ -39,56 +39,148 @@ * Should match NAT_SERVER_TIMEOUT in 'nat_test.c'. */ #define TIMEOUT GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_SECONDS, 20) + +/** + * Timeout for a name resolution + */ #define RESOLUTION_TIMEOUT GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_SECONDS, 30) + +/** + * Timeout for an operations + */ #define OP_TIMEOUT GNUNET_TIME_relative_multiply (GNUNET_TIME_UNIT_SECONDS, 30) +/** + * Context to store name resolutions for valiation + */ struct ValidationResolutionContext { + /** + * Next in DLL + */ struct ValidationResolutionContext *next; + /** + * Previous in DLL + */ struct ValidationResolutionContext *prev; + /** + * Peer identity + */ struct GNUNET_PeerIdentity id; + /** + * Address to resolve + */ struct GNUNET_HELLO_Address *addrcp; + /** + * Time of last validation + */ struct GNUNET_TIME_Absolute last_validation; + /** + * Address is valid until + */ struct GNUNET_TIME_Absolute valid_until; + /** + * Time of next validation + */ struct GNUNET_TIME_Absolute next_validation; + /** + * state of validation process + */ enum GNUNET_TRANSPORT_ValidationState state; + /** + * Tranport conversion handle + */ struct GNUNET_TRANSPORT_AddressToStringContext *asc; + /** + * plugin name + */ char *transport; + /** + * was the entry printed + */ int printed; }; - +/** + * Struct to store information about peers in monitor mode + */ struct MonitoredPeer { + /** + * State of the peer + */ enum GNUNET_TRANSPORT_PeerState state; + /** + * Timeout + */ struct GNUNET_TIME_Absolute state_timeout; + /** + * The address to convert + */ struct GNUNET_HELLO_Address *address; }; - +/** + * Context to store name resolutions for valiation + */ struct PeerResolutionContext { + /** + * Next in DLL + */ struct PeerResolutionContext *next; + + /** + * Prev in DLL + */ struct PeerResolutionContext *prev; + + /** + * The peer id + */ struct GNUNET_PeerIdentity id; + + /** + * address to resolve + */ struct GNUNET_HELLO_Address *addrcp; + + /** + * transport conversiion context + */ struct GNUNET_TRANSPORT_AddressToStringContext *asc; + + /** + * peer state + */ enum GNUNET_TRANSPORT_PeerState state; + + /** + * state timeout + */ struct GNUNET_TIME_Absolute state_timeout; + + /** + * transport plugin + */ char *transport; + + /** + * was the entry printed + */ int printed; }; @@ -349,12 +441,24 @@ struct TestContext *head; */ struct TestContext *tail; +/** + * DLL: head of validation resolution entries + */ static struct ValidationResolutionContext *vc_head; +/** + * DLL: tail of validation resolution entries + */ static struct ValidationResolutionContext *vc_tail; +/** + * DLL: head of resolution entries + */ static struct PeerResolutionContext *rc_head; +/** + * DLL: head of resolution entries + */ static struct PeerResolutionContext *rc_tail; @@ -596,8 +700,7 @@ display_test_result (struct TestContext *tc, * Clean up and update GUI. * * @param cls test context - * @param success currently always #GNUNET_OK - * @param emsg error message, NULL on success + * @param result status code */ static void result_callback (void *cls, @@ -633,8 +736,8 @@ resolve_validation_address (const struct GNUNET_PeerIdentity *id, /** * Function to call with a textual representation of an address. This * function will be called several times with different possible - * textual representations, and a last time with @address being NULL - * to signal the end of the iteration. Note that @address NULL + * textual representations, and a last time with @a address being NULL + * to signal the end of the iteration. Note that @a address NULL * always is the last call, regardless of the value in @a res. * * @param cls closure @@ -1205,8 +1308,8 @@ print_info (const struct GNUNET_PeerIdentity *id, /** * Function called with a textual representation of an address. This * function will be called several times with different possible - * textual representations, and a last time with @address being NULL - * to signal the end of the iteration. Note that @address NULL + * textual representations, and a last time with @a address being NULL + * to signal the end of the iteration. Note that @a address NULL * always is the last call, regardless of the value in @a res. * * @param cls closure diff --git a/src/transport/plugin_transport_http_client.c b/src/transport/plugin_transport_http_client.c index 38b0775f3..615639a6e 100644 --- a/src/transport/plugin_transport_http_client.c +++ b/src/transport/plugin_transport_http_client.c @@ -2077,18 +2077,12 @@ client_configure_plugin (struct HTTP_Client_Plugin *plugin) /** - * Function called by the pretty printer for the resolved address for - * each human-readable address obtained. The callback can be called - * several times. The last invocation must be with a @a address of - * NULL and a @a res of #GNUNET_OK. Thus, to indicate conversion - * errors, the callback might be called first with @a address NULL and - * @a res being #GNUNET_SYSERR. In that case, there must still be a - * subsequent call later with @a address NULL and @a res #GNUNET_OK. + * Function to convert an address to a human-readable string. * * @param cls closure - * @param address one of the names for the host, NULL on last callback - * @param res #GNUNET_OK if conversion was successful, #GNUNET_SYSERR on failure, - * #GNUNET_OK on last callback + * @param addr address to convert + * @param addrlen address length + * @return res string if conversion was successful, NULL otherwise */ static const char * http_client_plugin_address_to_string (void *cls, @@ -2126,7 +2120,7 @@ http_client_plugin_update_session_timeout (void *cls, * * @param cls closure * @param peer which peer was the session for - * @param session which session is being updated + * @param s which session is being updated * @param delay new delay to use for receiving */ static void diff --git a/src/transport/plugin_transport_http_common.c b/src/transport/plugin_transport_http_common.c index a420b8cdc..f1246bdb4 100644 --- a/src/transport/plugin_transport_http_common.c +++ b/src/transport/plugin_transport_http_common.c @@ -244,13 +244,15 @@ static struct PrettyPrinterContext *dll_ppc_tail; * to override the address again. * * @param plugin the name of the plugin - * @param addr binary address - * @param addrlen length of the address - * @return string representing the same address + * @param saddr the splitted http address + * @param options address options + * @param dnsresult dns name to include in address + * @return string representing the same address or NULL on error */ static const char * http_common_plugin_dnsresult_to_address (const char *plugin, - const struct SplittedHTTPAddress *saddr, uint32_t options, + const struct SplittedHTTPAddress *saddr, + uint32_t options, const char *dnsresult) { static char rbuf[1024]; diff --git a/src/transport/plugin_transport_http_server.c b/src/transport/plugin_transport_http_server.c index bed2de34f..74375462d 100644 --- a/src/transport/plugin_transport_http_server.c +++ b/src/transport/plugin_transport_http_server.c @@ -952,6 +952,7 @@ server_v6_run (void *cls, * * @param plugin plugin * @param daemon_handle the MHD daemon handle + * @param now schedule now * @return gnunet task identifier */ static GNUNET_SCHEDULER_TaskIdentifier @@ -3210,18 +3211,15 @@ LIBGNUNET_PLUGIN_TRANSPORT_DONE (void *cls) /** - * Function called by the pretty printer for the resolved address for - * each human-readable address obtained. The callback can be called - * several times. The last invocation must be with a @a address of - * NULL and a @a res of #GNUNET_OK. Thus, to indicate conversion - * errors, the callback might be called first with @a address NULL and - * @a res being #GNUNET_SYSERR. In that case, there must still be a - * subsequent call later with @a address NULL and @a res #GNUNET_OK. + * Function called for a quick conversion of the binary address to + * a numeric address. Note that the caller must not free the + * address and that the next call to this function is allowed + * to override the address again. * - * @param cls closure - * @param address one of the names for the host, NULL on last callback - * @param res #GNUNET_OK if conversion was successful, #GNUNET_SYSERR on failure, - * #GNUNET_OK on last callback + * @param cls unused + * @param addr binary address + * @param addrlen length of the address + * @return string representing the same address */ static const char * http_server_plugin_address_to_string (void *cls, @@ -3262,7 +3260,7 @@ http_server_plugin_get_network (void *cls, static void http_server_plugin_update_inbound_delay (void *cls, const struct GNUNET_PeerIdentity *peer, - struct Session *s, + struct Session *session, struct GNUNET_TIME_Relative delay) { s->next_receive = GNUNET_TIME_relative_to_absolute (delay); diff --git a/src/transport/plugin_transport_unix.c b/src/transport/plugin_transport_unix.c index 5cf9c5432..947ec5d71 100644 --- a/src/transport/plugin_transport_unix.c +++ b/src/transport/plugin_transport_unix.c @@ -561,7 +561,7 @@ reschedule_session_timeout (struct Session *session) * Convert unix path to a `struct sockaddr_un *` * * @param unixpath path to convert - * @param sock_len[out] set to the length of the address + * @param[out] sock_len set to the length of the address * @return converted unix path */ static struct sockaddr_un * @@ -1096,7 +1096,7 @@ unix_plugin_do_read (struct Plugin *plugin) /** * Write to UNIX domain socket (it is ready). * - * @param session session to write data for + * @param plugin handle to the plugin */ static void unix_plugin_do_write (struct Plugin *plugin) -- cgit v1.2.3