summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorChristian Grothoff <christian@grothoff.org>2014-02-02 17:25:33 +0000
committerChristian Grothoff <christian@grothoff.org>2014-02-02 17:25:33 +0000
commitfdf369790b040af2ab491e80dab8eb1bb95151a2 (patch)
tree05f96aa17d5c9656ab00eac2853f5c86aa990a54
parent779ddb717e6fa5f1fc1a3bb38b014f3cca8af800 (diff)
-indentation, doxygen
-rw-r--r--src/include/gnunet_connection_lib.h19
-rw-r--r--src/include/gnunet_transport_service.h184
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 *