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,
/* **************** 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,
/**
+ * 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,
/**
+ * 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,
/**
- * 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);
/**