src/include/gnunet_service_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-2013, 2016, 2017 GNUnet e.V.
   4
   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.
   9
  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.
  14
  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.
  19 */
  20
  21 /**
  22  * @author Christian Grothoff
  23  *
  24  * @file
  25  * Functions related to starting services
  26  *
  27  * @defgroup service  Service library
  28  * Start service processes.
  29  *
  30  * @see [Documentation](https://gnunet.org/developer-handbook-util-services)
  31  *
  32  * @{
  33  */
  34
  35 #ifndef GNUNET_SERVICE_LIB_H
  36 #define GNUNET_SERVICE_LIB_H
  37
  38 #ifdef __cplusplus
  39 extern "C"
  40 {
  41 #if 0                           /* keep Emacsens' auto-indent happy */
  42 }
  43 #endif
  44 #endif
  45
  46 #include "gnunet_configuration_lib.h"
  47 #include "gnunet_mq_lib.h"
  48
  49
  50 /**
  51  * Options for the service (bitmask).
  52  */
  53 enum GNUNET_SERVICE_Options
  54 {
  55   /**
  56    * Use defaults.  Terminates all client connections and the listen
  57    * sockets immediately upon receiving the shutdown signal.
  58    */
  59   GNUNET_SERVICE_OPTION_NONE = 0,
  60
  61   /**
  62    * Do not trigger server shutdown on signal at all; instead, allow
  63    * for the user to terminate the server explicitly when needed
  64    * by calling #GNUNET_SERVICE_shutdown().
  65    */
  66   GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN = 1,
  67
  68   /**
  69    * Trigger a SOFT server shutdown on signals, allowing active
  70    * non-monitor clients to complete their transactions.
  71    */
  72   GNUNET_SERVICE_OPTION_SOFT_SHUTDOWN = 2
  73 };
  74
  75
  76
  77 /* **************** NEW SERVICE API ********************** */
  78
  79 /**
  80  * Handle to a service.
  81  */
  82 struct GNUNET_SERVICE_Handle;
  83
  84
  85 /**
  86  * Handle to a client that is connected to a service.
  87  */
  88 struct GNUNET_SERVICE_Client;
  89
  90
  91 /**
  92  * Callback to initialize a service, called exactly once when the service is run.
  93  *
  94  * @param cls closure passed to #GNUNET_SERVICE_MAIN
  95  * @param cfg configuration to use for this service
  96  * @param sh handle to the newly create service
  97  */
  98 typedef void
  99 (*GNUNET_SERVICE_InitCallback)(void *cls,
 100                                const struct GNUNET_CONFIGURATION_Handle *cfg,
 101                                struct GNUNET_SERVICE_Handle *sh);
 102
 103
 104 /**
 105  * Callback to be called when a client connects to the service.
 106  *
 107  * @param cls closure for the service
 108  * @param c the new client that connected to the service
 109  * @param mq the message queue used to send messages to the client
 110  * @return the client-specific (`internal') closure
 111  */
 112 typedef void *
 113 (*GNUNET_SERVICE_ConnectHandler)(void *cls,
 114                                  struct GNUNET_SERVICE_Client *c,
 115                                  struct GNUNET_MQ_Handle *mq);
 116
 117
 118 /**
 119  * Callback to be called when a client disconnected from the service
 120  *
 121  * @param cls closure for the service
 122  * @param c the client that disconnected
 123  * @param internal_cls the client-specific (`internal') closure
 124  */
 125 typedef void
 126 (*GNUNET_SERVICE_DisconnectHandler)(void *cls,
 127                                     struct GNUNET_SERVICE_Client *c,
 128                                     void *internal_cls);
 129
 130
 131 /**
 132  * Low-level function to start a service if the scheduler
 133  * is already running.  Should only be used directly in
 134  * special cases.
 135  *
 136  * The function will launch the service with the name @a service_name
 137  * using the @a service_options to configure its shutdown
 138  * behavior. When clients connect or disconnect, the respective
 139  * @a connect_cb or @a disconnect_cb functions will be called. For
 140  * messages received from the clients, the respective @a handlers will
 141  * be invoked; for the closure of the handlers we use the return value
 142  * from the @a connect_cb invocation of the respective client.
 143  *
 144  * Each handler MUST call #GNUNET_SERVICE_client_continue() after each
 145  * message to receive further messages from this client.  If
 146  * #GNUNET_SERVICE_client_continue() is not called within a short
 147  * time, a warning will be logged. If delays are expected, services
 148  * should call #GNUNET_SERVICE_client_disable_continue_warning() to
 149  * disable the warning.
 150  *
 151  * Clients sending invalid messages (based on @a handlers) will be
 152  * dropped. Additionally, clients can be dropped at any time using
 153  * #GNUNET_SERVICE_client_drop().
 154  *
 155  * The service must be stopped using #GNUNET_SERVICE_stop().
 156  *
 157  * @param service_name name of the service to run
 158  * @param cfg configuration to use
 159  * @param connect_cb function to call whenever a client connects
 160  * @param disconnect_cb function to call whenever a client disconnects
 161  * @param cls closure argument for @a connect_cb and @a disconnect_cb
 162  * @param handlers NULL-terminated array of message handlers for the service,
 163  *                 the closure will be set to the value returned by
 164  *                 the @a connect_cb for the respective connection
 165  * @return NULL on error
 166  */
 167 struct GNUNET_SERVICE_Handle *
 168 GNUNET_SERVICE_start (const char *service_name,
 169                       const struct GNUNET_CONFIGURATION_Handle *cfg,
 170                       GNUNET_SERVICE_ConnectHandler connect_cb,
 171                       GNUNET_SERVICE_DisconnectHandler disconnect_cb,
 172                       void *cls,
 173                       const struct GNUNET_MQ_MessageHandler *handlers);
 174
 175
 176 /**
 177  * Stops a service that was started with #GNUNET_SERVICE_start().
 178  *
 179  * @param srv service to stop
 180  */
 181 void
 182 GNUNET_SERVICE_stop (struct GNUNET_SERVICE_Handle *srv);
 183
 184
 185 /**
 186  * Creates the "main" function for a GNUnet service.  You
 187  * should almost always use the #GNUNET_SERVICE_MAIN macro
 188  * instead of calling this function directly (except
 189  * for ARM, which should call this function directly).
 190  *
 191  * The function will launch the service with the name @a service_name
 192  * using the @a service_options to configure its shutdown
 193  * behavior. Once the service is ready, the @a init_cb will be called
 194  * for service-specific initialization.  @a init_cb will be given the
 195  * service handler which can be used to control the service's
 196  * availability.  When clients connect or disconnect, the respective
 197  * @a connect_cb or @a disconnect_cb functions will be called. For
 198  * messages received from the clients, the respective @a handlers will
 199  * be invoked; for the closure of the handlers we use the return value
 200  * from the @a connect_cb invocation of the respective client.
 201  *
 202  * Each handler MUST call #GNUNET_SERVICE_client_continue() after each
 203  * message to receive further messages from this client.  If
 204  * #GNUNET_SERVICE_client_continue() is not called within a short
 205  * time, a warning will be logged. If delays are expected, services
 206  * should call #GNUNET_SERVICE_client_disable_continue_warning() to
 207  * disable the warning.
 208  *
 209  * Clients sending invalid messages (based on @a handlers) will be
 210  * dropped. Additionally, clients can be dropped at any time using
 211  * #GNUNET_SERVICE_client_drop().
 212  *
 213  * @param argc number of command-line arguments in @a argv
 214  * @param argv array of command-line arguments
 215  * @param service_name name of the service to run
 216  * @param options options controlling shutdown of the service
 217  * @param service_init_cb function to call once the service is ready
 218  * @param connect_cb function to call whenever a client connects
 219  * @param disconnect_cb function to call whenever a client disconnects
 220  * @param cls closure argument for @a service_init_cb, @a connect_cb and @a disconnect_cb
 221  * @param handlers NULL-terminated array of message handlers for the service,
 222  *                 the closure will be set to the value returned by
 223  *                 the @a connect_cb for the respective connection
 224  * @return 0 on success, non-zero on error
 225  */
 226 int
 227 GNUNET_SERVICE_run_ (int argc,
 228                      char *const *argv,
 229                      const char *service_name,
 230                      enum GNUNET_SERVICE_Options options,
 231                      GNUNET_SERVICE_InitCallback service_init_cb,
 232                      GNUNET_SERVICE_ConnectHandler connect_cb,
 233                      GNUNET_SERVICE_DisconnectHandler disconnect_cb,
 234                      void *cls,
 235                      const struct GNUNET_MQ_MessageHandler *handlers);
 236
 237
 238 /**
 239  * Creates the "main" function for a GNUnet service.  You
 240  * MUST use this macro to define GNUnet services (except
 241  * for ARM, which MUST NOT use the macro).  The reason is
 242  * the GNUnet-as-a-library project, where we will not define
 243  * a main function anywhere but in ARM.
 244  *
 245  * The macro will launch the service with the name @a service_name
 246  * using the @a service_options to configure its shutdown
 247  * behavior. Once the service is ready, the @a init_cb will be called
 248  * for service-specific initialization.  @a init_cb will be given the
 249  * service handler which can be used to control the service's
 250  * availability.  When clients connect or disconnect, the respective
 251  * @a connect_cb or @a disconnect_cb functions will be called. For
 252  * messages received from the clients, the respective @a handlers will
 253  * be invoked; for the closure of the handlers we use the return value
 254  * from the @a connect_cb invocation of the respective client.
 255  *
 256  * Each handler MUST call #GNUNET_SERVICE_client_continue() after each
 257  * message to receive further messages from this client.  If
 258  * #GNUNET_SERVICE_client_continue() is not called within a short
 259  * time, a warning will be logged. If delays are expected, services
 260  * should call #GNUNET_SERVICE_client_disable_continue_warning() to
 261  * disable the warning.
 262  *
 263  * Clients sending invalid messages (based on @a handlers) will be
 264  * dropped. Additionally, clients can be dropped at any time using
 265  * #GNUNET_SERVICE_client_drop().
 266  *
 267  * @param service_name name of the service to run
 268  * @param options options controlling shutdown of the service
 269  * @param service_init_cb function to call once the service is ready
 270  * @param connect_cb function to call whenever a client connects
 271  * @param disconnect_cb function to call whenever a client disconnects
 272  * @param cls closure argument for @a service_init_cb, @a connect_cb and @a disconnect_cb
 273  * @param ... array of message handlers for the service, terminated
 274  *            by #GNUNET_MQ_handler_end();
 275  *                 the closure will be set to the value returned by
 276  *                 the @a connect_cb for the respective connection
 277  * @return 0 on success, non-zero on error
 278  *
 279  * Sample invocation:
 280  * <code>
 281  * GNUNET_SERVICE_MAIN
 282  * ("resolver",
 283  *  GNUNET_SERVICE_OPTION_NONE,
 284  *  &init_cb,
 285  *  &connect_cb,
 286  *  &disconnect_cb,
 287  *  closure_for_cb,
 288  *  GNUNET_MQ_hd_var_size (get,
 289  *                         GNUNET_MESSAGE_TYPE_RESOLVER_REQUEST,
 290  *                         struct GNUNET_RESOLVER_GetMessage,
 291  *                         NULL),
 292  *  GNUNET_MQ_handler_end ());
 293  * </code>
 294  */
 295 #define GNUNET_SERVICE_MAIN(service_name,service_options,init_cb,connect_cb,disconnect_cb,cls,...) \
 296   int \
 297   main (int argc,\
 298         char *const *argv)\
 299   { \
 300     struct GNUNET_MQ_MessageHandler mh[] = { \
 301       __VA_ARGS__ \
 302     };                        \
 303     return GNUNET_SERVICE_run_ (argc, \
 304                                 argv, \
 305                                 service_name, \
 306                                 service_options, \
 307                                 init_cb, \
 308                                 connect_cb, \
 309                                 disconnect_cb, \
 310                                 cls, \
 311                                 mh); \
 312   }
 313
 314
 315 /**
 316  * Suspend accepting connections from the listen socket temporarily.
 317  * Resume activity using #GNUNET_SERVICE_resume.
 318  *
 319  * @param sh service to stop accepting connections.
 320  */
 321 void
 322 GNUNET_SERVICE_suspend (struct GNUNET_SERVICE_Handle *sh);
 323
 324
 325 /**
 326  * Resume accepting connections from the listen socket.
 327  *
 328  * @param sh service to resume accepting connections.
 329  */
 330 void
 331 GNUNET_SERVICE_resume (struct GNUNET_SERVICE_Handle *sh);
 332
 333
 334 /**
 335  * Continue receiving further messages from the given client.
 336  * Must be called after each message received.
 337  *
 338  * @param c the client to continue receiving from
 339  */
 340 void
 341 GNUNET_SERVICE_client_continue (struct GNUNET_SERVICE_Client *c);
 342
 343
 344 /**
 345  * Obtain the message queue of @a c.  Convenience function.
 346  *
 347  * @param c the client to continue receiving from
 348  * @return the message queue of @a c
 349  */
 350 struct GNUNET_MQ_Handle *
 351 GNUNET_SERVICE_client_get_mq (struct GNUNET_SERVICE_Client *c);
 352
 353
 354 /**
 355  * Disable the warning the server issues if a message is not
 356  * acknowledged in a timely fashion.  Use this call if a client is
 357  * intentionally delayed for a while.  Only applies to the current
 358  * message.
 359  *
 360  * @param c client for which to disable the warning
 361  */
 362 void
 363 GNUNET_SERVICE_client_disable_continue_warning (struct GNUNET_SERVICE_Client *c);
 364
 365
 366 /**
 367  * Ask the server to disconnect from the given client.  This is the
 368  * same as returning #GNUNET_SYSERR within the check procedure when
 369  * handling a message, wexcept that it allows dropping of a client even
 370  * when not handling a message from that client.  The `disconnect_cb`
 371  * will be called on @a c even if the application closes the connection
 372  * using this function.
 373  *
 374  * @param c client to disconnect now
 375  */
 376 void
 377 GNUNET_SERVICE_client_drop (struct GNUNET_SERVICE_Client *c);
 378
 379
 380 /**
 381  * Explicitly stops the service.
 382  *
 383  * @param sh server to shutdown
 384  */
 385 void
 386 GNUNET_SERVICE_shutdown (struct GNUNET_SERVICE_Handle *sh);
 387
 388
 389 /**
 390  * Set the 'monitor' flag on this client.  Clients which have been
 391  * marked as 'monitors' won't prevent the server from shutting down
 392  * once #GNUNET_SERVICE_stop_listening() has been invoked.  The idea is
 393  * that for "normal" clients we likely want to allow them to process
 394  * their requests; however, monitor-clients are likely to 'never'
 395  * disconnect during shutdown and thus will not be considered when
 396  * determining if the server should continue to exist after
 397  * shutdown has been triggered.
 398  *
 399  * @param c client to mark as a monitor
 400  */
 401 void
 402 GNUNET_SERVICE_client_mark_monitor (struct GNUNET_SERVICE_Client *c);
 403
 404
 405 /**
 406  * Set the persist option on this client.  Indicates that the
 407  * underlying socket or fd should never really be closed.  Used for
 408  * indicating process death.
 409  *
 410  * @param c client to persist the socket (never to be closed)
 411  */
 412 void
 413 GNUNET_SERVICE_client_persist (struct GNUNET_SERVICE_Client *c);
 414
 415
 416 #if 0                           /* keep Emacsens' auto-indent happy */
 417 {
 418 #endif
 419 #ifdef __cplusplus
 420 }
 421 #endif
 422
 423 /* ifndef GNUNET_SERVICE_LIB_H */
 424 #endif
 425
 426 /** @} */  /* end of group service */
 427
 428 /* end of gnunet_service_lib.h */