/*
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
* @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
* 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);
/**
* @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);
/**
*/
enum GNUNET_SERVICE_Options
{
- /**
- * Use defaults.
- */
+ /**
+ * Use defaults.
+ */
GNUNET_SERVICE_OPTION_NONE = 0,
- /**
- * Do not trigger server shutdown on signals, allow for the user
- * to terminate the server explicitly when needed.
- */
- GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN = 1
+ /**
+ * Do not trigger server shutdown on signals, allow for the user
+ * to terminate the server explicitly when needed.
+ */
+ GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN = 1,
+
+ /**
+ * Trigger a SOFT server shutdown on signals, allowing active
+ * non-monitor clients to complete their transactions.
+ */
+ GNUNET_SERVICE_OPTION_SOFT_SHUTDOWN = 2
};
* 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 serviceName our service name
- * @param opt service options
+ * @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 *serviceName,
- enum GNUNET_SERVICE_Options opt, 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.
*
- * @param serviceName our service name
+ * @param service_name our service name
* @param cfg configuration to use
+ * @param options service options
* @return NULL on error, service handle
*/
struct GNUNET_SERVICE_Context *
-GNUNET_SERVICE_start (const char *serviceName,
- const struct GNUNET_CONFIGURATION_Handle *cfg);
+GNUNET_SERVICE_start (const char *service_name,
+ const struct GNUNET_CONFIGURATION_Handle *cfg,
+ enum GNUNET_SERVICE_Options options);
/**
/**
- * 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
*/
}
#endif
+
+/** @} */ /* end of group service */
+
+
/* ifndef GNUNET_SERVICE_LIB_H */
#endif
/* end of gnunet_service_lib.h */
projects / oweals / gnunet.git / blobdiff