2 This file is part of GNUnet.
3 Copyright (C) 2009-2013 GNUnet e.V.
5 GNUnet is free software; you can redistribute it and/or modify
6 it under the terms of the GNU General Public License as published
7 by the Free Software Foundation; either version 3, or (at your
8 option) any later version.
10 GNUnet is distributed in the hope that it will be useful, but
11 WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 General Public License for more details.
15 You should have received a copy of the GNU General Public License
16 along with GNUnet; see the file COPYING. If not, write to the
17 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 Boston, MA 02110-1301, USA.
22 * @author Christian Grothoff
25 * Functions related to starting services
27 * @defgroup service Service library
28 * Start service processes.
30 * @see [Documentation](https://gnunet.org/developer-handbook-util-services)
35 #ifndef GNUNET_SERVICE_LIB_H
36 #define GNUNET_SERVICE_LIB_H
41 #if 0 /* keep Emacsens' auto-indent happy */
46 #include "gnunet_configuration_lib.h"
47 #include "gnunet_server_lib.h"
51 * Get the list of addresses that a server for the given service
54 * @param service_name name of the service
55 * @param cfg configuration (which specifies the addresses)
56 * @param addrs set (call by reference) to an array of pointers to the
57 * addresses the server should bind to and listen on; the
58 * array will be NULL-terminated (on success)
59 * @param addr_lens set (call by reference) to an array of the lengths
60 * of the respective `struct sockaddr` struct in the @a addrs
62 * @return number of addresses found on success,
63 * #GNUNET_SYSERR if the configuration
64 * did not specify reasonable finding information or
65 * if it specified a hostname that could not be resolved;
66 * #GNUNET_NO if the number of addresses configured is
67 * zero (in this case, '* @a addrs' and '* @a addr_lens' will be
71 GNUNET_SERVICE_get_server_addresses (const char *service_name,
72 const struct GNUNET_CONFIGURATION_Handle
73 *cfg, struct sockaddr ***addrs,
74 socklen_t **addr_lens);
78 * Function called by the service's run
79 * method to run service-specific setup code.
82 * @param server the initialized server
83 * @param cfg configuration to use
86 (*GNUNET_SERVICE_Main) (void *cls,
87 struct GNUNET_SERVER_Handle *server,
88 const struct GNUNET_CONFIGURATION_Handle *cfg);
92 * Options for the service (bitmask).
94 enum GNUNET_SERVICE_Options
99 GNUNET_SERVICE_OPTION_NONE = 0,
102 * Do not trigger server shutdown on signals, allow for the user
103 * to terminate the server explicitly when needed.
105 GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN = 1,
108 * Trigger a SOFT server shutdown on signals, allowing active
109 * non-monitor clients to complete their transactions.
111 GNUNET_SERVICE_OPTION_SOFT_SHUTDOWN = 2
116 * Run a standard GNUnet service startup sequence (initialize loggers
117 * and configuration, parse options).
119 * @param argc number of command line arguments in @a argv
120 * @param argv command line arguments
121 * @param service_name our service name
122 * @param options service options
123 * @param task main task of the service
124 * @param task_cls closure for @a task
125 * @return #GNUNET_SYSERR on error, #GNUNET_OK
126 * if we shutdown nicely
129 GNUNET_SERVICE_run (int argc, char *const *argv,
130 const char *service_name,
131 enum GNUNET_SERVICE_Options options,
132 GNUNET_SERVICE_Main task,
137 * Opaque handle for a service.
139 struct GNUNET_SERVICE_Context;
143 * Run a service startup sequence within an existing
144 * initialized system.
146 * @param service_name our service name
147 * @param cfg configuration to use
148 * @param options service options
149 * @return NULL on error, service handle
151 struct GNUNET_SERVICE_Context *
152 GNUNET_SERVICE_start (const char *service_name,
153 const struct GNUNET_CONFIGURATION_Handle *cfg,
154 enum GNUNET_SERVICE_Options options);
158 * Obtain the server used by a service. Note that the server must NOT
159 * be destroyed by the caller.
161 * @param ctx the service context returned from the start function
162 * @return handle to the server for this service, NULL if there is none
164 struct GNUNET_SERVER_Handle *
165 GNUNET_SERVICE_get_server (struct GNUNET_SERVICE_Context *ctx);
169 * Get the NULL-terminated array of listen sockets for this service.
171 * @param ctx service context to query
172 * @return NULL if there are no listen sockets, otherwise NULL-terminated
173 * array of listen sockets.
175 struct GNUNET_NETWORK_Handle *const *
176 GNUNET_SERVICE_get_listen_sockets (struct GNUNET_SERVICE_Context *ctx);
180 * Stop a service that was started with #GNUNET_SERVICE_start.
182 * @param sctx the service context returned from the start function
185 GNUNET_SERVICE_stop (struct GNUNET_SERVICE_Context *sctx);
188 #if 0 /* keep Emacsens' auto-indent happy */
195 /* ifndef GNUNET_SERVICE_LIB_H */
198 /** @} */ /* end of group service */
200 /* end of gnunet_service_lib.h */