[GNUnet-SVN] r31934 - gnunet/src/include

[gnunet]

Author: wachs
Date: 2014-01-16 15:38:06 +0100 (Thu, 16 Jan 2014)
New Revision: 31934

Modified:
   gnunet/src/include/gnunet_transport_service.h
Log:
documentation for callback


Modified: gnunet/src/include/gnunet_transport_service.h
===================================================================
--- gnunet/src/include/gnunet_transport_service.h       2014-01-16 14:03:36 UTC 
(rev 31933)
+++ gnunet/src/include/gnunet_transport_service.h       2014-01-16 14:38:06 UTC 
(rev 31934)
@@ -206,30 +206,43 @@
   GNUNET_TRANSPORT_PS_DISCONNECT_FINISHED
 };
 
+/**
+ * Current state of a validation process
+ */
 enum GNUNET_TRANSPORT_ValidationState
 {
   /**
    * Undefined state
+   *
+   * Used for final callback indicating operation done
    */
   GNUNET_TRANSPORT_VS_NONE,
 
   /**
    * Fresh validation entry
+   *
+   * Entry was just created, no validation process was executed
    */
   GNUNET_TRANSPORT_VS_NEW,
 
   /**
    * Updated validation entry
+   *
+   * This is an update for an existing validation entry
    */
   GNUNET_TRANSPORT_VS_UPDATE,
 
   /**
    * Timeout for validation entry
+   *
+   * A timeout occured during the validation process
    */
   GNUNET_TRANSPORT_VS_TIMEOUT,
 
   /**
    * Validation entry is removed
+   *
+   * The validation entry is getting removed due to a failed validation
    */
   GNUNET_TRANSPORT_VS_REMOVE,
 };
@@ -336,10 +349,18 @@
 /**
  * Function to call with validation information about a peer
  *
+ * This function is called by the transport validation monitoring api to
+ * indicate a change to a validation entry. The information included represent
+ * the current state of the validation entry,
+ *
+ * If the monitoring was called with one_shot=GNUNET_YES, a final callback
+ * with peer==NULL and address==NULL is executed.
+ *
  * @param cls closure
  * @param peer peer this update is about,
  *      NULL if this is the final last callback for a iteration operation
- * @param address address, NULL for disconnect notification in monitor mode
+ * @param address address,
+ *      NULL for disconnect notification in monitor mode
  * @param valid_until when does this address expire
  * @param next_validation time of the next validation operation
  *