2 This file is part of GNUnet.
3 Copyright (C) 2009-2013, 2016 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"
48 #include "gnunet_mq_lib.h"
52 * Get the list of addresses that a server for the given service
55 * @param service_name name of the service
56 * @param cfg configuration (which specifies the addresses)
57 * @param addrs set (call by reference) to an array of pointers to the
58 * addresses the server should bind to and listen on; the
59 * array will be NULL-terminated (on success)
60 * @param addr_lens set (call by reference) to an array of the lengths
61 * of the respective `struct sockaddr` struct in the @a addrs
63 * @return number of addresses found on success,
64 * #GNUNET_SYSERR if the configuration
65 * did not specify reasonable finding information or
66 * if it specified a hostname that could not be resolved;
67 * #GNUNET_NO if the number of addresses configured is
68 * zero (in this case, '* @a addrs' and '* @a addr_lens' will be
72 GNUNET_SERVICE_get_server_addresses (const char *service_name,
73 const struct GNUNET_CONFIGURATION_Handle *cfg,
74 struct sockaddr ***addrs,
75 socklen_t **addr_lens);
79 * Function called by the service's run
80 * method to run service-specific setup code.
83 * @param server the initialized server
84 * @param cfg configuration to use
87 (*GNUNET_SERVICE_Main) (void *cls,
88 struct GNUNET_SERVER_Handle *server,
89 const struct GNUNET_CONFIGURATION_Handle *cfg);
93 * Options for the service (bitmask).
95 enum GNUNET_SERVICE_Options
100 GNUNET_SERVICE_OPTION_NONE = 0,
103 * Do not trigger server shutdown on signals, allow for the user
104 * to terminate the server explicitly when needed.
106 GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN = 1,
109 * Trigger a SOFT server shutdown on signals, allowing active
110 * non-monitor clients to complete their transactions.
112 GNUNET_SERVICE_OPTION_SOFT_SHUTDOWN = 2
117 * Run a standard GNUnet service startup sequence (initialize loggers
118 * and configuration, parse options).
120 * @param argc number of command line arguments in @a argv
121 * @param argv command line arguments
122 * @param service_name our service name
123 * @param options service options
124 * @param task main task of the service
125 * @param task_cls closure for @a task
126 * @return #GNUNET_SYSERR on error, #GNUNET_OK
127 * if we shutdown nicely
131 GNUNET_SERVICE_run (int argc,
133 const char *service_name,
134 enum GNUNET_SERVICE_Options options,
135 GNUNET_SERVICE_Main task,
140 * Opaque handle for a service.
142 struct GNUNET_SERVICE_Context;
146 * Run a service startup sequence within an existing
147 * initialized system.
149 * @param service_name our service name
150 * @param cfg configuration to use
151 * @param options service options
152 * @return NULL on error, service handle
155 struct GNUNET_SERVICE_Context *
156 GNUNET_SERVICE_start (const char *service_name,
157 const struct GNUNET_CONFIGURATION_Handle *cfg,
158 enum GNUNET_SERVICE_Options options);
162 * Obtain the server used by a service. Note that the server must NOT
163 * be destroyed by the caller.
165 * @param ctx the service context returned from the start function
166 * @return handle to the server for this service, NULL if there is none
169 struct GNUNET_SERVER_Handle *
170 GNUNET_SERVICE_get_server (struct GNUNET_SERVICE_Context *ctx);
174 * Get the NULL-terminated array of listen sockets for this service.
176 * @param ctx service context to query
177 * @return NULL if there are no listen sockets, otherwise NULL-terminated
178 * array of listen sockets.
181 struct GNUNET_NETWORK_Handle *const *
182 GNUNET_SERVICE_get_listen_sockets (struct GNUNET_SERVICE_Context *ctx);
186 * Stop a service that was started with #GNUNET_SERVICE_start.
188 * @param sctx the service context returned from the start function
192 GNUNET_SERVICE_stop (struct GNUNET_SERVICE_Context *sctx);
195 /* **************** NEW SERVICE API ********************** */
200 struct GNUNET_SERVICE_Handle;
206 struct GNUNET_SERVICE_Client;
217 (*GNUNET_SERVICE_InitCallback)(void *cls,
218 const struct GNUNET_CONFIGURATION_Handle *cfg,
219 struct GNUNET_SERVICE_Handle *sh);
231 (*GNUNET_SERVICE_ConnectHandler)(void *cls,
232 struct GNUNET_SERVICE_Client *c,
233 struct GNUNET_MQ_Handle *mq);
241 * @param internal_cls
244 (*GNUNET_SERVICE_DisconnectHandler)(void *cls,
245 struct GNUNET_SERVICE_Client *c,
250 * Creates the "main" function for a GNUnet service. You
251 * should almost always use the #GNUNET_SERVICE_MAIN macro
252 * instead of calling this function directly (except
253 * for ARM, which should call this function directly).
255 * The function will launch the service with the name @a service_name
256 * using the @a service_options to configure its shutdown
257 * behavior. Once the service is ready, the @a init_cb will be called
258 * for service-specific initialization. @a init_cb will be given the
259 * service handler which can be used to control the service's
260 * availability. When clients connect or disconnect, the respective
261 * @a connect_cb or @a disconnect_cb functions will be called. For
262 * messages received from the clients, the respective @a handlers will
263 * be invoked; for the closure of the handlers we use the return value
264 * from the @a connect_cb invocation of the respective client.
266 * Each handler MUST call #GNUNET_SERVICE_client_continue() after each
267 * message to receive further messages from this client. If
268 * #GNUNET_SERVICE_client_continue() is not called within a short
269 * time, a warning will be logged. If delays are expected, services
270 * should call #GNUNET_SERVICE_client_disable_continue_warning() to
271 * disable the warning.
273 * Clients sending invalid messages (based on @a handlers) will be
274 * dropped. Additionally, clients can be dropped at any time using
275 * #GNUNET_SERVICE_client_drop().
279 * @param service_name
281 * @param service_init_cb
283 * @param disconnect_cb
286 * @return 0 on success, non-zero on error
289 GNUNET_SERVICE_ruN_ (int argc,
291 const char *service_name,
292 enum GNUNET_SERVICE_Options options,
293 GNUNET_SERVICE_InitCallback service_init_cb,
294 GNUNET_SERVICE_ConnectHandler connect_cb,
295 GNUNET_SERVICE_DisconnectHandler disconnect_cb,
297 const struct GNUNET_MQ_MessageHandler *handlers);
301 * Creates the "main" function for a GNUnet service. You
302 * MUST use this macro to define GNUnet services (except
303 * for ARM, which MUST NOT use the macro). The reason is
304 * the GNUnet-as-a-library project, where we will not define
305 * a main function anywhere but in ARM.
307 * The macro will launch the service with the name @a service_name
308 * using the @a service_options to configure its shutdown
309 * behavior. Once the service is ready, the @a init_cb will be called
310 * for service-specific initialization. @a init_cb will be given the
311 * service handler which can be used to control the service's
312 * availability. When clients connect or disconnect, the respective
313 * @a connect_cb or @a disconnect_cb functions will be called. For
314 * messages received from the clients, the respective @a handlers will
315 * be invoked; for the closure of the handlers we use the return value
316 * from the @a connect_cb invocation of the respective client.
318 * Each handler MUST call #GNUNET_SERVICE_client_continue() after each
319 * message to receive further messages from this client. If
320 * #GNUNET_SERVICE_client_continue() is not called within a short
321 * time, a warning will be logged. If delays are expected, services
322 * should call #GNUNET_SERVICE_client_disable_continue_warning() to
323 * disable the warning.
325 * Clients sending invalid messages (based on @a handlers) will be
326 * dropped. Additionally, clients can be dropped at any time using
327 * #GNUNET_SERVICE_client_drop().
331 * @param service_name
333 * @param service_init_cb
335 * @param disconnect_cb
338 * @return 0 on success, non-zero on error
340 #define GNUNET_SERVICE_MAIN(service_name,service_options,init_cb,connect_cb,disconnect_cb,cls,handlers) \
345 return GNUNET_SERVICE_ruN_ (argc, \
358 * Suspend accepting connections from the listen socket temporarily.
359 * Resume activity using #GNUNET_SERVICE_resume.
361 * @param sh service to stop accepting connections.
364 GNUNET_SERVICE_suspend (struct GNUNET_SERVICE_Handle *sh);
367 * Resume accepting connections from the listen socket.
369 * @param sh service to resume accepting connections.
372 GNUNET_SERVICE_resume (struct GNUNET_SERVICE_Handle *sh);
375 * Continue receiving further messages from the given client.
376 * Must be called after each message received.
378 * @param c the client to continue receiving from
381 GNUNET_SERVICE_client_continue (struct GNUNET_SERVICE_Client *c);
386 GNUNET_SERVICE_client_disable_continue_warning (struct GNUNET_SERVICE_Client *c);
393 GNUNET_SERVICE_client_drop (struct GNUNET_SERVICE_Client *c);
400 GNUNET_SERVICE_stop_listening (struct GNUNET_SERVICE_Handle *sh);
407 GNUNET_SERVICE_client_mark_monitor (struct GNUNET_SERVICE_Client *c);
414 GNUNET_SERVICE_client_persist (struct GNUNET_SERVICE_Client *c);
418 #if 0 /* keep Emacsens' auto-indent happy */
425 /* ifndef GNUNET_SERVICE_LIB_H */
428 /** @} */ /* end of group service */
430 /* end of gnunet_service_lib.h */