src/include/gnunet_service_lib.h

   1 /*
   2      This file is part of GNUnet.
   3      Copyright (C) 2009-2013, 2016 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_server_lib.h"
  48 #include "gnunet_mq_lib.h"
  49
  50
  51 /**
  52  * Get the list of addresses that a server for the given service
  53  * should bind to.
  54  *
  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
  62  *              array (on success)
  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
  69  *              set to NULL).
  70  */
  71 int
  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);
  76
  77
  78 /**
  79  * Function called by the service's run
  80  * method to run service-specific setup code.
  81  *
  82  * @param cls closure
  83  * @param server the initialized server
  84  * @param cfg configuration to use
  85  */
  86 typedef void
  87 (*GNUNET_SERVICE_Main) (void *cls,
  88                         struct GNUNET_SERVER_Handle *server,
  89                         const struct GNUNET_CONFIGURATION_Handle *cfg);
  90
  91
  92 /**
  93  * Options for the service (bitmask).
  94  */
  95 enum GNUNET_SERVICE_Options
  96 {
  97   /**
  98    * Use defaults.
  99    */
 100   GNUNET_SERVICE_OPTION_NONE = 0,
 101
 102   /**
 103    * Do not trigger server shutdown on signals, allow for the user
 104    * to terminate the server explicitly when needed.
 105    */
 106   GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN = 1,
 107
 108   /**
 109    * Trigger a SOFT server shutdown on signals, allowing active
 110    * non-monitor clients to complete their transactions.
 111    */
 112   GNUNET_SERVICE_OPTION_SOFT_SHUTDOWN = 2
 113 };
 114
 115
 116 /**
 117  * Run a standard GNUnet service startup sequence (initialize loggers
 118  * and configuration, parse options).
 119  *
 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
 128  * @deprecated
 129  */
 130 int
 131 GNUNET_SERVICE_run (int argc,
 132                     char *const *argv,
 133                     const char *service_name,
 134                     enum GNUNET_SERVICE_Options options,
 135                     GNUNET_SERVICE_Main task,
 136                     void *task_cls);
 137
 138
 139 /**
 140  * Opaque handle for a service.
 141  */
 142 struct GNUNET_SERVICE_Context;
 143
 144
 145 /**
 146  * Run a service startup sequence within an existing
 147  * initialized system.
 148  *
 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
 153  * @deprecated
 154  */
 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);
 159
 160
 161 /**
 162  * Obtain the server used by a service.  Note that the server must NOT
 163  * be destroyed by the caller.
 164  *
 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
 167  * @deprecated
 168  */
 169 struct GNUNET_SERVER_Handle *
 170 GNUNET_SERVICE_get_server (struct GNUNET_SERVICE_Context *ctx);
 171
 172
 173 /**
 174  * Get the NULL-terminated array of listen sockets for this service.
 175  *
 176  * @param ctx service context to query
 177  * @return NULL if there are no listen sockets, otherwise NULL-terminated
 178  *              array of listen sockets.
 179  * @deprecated
 180  */
 181 struct GNUNET_NETWORK_Handle *const *
 182 GNUNET_SERVICE_get_listen_sockets (struct GNUNET_SERVICE_Context *ctx);
 183
 184
 185 /**
 186  * Stop a service that was started with #GNUNET_SERVICE_start.
 187  *
 188  * @param sctx the service context returned from the start function
 189  * @deprecated
 190  */
 191 void
 192 GNUNET_SERVICE_stop (struct GNUNET_SERVICE_Context *sctx);
 193
 194
 195 /* **************** NEW SERVICE API ********************** */
 196
 197 /**
 198  *
 199  */
 200 struct GNUNET_SERVICE_Handle;
 201
 202
 203 /**
 204  *
 205  */
 206 struct GNUNET_SERVICE_Client;
 207
 208
 209 /**
 210  *
 211  *
 212  * @param cls
 213  * @param cfg
 214  * @param sh
 215  */
 216 typedef void
 217 (*GNUNET_SERVICE_InitCallback)(void *cls,
 218                                const struct GNUNET_CONFIGURATION_Handle *cfg,
 219                                struct GNUNET_SERVICE_Handle *sh);
 220
 221
 222 /**
 223  *
 224  *
 225  * @param cls
 226  * @param c
 227  * @param mq
 228  * @return
 229  */
 230 typedef void *
 231 (*GNUNET_SERVICE_ConnectHandler)(void *cls,
 232                                  struct GNUNET_SERVICE_Client *c,
 233                                  struct GNUNET_MQ_Handle *mq);
 234
 235
 236 /**
 237  *
 238  *
 239  * @param cls
 240  * @param c
 241  * @param internal_cls
 242  */
 243 typedef void
 244 (*GNUNET_SERVICE_DisconnectHandler)(void *cls,
 245                                     struct GNUNET_SERVICE_Client *c,
 246                                     void *internal_cls);
 247
 248
 249 /**
 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).
 254  *
 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.
 265  *
 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.
 272  *
 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().
 276  *
 277  * @param argc
 278  * @param argv
 279  * @param service_name
 280  * @param options
 281  * @param service_init_cb
 282  * @param connect_cb
 283  * @param disconnect_cb
 284  * @param cls
 285  * @param handlers
 286  * @return 0 on success, non-zero on error
 287  */
 288 int
 289 GNUNET_SERVICE_ruN_ (int argc,
 290                      char *const *argv,
 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,
 296                      void *cls,
 297                      const struct GNUNET_MQ_MessageHandler *handlers);
 298
 299
 300 /**
 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.
 306  *
 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.
 317  *
 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.
 324  *
 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().
 328  *
 329  * @param argc
 330  * @param argv
 331  * @param service_name
 332  * @param options
 333  * @param service_init_cb
 334  * @param connect_cb
 335  * @param disconnect_cb
 336  * @param cls
 337  * @param handlers
 338  * @return 0 on success, non-zero on error
 339  */
 340 #define GNUNET_SERVICE_MAIN(service_name,service_options,init_cb,connect_cb,disconnect_cb,cls,handlers) \
 341   int \
 342   main (int argc,\
 343         char *const *argv)\
 344   { \
 345     return GNUNET_SERVICE_ruN_ (argc, \
 346                                 argv, \
 347                                 service_name, \
 348                                 service_options, \
 349                                 init_cb, \
 350                                 connect_cb, \
 351                                 disconnect_cb, \
 352                                 cls, \
 353                                 handlers); \
 354   }
 355
 356
 357 /**
 358  * Suspend accepting connections from the listen socket temporarily.
 359  * Resume activity using #GNUNET_SERVICE_resume.
 360  *
 361  * @param sh service to stop accepting connections.
 362  */
 363 void
 364 GNUNET_SERVICE_suspend (struct GNUNET_SERVICE_Handle *sh);
 365
 366
 367 /**
 368  * Resume accepting connections from the listen socket.
 369  *
 370  * @param sh service to resume accepting connections.
 371  */
 372 void
 373 GNUNET_SERVICE_resume (struct GNUNET_SERVICE_Handle *sh);
 374
 375
 376 /**
 377  * Continue receiving further messages from the given client.
 378  * Must be called after each message received.
 379  *
 380  * @param c the client to continue receiving from
 381  */
 382 void
 383 GNUNET_SERVICE_client_continue (struct GNUNET_SERVICE_Client *c);
 384
 385
 386 /**
 387  * Disable the warning the server issues if a message is not
 388  * acknowledged in a timely fashion.  Use this call if a client is
 389  * intentionally delayed for a while.  Only applies to the current
 390  * message.
 391  *
 392  * @param c client for which to disable the warning
 393  */
 394 void
 395 GNUNET_SERVICE_client_disable_continue_warning (struct GNUNET_SERVICE_Client *c);
 396
 397
 398 /**
 399  * Ask the server to disconnect from the given client.  This is the
 400  * same as returning #GNUNET_SYSERR within the check procedure when
 401  * handling a message, wexcept that it allows dropping of a client even
 402  * when not handling a message from that client.
 403  *
 404  * @param c client to disconnect now
 405  */
 406 void
 407 GNUNET_SERVICE_client_drop (struct GNUNET_SERVICE_Client *c);
 408
 409
 410 /**
 411  * Stop the listen socket and get ready to shutdown the server once
 412  * only clients marked using #GNUNET_SERVER_client_mark_monitor are
 413  * left.
 414  *
 415  * @param sh server to stop listening on
 416  */
 417 void
 418 GNUNET_SERVICE_stop_listening (struct GNUNET_SERVICE_Handle *sh);
 419
 420
 421 /**
 422  * Set the 'monitor' flag on this client.  Clients which have been
 423  * marked as 'monitors' won't prevent the server from shutting down
 424  * once #GNUNET_SERVICE_stop_listening() has been invoked.  The idea is
 425  * that for "normal" clients we likely want to allow them to process
 426  * their requests; however, monitor-clients are likely to 'never'
 427  * disconnect during shutdown and thus will not be considered when
 428  * determining if the server should continue to exist after
 429  * shutdown has been triggered.
 430  *
 431  * @param c client to mark as a monitor
 432  */
 433 void
 434 GNUNET_SERVICE_client_mark_monitor (struct GNUNET_SERVICE_Client *c);
 435
 436
 437 /**
 438  * Set the persist option on this client.  Indicates that the
 439  * underlying socket or fd should never really be closed.  Used for
 440  * indicating process death.
 441  *
 442  * @param c client to persist the socket (never to be closed)
 443  */
 444 void
 445 GNUNET_SERVICE_client_persist (struct GNUNET_SERVICE_Client *c);
 446
 447
 448 #if 0                           /* keep Emacsens' auto-indent happy */
 449 {
 450 #endif
 451 #ifdef __cplusplus
 452 }
 453 #endif
 454
 455 /* ifndef GNUNET_SERVICE_LIB_H */
 456 #endif
 457
 458 /** @} */  /* end of group service */
 459
 460 /* end of gnunet_service_lib.h */