SET service: accurate results for symmetric mode

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

diff --git a/src/include/gnunet_service_lib.h b/src/include/gnunet_service_lib.h
index ec0c15e1bf6f313b6a8a832972aa8ff0fac89fc5..6cb7413d3c6edbd51cc5e40e73ed4a22951c68cc 100644 (file)
--- a/src/include/gnunet_service_lib.h
+++ b/src/include/gnunet_service_lib.h
@@ -1,10 +1,10 @@
 /*
      This file is part of GNUnet.
-     (C) 2009 Christian Grothoff (and other contributing authors)
+     Copyright (C) 2009-2013 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
-     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
@@ -14,14 +14,16 @@
 
      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.
 */
 
 /**
  * @file include/gnunet_service_lib.h
  * @brief functions related to starting services
  * @author Christian Grothoff
+ * @defgroup service generic functions for implementing service processes
+ * @{
  */
 
 #ifndef GNUNET_SERVICE_LIB_H
@@ -43,27 +45,27 @@ extern "C"
  * Get the list of addresses that a server for the given service
  * should bind to.
  *
- * @param serviceName name of the service
+ * @param service_name name of the service
  * @param cfg configuration (which specifies the addresses)
  * @param addrs set (call by reference) to an array of pointers to the
  *              addresses the server should bind to and listen on; the
  *              array will be NULL-terminated (on success)
  * @param addr_lens set (call by reference) to an array of the lengths
- *              of the respective 'struct sockaddr' struct in the 'addrs'
+ *              of the respective `struct sockaddr` struct in the @a addrs
  *              array (on success)
  * @return number of addresses found on success,
- *              GNUNET_SYSERR if the configuration
+ *              #GNUNET_SYSERR if the configuration
  *              did not specify reasonable finding information or
  *              if it specified a hostname that could not be resolved;
- *              GNUNET_NO if the number of addresses configured is
- *              zero (in this case, '*addrs' and '*addr_lens' will be
+ *              #GNUNET_NO if the number of addresses configured is
+ *              zero (in this case, '* @a addrs' and '* @a addr_lens' will be
  *              set to NULL).
  */
 int
-GNUNET_SERVICE_get_server_addresses (const char *serviceName,
+GNUNET_SERVICE_get_server_addresses (const char *service_name,
                                      const struct GNUNET_CONFIGURATION_Handle
                                      *cfg, struct sockaddr ***addrs,
-                                     socklen_t ** addr_lens);
+                                     socklen_t **addr_lens);
 
 
 /**
@@ -74,10 +76,10 @@ GNUNET_SERVICE_get_server_addresses (const char *serviceName,
  * @param server the initialized server
  * @param cfg configuration to use
  */
-typedef void (*GNUNET_SERVICE_Main) (void *cls,
-                                     struct GNUNET_SERVER_Handle * server,
-                                     const struct GNUNET_CONFIGURATION_Handle *
-                                     cfg);
+typedef void
+(*GNUNET_SERVICE_Main) (void *cls,
+                        struct GNUNET_SERVER_Handle *server,
+                        const struct GNUNET_CONFIGURATION_Handle *cfg);
 
 
 /**
@@ -108,23 +110,29 @@ enum GNUNET_SERVICE_Options
  * Run a standard GNUnet service startup sequence (initialize loggers
  * and configuration, parse options).
  *
- * @param argc number of command line arguments
+ * @param argc number of command line arguments in @a argv
  * @param argv command line arguments
  * @param service_name our service name
  * @param options service options
  * @param task main task of the service
- * @param task_cls closure for task
- * @return GNUNET_SYSERR on error, GNUNET_OK
+ * @param task_cls closure for @a task
+ * @return #GNUNET_SYSERR on error, #GNUNET_OK
  *         if we shutdown nicely
  */
 int
-GNUNET_SERVICE_run (int argc, char *const *argv, const char *service_name,
-                    enum GNUNET_SERVICE_Options options, GNUNET_SERVICE_Main task,
-                    void *task_cls);
+GNUNET_SERVICE_run (int argc, char *const *argv,
+                   const char *service_name,
+                    enum GNUNET_SERVICE_Options options,
+                   GNUNET_SERVICE_Main task,
+                   void *task_cls);
 
 
+/**
+ * Opaque handle for a service.
+ */
 struct GNUNET_SERVICE_Context;
 
+
 /**
  * Run a service startup sequence within an existing
  * initialized system.
@@ -152,7 +160,18 @@ GNUNET_SERVICE_get_server (struct GNUNET_SERVICE_Context *ctx);
 
 
 /**
- * Stop a service that was started with "GNUNET_SERVICE_start".
+ * Get the NULL-terminated array of listen sockets for this service.
+ *
+ * @param ctx service context to query
+ * @return NULL if there are no listen sockets, otherwise NULL-terminated
+ *              array of listen sockets.
+ */
+struct GNUNET_NETWORK_Handle *const *
+GNUNET_SERVICE_get_listen_sockets (struct GNUNET_SERVICE_Context *ctx);
+
+
+/**
+ * Stop a service that was started with #GNUNET_SERVICE_start.
  *
  * @param sctx the service context returned from the start function
  */
@@ -167,6 +186,10 @@ GNUNET_SERVICE_stop (struct GNUNET_SERVICE_Context *sctx);
 }
 #endif
 
+
+/** @} */ /* end of group service */
+
+
 /* ifndef GNUNET_SERVICE_LIB_H */
 #endif
 /* end of gnunet_service_lib.h */