print active/inactive information

[oweals/gnunet.git] / src / include / gnunet_transport_service.h

diff --git a/src/include/gnunet_transport_service.h b/src/include/gnunet_transport_service.h
index 69dcefb21678a912edd4c8fbef14348cab234cc8..3a4d282e476616c5cce05ee47cfb966cf2a78681 100644 (file)
--- a/src/include/gnunet_transport_service.h
+++ b/src/include/gnunet_transport_service.h
@@ -172,7 +172,11 @@ enum GNUNET_TRANSPORT_PeerState
 
 
 /**
- * Current state of a validation process
+ * Current state of a validation process.
+ *
+ * FIXME: what state is used to indicate that a validation
+ * was successful? If that is clarified/determined, "UGH" in
+ * ~gnunet-peerinfo-gtk.c:1103 should be resolved.
  */
 enum GNUNET_TRANSPORT_ValidationState
 {
@@ -273,18 +277,25 @@ typedef void
 
 
 /**
- * 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 NULL to signal the end
- * of the iteration.
+ * 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
+ * always is the last call, regardless of the value in @a res.
  *
  * @param cls closure
- * @param address NULL on error or end of iteration,
- *        otherwise 0-terminated printable UTF-8 string
+ * @param address NULL on end of iteration,
+ *        otherwise 0-terminated printable UTF-8 string,
+ *        in particular an empty string if @a res is #GNUNET_NO
+ * @param res result of the address to string conversion:
+ *        if #GNUNET_OK: conversion successful
+ *        if #GNUNET_NO: address was invalid (or not supported)
+ *        if #GNUNET_SYSERR: communication error (IPC error)
  */
 typedef void
 (*GNUNET_TRANSPORT_AddressToStringCallback) (void *cls,
-                                             const char *address);
+                                             const char *address,
+                                             int res);
 
 
 /**
@@ -446,7 +457,7 @@ GNUNET_TRANSPORT_try_connect (struct GNUNET_TRANSPORT_Handle *handle,
  * Cancel the request to transport to try a connect
  * Callback will not be called
  *
- * @param tch GNUNET_TRANSPORT_TryConnectHandle handle to cancel
+ * @param tch handle to cancel
  */
 void
 GNUNET_TRANSPORT_try_connect_cancel (struct GNUNET_TRANSPORT_TryConnectHandle *tch);
@@ -466,16 +477,16 @@ GNUNET_TRANSPORT_try_connect_cancel (struct GNUNET_TRANSPORT_TryConnectHandle *t
  */
 struct GNUNET_TRANSPORT_TryConnectHandle *
 GNUNET_TRANSPORT_try_disconnect (struct GNUNET_TRANSPORT_Handle *handle,
-                              const struct GNUNET_PeerIdentity *target,
-                              GNUNET_TRANSPORT_TryConnectCallback cb,
-                              void *cb_cls);
+                                 const struct GNUNET_PeerIdentity *target,
+                                 GNUNET_TRANSPORT_TryConnectCallback cb,
+                                 void *cb_cls);
 
 
 /**
  * Cancel the request to transport to try a disconnect
  * Callback will not be called
  *
- * @param tch GNUNET_TRANSPORT_TryConnectHandle handle to cancel
+ * @param tch handle for operation to cancel
  */
 void
 GNUNET_TRANSPORT_try_disconnect_cancel (struct GNUNET_TRANSPORT_TryConnectHandle *tch);
@@ -628,6 +639,9 @@ void
 GNUNET_TRANSPORT_get_hello_cancel (struct GNUNET_TRANSPORT_GetHelloHandle *ghh);
 
 
+/**
+ * Handle for a #GNUNET_TRANSPORT_offer_hello operation
+ */
 struct GNUNET_TRANSPORT_OfferHelloHandle;
 
 /**
@@ -724,6 +738,10 @@ GNUNET_TRANSPORT_is_connected (enum GNUNET_TRANSPORT_PeerState state);
 const char *
 GNUNET_TRANSPORT_vs2s (enum GNUNET_TRANSPORT_ValidationState state);
 
+
+/**
+ * Handle for a #GNUNET_TRANSPORT_monitor_peers operation.
+ */
 struct GNUNET_TRANSPORT_PeerMonitoringContext;
 
 /**
@@ -771,6 +789,9 @@ void
 GNUNET_TRANSPORT_monitor_peers_cancel (struct GNUNET_TRANSPORT_PeerMonitoringContext *pic);
 
 
+/**
+ * Handle for a #GNUNET_TRANSPORT_monitor_validation_entries() operation.
+ */
 struct GNUNET_TRANSPORT_ValidationMonitoringContext;
 
 /**