fix misc make dist issues

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

diff --git a/src/include/gnunet_nse_service.h b/src/include/gnunet_nse_service.h
index 012a61c22fe2067fa1f07af45ccc2c19e5aed95e..90f74a7ffbc65f995f66766b67b6564434d806f9 100644 (file)
--- a/src/include/gnunet_nse_service.h
+++ b/src/include/gnunet_nse_service.h
@@ -1,10 +1,10 @@
 /*
       This file is part of GNUnet
 /*
       This file is part of GNUnet

-      (C) 2009, 2010 Christian Grothoff (and other contributing authors)
+      Copyright (C) 2011 GNUnet e.V.

 
       GNUnet is free software; you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published
 
       GNUnet is free software; you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published

-      by the Free Software Foundation; either version 2, or (at your
+      by the Free Software Foundation; either version 3, or (at your

       option) any later version.
 
       GNUnet is distributed in the hope that it will be useful, but
       option) any later version.
 
       GNUnet is distributed in the hope that it will be useful, but


@@ -14,20 +14,29 @@
 
       You should have received a copy of the GNU General Public License
       along with GNUnet; see the file COPYING.  If not, write to the
 
       You should have received a copy of the GNU General Public License
       along with GNUnet; see the file COPYING.  If not, write to the

-      Free Software Foundation, Inc., 59 Temple Place - Suite 330,
-      Boston, MA 02111-1307, USA.
+      Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+      Boston, MA 02110-1301, USA.

  */
 
 #ifndef GNUNET_NSE_SERVICE_H_
 #define GNUNET_NSE_SERVICE_H_
 
 /**
  */
 
 #ifndef GNUNET_NSE_SERVICE_H_
 #define GNUNET_NSE_SERVICE_H_
 
 /**

- * @file include/gnunet_nse_service.h
- * @brief API to retrieve the current network size estimate,
- *        also to register for notifications whenever a new
- *        network size estimate is calculated.
- *

  * @author Nathan Evans
  * @author Nathan Evans

+ *
+ * @file
+ * API to retrieve the current network size estimate
+ *
+ * @defgroup nse  NSE service
+ * Network Size Estimation
+ *
+ * Provides an API to retrieve the current network size estimate,
+ * also to register for notifications whenever a new
+ * network size estimate is calculated.
+ *
+ * @see [Documentation](https://gnunet.org/gnunet-nse-subsystem)
+ *
+ * @{

  */
 
 #ifdef __cplusplus
  */
 
 #ifdef __cplusplus


@@ -38,57 +47,49 @@ extern "C"
 #endif
 #endif
 
 #endif
 #endif
 

-#include "gnunet_common.h"
-#include "gnunet_configuration_lib.h"
-#include "gnunet_scheduler_lib.h"
+#include "gnunet_util_lib.h"

 
 /**
  * Version of the network size estimation API.
  */
 #define GNUNET_NSE_VERSION 0x00000000
 
 
 /**
  * Version of the network size estimation API.
  */
 #define GNUNET_NSE_VERSION 0x00000000
 

-/**
- * Interval for sending network size estimation flood requests.
- * Number is in milliseconds.
- * This needs to be a factor of the number milliseconds in
- * a day, as the base time used is midnight each day offset
- * by this amount.
- *
- * There are 86400000 milliseconds in a day.
- */
-#define GNUNET_NSE_INTERVAL 3600000 /* Once per hour */
-
-/**
- * Number of bits
- */
-#define GNUNET_NSE_BITS
-

 /**
  * Handle for the network size estimation service.
  */
 struct GNUNET_NSE_Handle;
 
 /**
  * Handle for the network size estimation service.
  */
 struct GNUNET_NSE_Handle;
 

-

 /**
  * Callback to call when network size estimate is updated.
  *
  * @param cls closure
 /**
  * Callback to call when network size estimate is updated.
  *
  * @param cls closure

- * @param estimate the value of the current network size estimate
- * @param std_dev standard deviation (rounded down to nearest integer)
- *                of the size estimation values seen
- * @return GNUNET_OK to continue, GNUNET_SYSERR to abort iteration
+ * @param timestamp time when the estimate was received from the server (or created by the server)
+ * @param logestimate the log(Base 2) value of the current network size estimate
+ * @param std_dev standard deviation for the estimate
+ *
+ */
+typedef void (*GNUNET_NSE_Callback) (void *cls,
+                                     struct GNUNET_TIME_Absolute timestamp,
+                                     double logestimate, double std_dev);
+
+
+/**
+ * Convert the logarithmic estimated returned to the 'GNUNET_NSE_Callback'
+ * into an absolute estimate in terms of the number of peers in the network.
+ *
+ * @param loge logarithmic estimate
+ * @return absolute number of peers in the network (estimated)

  */
  */

-typedef int
-(*GNUNET_NSE_Callback) (void *cls, double estimate, double std_dev);
+#define GNUNET_NSE_log_estimate_to_n(loge) pow(2.0, (loge))
+

 
 /**
  * Connect to the network size estimation service.
  *
  * @param cfg the configuration to use
  * @param func funtion to call with network size estimate
 
 /**
  * Connect to the network size estimation service.
  *
  * @param cfg the configuration to use
  * @param func funtion to call with network size estimate

- * @param func_cls closure to pass for network size estimate callback
- *
- * @return handle to use
+ * @param func_cls closure to pass to @a func
+ * @return handle to use in #GNUNET_NSE_disconnect to stop NSE from invoking the callbacks

  */
 struct GNUNET_NSE_Handle *
 GNUNET_NSE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
  */
 struct GNUNET_NSE_Handle *
 GNUNET_NSE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,


@@ -99,7 +100,6 @@ GNUNET_NSE_connect (const struct GNUNET_CONFIGURATION_Handle *cfg,
  * Disconnect from network size estimation service
  *
  * @param h handle to destroy
  * Disconnect from network size estimation service
  *
  * @param h handle to destroy

- *

  */
 void
 GNUNET_NSE_disconnect (struct GNUNET_NSE_Handle *h);
  */
 void
 GNUNET_NSE_disconnect (struct GNUNET_NSE_Handle *h);


@@ -112,4 +112,6 @@ GNUNET_NSE_disconnect (struct GNUNET_NSE_Handle *h);
 }
 #endif
 
 }
 #endif
 

+/** @} */ /* end of group nse */
+

 #endif /* GNUNET_NSE_SERVICE_H_ */
 #endif /* GNUNET_NSE_SERVICE_H_ */