2 This file is part of GNUnet.
3 Copyright (C) 2009-2013, 2016, 2017 GNUnet e.V.
5 GNUnet is free software: you can redistribute it and/or modify it
6 under the terms of the GNU Affero General Public License as published
7 by the Free Software Foundation, either version 3 of the License,
8 or (at your 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 Affero General Public License for more details.
15 You should have received a copy of the GNU Affero General Public License
16 along with this program. If not, see <http://www.gnu.org/licenses/>.
20 * @author Christian Grothoff
23 * Functions related to starting services
25 * @defgroup service Service library
26 * Start service processes.
28 * @see [Documentation](https://gnunet.org/developer-handbook-util-services)
33 #ifndef GNUNET_SERVICE_LIB_H
34 #define GNUNET_SERVICE_LIB_H
39 #if 0 /* keep Emacsens' auto-indent happy */
44 #include "gnunet_configuration_lib.h"
45 #include "gnunet_mq_lib.h"
49 * Options for the service (bitmask).
51 enum GNUNET_SERVICE_Options
54 * Use defaults. Terminates all client connections and the listen
55 * sockets immediately upon receiving the shutdown signal.
57 GNUNET_SERVICE_OPTION_NONE = 0,
60 * Do not trigger server shutdown on signal at all; instead, allow
61 * for the user to terminate the server explicitly when needed
62 * by calling #GNUNET_SERVICE_shutdown().
64 GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN = 1,
67 * Trigger a SOFT server shutdown on signals, allowing active
68 * non-monitor clients to complete their transactions.
70 GNUNET_SERVICE_OPTION_SOFT_SHUTDOWN = 2
75 /* **************** NEW SERVICE API ********************** */
78 * Handle to a service.
80 struct GNUNET_SERVICE_Handle;
84 * Handle to a client that is connected to a service.
86 struct GNUNET_SERVICE_Client;
90 * Callback to initialize a service, called exactly once when the service is run.
92 * @param cls closure passed to #GNUNET_SERVICE_MAIN
93 * @param cfg configuration to use for this service
94 * @param sh handle to the newly create service
97 (*GNUNET_SERVICE_InitCallback)(void *cls,
98 const struct GNUNET_CONFIGURATION_Handle *cfg,
99 struct GNUNET_SERVICE_Handle *sh);
103 * Callback to be called when a client connects to the service.
105 * @param cls closure for the service
106 * @param c the new client that connected to the service
107 * @param mq the message queue used to send messages to the client
108 * @return the client-specific (`internal') closure
111 (*GNUNET_SERVICE_ConnectHandler)(void *cls,
112 struct GNUNET_SERVICE_Client *c,
113 struct GNUNET_MQ_Handle *mq);
117 * Callback to be called when a client disconnected from the service
119 * @param cls closure for the service
120 * @param c the client that disconnected
121 * @param internal_cls the client-specific (`internal') closure
124 (*GNUNET_SERVICE_DisconnectHandler)(void *cls,
125 struct GNUNET_SERVICE_Client *c,
130 * Low-level function to start a service if the scheduler
131 * is already running. Should only be used directly in
134 * The function will launch the service with the name @a service_name
135 * using the @a service_options to configure its shutdown
136 * behavior. When clients connect or disconnect, the respective
137 * @a connect_cb or @a disconnect_cb functions will be called. For
138 * messages received from the clients, the respective @a handlers will
139 * be invoked; for the closure of the handlers we use the return value
140 * from the @a connect_cb invocation of the respective client.
142 * Each handler MUST call #GNUNET_SERVICE_client_continue() after each
143 * message to receive further messages from this client. If
144 * #GNUNET_SERVICE_client_continue() is not called within a short
145 * time, a warning will be logged. If delays are expected, services
146 * should call #GNUNET_SERVICE_client_disable_continue_warning() to
147 * disable the warning.
149 * Clients sending invalid messages (based on @a handlers) will be
150 * dropped. Additionally, clients can be dropped at any time using
151 * #GNUNET_SERVICE_client_drop().
153 * The service must be stopped using #GNUNET_SERVICE_stop().
155 * @param service_name name of the service to run
156 * @param cfg configuration to use
157 * @param connect_cb function to call whenever a client connects
158 * @param disconnect_cb function to call whenever a client disconnects
159 * @param cls closure argument for @a connect_cb and @a disconnect_cb
160 * @param handlers NULL-terminated array of message handlers for the service,
161 * the closure will be set to the value returned by
162 * the @a connect_cb for the respective connection
163 * @return NULL on error
165 struct GNUNET_SERVICE_Handle *
166 GNUNET_SERVICE_start (const char *service_name,
167 const struct GNUNET_CONFIGURATION_Handle *cfg,
168 GNUNET_SERVICE_ConnectHandler connect_cb,
169 GNUNET_SERVICE_DisconnectHandler disconnect_cb,
171 const struct GNUNET_MQ_MessageHandler *handlers);
175 * Stops a service that was started with #GNUNET_SERVICE_start().
177 * @param srv service to stop
180 GNUNET_SERVICE_stop (struct GNUNET_SERVICE_Handle *srv);
184 * Creates the "main" function for a GNUnet service. You
185 * should almost always use the #GNUNET_SERVICE_MAIN macro
186 * instead of calling this function directly (except
187 * for ARM, which should call this function directly).
189 * The function will launch the service with the name @a service_name
190 * using the @a service_options to configure its shutdown
191 * behavior. Once the service is ready, the @a init_cb will be called
192 * for service-specific initialization. @a init_cb will be given the
193 * service handler which can be used to control the service's
194 * availability. When clients connect or disconnect, the respective
195 * @a connect_cb or @a disconnect_cb functions will be called. For
196 * messages received from the clients, the respective @a handlers will
197 * be invoked; for the closure of the handlers we use the return value
198 * from the @a connect_cb invocation of the respective client.
200 * Each handler MUST call #GNUNET_SERVICE_client_continue() after each
201 * message to receive further messages from this client. If
202 * #GNUNET_SERVICE_client_continue() is not called within a short
203 * time, a warning will be logged. If delays are expected, services
204 * should call #GNUNET_SERVICE_client_disable_continue_warning() to
205 * disable the warning.
207 * Clients sending invalid messages (based on @a handlers) will be
208 * dropped. Additionally, clients can be dropped at any time using
209 * #GNUNET_SERVICE_client_drop().
211 * @param argc number of command-line arguments in @a argv
212 * @param argv array of command-line arguments
213 * @param service_name name of the service to run
214 * @param options options controlling shutdown of the service
215 * @param service_init_cb function to call once the service is ready
216 * @param connect_cb function to call whenever a client connects
217 * @param disconnect_cb function to call whenever a client disconnects
218 * @param cls closure argument for @a service_init_cb, @a connect_cb and @a disconnect_cb
219 * @param handlers NULL-terminated array of message handlers for the service,
220 * the closure will be set to the value returned by
221 * the @a connect_cb for the respective connection
222 * @return 0 on success, non-zero on error
225 GNUNET_SERVICE_run_ (int argc,
227 const char *service_name,
228 enum GNUNET_SERVICE_Options options,
229 GNUNET_SERVICE_InitCallback service_init_cb,
230 GNUNET_SERVICE_ConnectHandler connect_cb,
231 GNUNET_SERVICE_DisconnectHandler disconnect_cb,
233 const struct GNUNET_MQ_MessageHandler *handlers);
237 * Creates the "main" function for a GNUnet service. You
238 * MUST use this macro to define GNUnet services (except
239 * for ARM, which MUST NOT use the macro). The reason is
240 * the GNUnet-as-a-library project, where we will not define
241 * a main function anywhere but in ARM.
243 * The macro will launch the service with the name @a service_name
244 * using the @a service_options to configure its shutdown
245 * behavior. Once the service is ready, the @a init_cb will be called
246 * for service-specific initialization. @a init_cb will be given the
247 * service handler which can be used to control the service's
248 * availability. When clients connect or disconnect, the respective
249 * @a connect_cb or @a disconnect_cb functions will be called. For
250 * messages received from the clients, the respective @a handlers will
251 * be invoked; for the closure of the handlers we use the return value
252 * from the @a connect_cb invocation of the respective client.
254 * Each handler MUST call #GNUNET_SERVICE_client_continue() after each
255 * message to receive further messages from this client. If
256 * #GNUNET_SERVICE_client_continue() is not called within a short
257 * time, a warning will be logged. If delays are expected, services
258 * should call #GNUNET_SERVICE_client_disable_continue_warning() to
259 * disable the warning.
261 * Clients sending invalid messages (based on @a handlers) will be
262 * dropped. Additionally, clients can be dropped at any time using
263 * #GNUNET_SERVICE_client_drop().
265 * @param service_name name of the service to run
266 * @param options options controlling shutdown of the service
267 * @param service_init_cb function to call once the service is ready
268 * @param connect_cb function to call whenever a client connects
269 * @param disconnect_cb function to call whenever a client disconnects
270 * @param cls closure argument for @a service_init_cb, @a connect_cb and @a disconnect_cb
271 * @param ... array of message handlers for the service, terminated
272 * by #GNUNET_MQ_handler_end();
273 * the closure will be set to the value returned by
274 * the @a connect_cb for the respective connection
275 * @return 0 on success, non-zero on error
279 * GNUNET_SERVICE_MAIN
281 * GNUNET_SERVICE_OPTION_NONE,
286 * GNUNET_MQ_hd_var_size (get,
287 * GNUNET_MESSAGE_TYPE_RESOLVER_REQUEST,
288 * struct GNUNET_RESOLVER_GetMessage,
290 * GNUNET_MQ_handler_end ());
293 #define GNUNET_SERVICE_MAIN(service_name,service_options,init_cb,connect_cb,disconnect_cb,cls,...) \
298 struct GNUNET_MQ_MessageHandler mh[] = { \
301 return GNUNET_SERVICE_run_ (argc, \
314 * Suspend accepting connections from the listen socket temporarily.
315 * Resume activity using #GNUNET_SERVICE_resume.
317 * @param sh service to stop accepting connections.
320 GNUNET_SERVICE_suspend (struct GNUNET_SERVICE_Handle *sh);
324 * Resume accepting connections from the listen socket.
326 * @param sh service to resume accepting connections.
329 GNUNET_SERVICE_resume (struct GNUNET_SERVICE_Handle *sh);
333 * Continue receiving further messages from the given client.
334 * Must be called after each message received.
336 * @param c the client to continue receiving from
339 GNUNET_SERVICE_client_continue (struct GNUNET_SERVICE_Client *c);
343 * Obtain the message queue of @a c. Convenience function.
345 * @param c the client to continue receiving from
346 * @return the message queue of @a c
348 struct GNUNET_MQ_Handle *
349 GNUNET_SERVICE_client_get_mq (struct GNUNET_SERVICE_Client *c);
353 * Disable the warning the server issues if a message is not
354 * acknowledged in a timely fashion. Use this call if a client is
355 * intentionally delayed for a while. Only applies to the current
358 * @param c client for which to disable the warning
361 GNUNET_SERVICE_client_disable_continue_warning (struct GNUNET_SERVICE_Client *c);
365 * Ask the server to disconnect from the given client. This is the
366 * same as returning #GNUNET_SYSERR within the check procedure when
367 * handling a message, except that it allows dropping of a client even
368 * when not handling a message from that client. The `disconnect_cb`
369 * will be called on @a c even if the application closes the connection
370 * using this function.
372 * This function should be called (outside of util's internal logic)
373 * if (and usually only if) the client has violated the
374 * protocol. Otherwise, we should leave it to the client to disconnect
377 * @param c client to disconnect now
380 GNUNET_SERVICE_client_drop (struct GNUNET_SERVICE_Client *c);
384 * Explicitly stops the service.
386 * @param sh server to shutdown
389 GNUNET_SERVICE_shutdown (struct GNUNET_SERVICE_Handle *sh);
393 * Set the 'monitor' flag on this client. Clients which have been
394 * marked as 'monitors' won't prevent the server from shutting down
395 * once #GNUNET_SERVICE_stop_listening() has been invoked. The idea is
396 * that for "normal" clients we likely want to allow them to process
397 * their requests; however, monitor-clients are likely to 'never'
398 * disconnect during shutdown and thus will not be considered when
399 * determining if the server should continue to exist after
400 * shutdown has been triggered.
402 * @param c client to mark as a monitor
405 GNUNET_SERVICE_client_mark_monitor (struct GNUNET_SERVICE_Client *c);
409 * Set the persist option on this client. Indicates that the
410 * underlying socket or fd should never really be closed. Used for
411 * indicating process death.
413 * @param c client to persist the socket (never to be closed)
416 GNUNET_SERVICE_client_persist (struct GNUNET_SERVICE_Client *c);
419 #if 0 /* keep Emacsens' auto-indent happy */
426 /* ifndef GNUNET_SERVICE_LIB_H */
429 /** @} */ /* end of group service */
431 /* end of gnunet_service_lib.h */