gnunetutil: add 2d and 3d allocation including tests

[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 f7d2f781c48d9e14da5dc80aa43b87e04fbb6fa9..797857ed8541f0334dc4db127dc1fde97b81e9e7 100644 (file)
--- a/src/include/gnunet_service_lib.h
+++ b/src/include/gnunet_service_lib.h
@@ -95,13 +95,15 @@ typedef void
 enum GNUNET_SERVICE_Options
 {
   /**
-   * Use defaults.
+   * Use defaults.  Terminates all client connections and the listen
+   * sockets immediately upon receiving the shutdown signal.
    */
   GNUNET_SERVICE_OPTION_NONE = 0,
 
   /**
-   * Do not trigger server shutdown on signals, allow for the user
-   * to terminate the server explicitly when needed.
+   * Do not trigger server shutdown on signal at all; instead, allow
+   * for the user to terminate the server explicitly when needed
+   * by calling #GNUNET_SERVICE_shutdown().
    */
   GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN = 1,
 
@@ -195,23 +197,23 @@ GNUNET_SERVICE_stop (struct GNUNET_SERVICE_Context *sctx);
 /* **************** NEW SERVICE API ********************** */
 
 /**
- *
+ * Handle to a service.
  */
 struct GNUNET_SERVICE_Handle;
 
 
 /**
- *
+ * Handle to a client that is connected to a service.
  */
 struct GNUNET_SERVICE_Client;
 
 
 /**
+ * Callback to initialize a service, called exactly once when the service is run.
  *
- *
- * @param cls
- * @param cfg
- * @param sh
+ * @param cls closure passed to #GNUNET_SERVICE_MAIN
+ * @param cfg configuration to use for this service
+ * @param sh handle to the newly create service
  */
 typedef void
 (*GNUNET_SERVICE_InitCallback)(void *cls,
@@ -220,12 +222,12 @@ typedef void
 
 
 /**
+ * Callback to be called when a client connects to the service.
  *
- *
- * @param cls
- * @param c
- * @param mq
- * @return
+ * @param cls closure for the service
+ * @param c the new client that connected to the service
+ * @param mq the message queue used to send messages to the client
+ * @return the client-specific (`internal') closure
  */
 typedef void *
 (*GNUNET_SERVICE_ConnectHandler)(void *cls,
@@ -234,11 +236,11 @@ typedef void *
 
 
 /**
+ * Callback to be called when a client disconnected from the service
  *
- *
- * @param cls
- * @param c
- * @param internal_cls
+ * @param cls closure for the service
+ * @param c the client that disconnected
+ * @param internal_cls the client-specific (`internal') closure
  */
 typedef void
 (*GNUNET_SERVICE_DisconnectHandler)(void *cls,
@@ -274,15 +276,17 @@ typedef void
  * dropped. Additionally, clients can be dropped at any time using
  * #GNUNET_SERVICE_client_drop().
  *
- * @param argc
- * @param argv
- * @param service_name
- * @param options
- * @param service_init_cb
- * @param connect_cb
- * @param disconnect_cb
- * @param cls
- * @param handlers
+ * @param argc number of command-line arguments in @a argv
+ * @param argv array of command-line arguments
+ * @param service_name name of the service to run
+ * @param options options controlling shutdown of the service
+ * @param service_init_cb function to call once the service is ready
+ * @param connect_cb function to call whenever a client connects
+ * @param disconnect_cb function to call whenever a client disconnects
+ * @param cls closure argument for @a service_init_cb, @a connect_cb and @a disconnect_cb
+ * @param handlers NULL-terminated array of message handlers for the service,
+ *                 the closure will be set to the value returned by
+ *                 the @a connect_cb for the respective connection
  * @return 0 on success, non-zero on error
  */
 int
@@ -326,15 +330,15 @@ GNUNET_SERVICE_ruN_ (int argc,
  * dropped. Additionally, clients can be dropped at any time using
  * #GNUNET_SERVICE_client_drop().
  *
- * @param argc
- * @param argv
- * @param service_name
- * @param options
- * @param service_init_cb
- * @param connect_cb
- * @param disconnect_cb
- * @param cls
- * @param handlers
+ * @param service_name name of the service to run
+ * @param options options controlling shutdown of the service
+ * @param service_init_cb function to call once the service is ready
+ * @param connect_cb function to call whenever a client connects
+ * @param disconnect_cb function to call whenever a client disconnects
+ * @param cls closure argument for @a service_init_cb, @a connect_cb and @a disconnect_cb
+ * @param handlers NULL-terminated array of message handlers for the service,
+ *                 the closure will be set to the value returned by
+ *                 the @a connect_cb for the respective connection
  * @return 0 on success, non-zero on error
  */
 #define GNUNET_SERVICE_MAIN(service_name,service_options,init_cb,connect_cb,disconnect_cb,cls,handlers) \
@@ -399,7 +403,9 @@ GNUNET_SERVICE_client_disable_continue_warning (struct GNUNET_SERVICE_Client *c)
  * Ask the server to disconnect from the given client.  This is the
  * same as returning #GNUNET_SYSERR within the check procedure when
  * handling a message, wexcept that it allows dropping of a client even
- * when not handling a message from that client.
+ * when not handling a message from that client.  The `disconnect_cb`
+ * will be called on @a c even if the application closes the connection
+ * using this function.
  *
  * @param c client to disconnect now
  */
@@ -408,14 +414,12 @@ GNUNET_SERVICE_client_drop (struct GNUNET_SERVICE_Client *c);
 
 
 /**
- * Stop the listen socket and get ready to shutdown the server once
- * only clients marked using #GNUNET_SERVER_client_mark_monitor are
- * left.
+ * Explicitly stops the service.
  *
- * @param sh server to stop listening on
+ * @param sh server to shutdown
  */
 void
-GNUNET_SERVICE_stop_listening (struct GNUNET_SERVICE_Handle *sh);
+GNUNET_SERVICE_shutdown (struct GNUNET_SERVICE_Handle *sh);
 
 
 /**