Service library

Start service processes. More...

Collaboration diagram for Service library:

Macros
#define	GNUNET_SERVICE_MAIN(pd, service_name, service_options, init_cb, connect_cb, disconnect_cb, cls, ...)
	Creates the "main" function for a GNUnet service. More...

Typedefs
typedef void(*	GNUNET_SERVICE_InitCallback) (void *cls, const struct GNUNET_CONFIGURATION_Handle *cfg, struct GNUNET_SERVICE_Handle *sh)
	Callback to initialize a service, called exactly once when the service is run. More...
typedef void *(*	GNUNET_SERVICE_ConnectHandler) (void *cls, struct GNUNET_SERVICE_Client *c, struct GNUNET_MQ_Handle *mq)
	Callback to be called when a client connects to the service. More...
typedef void(*	GNUNET_SERVICE_DisconnectHandler) (void *cls, struct GNUNET_SERVICE_Client *c, void *internal_cls)
	Callback to be called when a client disconnected from the service. More...

Enumerations
enum	GNUNET_SERVICE_Options {   GNUNET_SERVICE_OPTION_NONE = 0 , GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN = 1 , GNUNET_SERVICE_OPTION_SOFT_SHUTDOWN = 2 , GNUNET_SERVICE_OPTION_SHUTDOWN_BITMASK = 3 ,   GNUNET_SERVICE_OPTION_CLOSE_LSOCKS = 4 }
	Options for the service (bitmask). More...

Functions
struct GNUNET_SERVICE_Handle *	GNUNET_SERVICE_start (const struct GNUNET_OS_ProjectData *pd, const char *service_name, const struct GNUNET_CONFIGURATION_Handle *cfg, GNUNET_SERVICE_ConnectHandler connect_cb, GNUNET_SERVICE_DisconnectHandler disconnect_cb, void *cls, const struct GNUNET_MQ_MessageHandler *handlers)
	Low-level function to start a service if the scheduler is already running. More...
void	GNUNET_SERVICE_stop (struct GNUNET_SERVICE_Handle *srv)
	Stops a service that was started with GNUNET_SERVICE_start(). More...
int	GNUNET_SERVICE_run_ (const struct GNUNET_OS_ProjectData *pd, int argc, char *const *argv, const char *service_name, enum GNUNET_SERVICE_Options options, GNUNET_SERVICE_InitCallback service_init_cb, GNUNET_SERVICE_ConnectHandler connect_cb, GNUNET_SERVICE_DisconnectHandler disconnect_cb, void *cls, const struct GNUNET_MQ_MessageHandler *handlers)
	Creates the "main" function for a GNUnet service. More...
int	GNUNET_SERVICE_register_ (const struct GNUNET_OS_ProjectData *pd, const char *service_name, enum GNUNET_SERVICE_Options options, GNUNET_SERVICE_InitCallback service_init_cb, GNUNET_SERVICE_ConnectHandler connect_cb, GNUNET_SERVICE_DisconnectHandler disconnect_cb, void *cls, const struct GNUNET_MQ_MessageHandler *handlers)
	Registers the GNUnet service to be scheduled as part of a monilithic libgnunet. More...
void	GNUNET_SERVICE_main (const struct GNUNET_OS_ProjectData *pd, int argc, char *const *argv, struct GNUNET_CONFIGURATION_Handle *cfg, enum GNUNET_GenericReturnValue with_scheduler)
	Run the mainloop in a monolithic libgnunet. More...
void	GNUNET_SERVICE_suspend (struct GNUNET_SERVICE_Handle *sh)
	Suspend accepting connections from the listen socket temporarily. More...
void	GNUNET_SERVICE_resume (struct GNUNET_SERVICE_Handle *sh)
	Resume accepting connections from the listen socket. More...
void	GNUNET_SERVICE_client_continue (struct GNUNET_SERVICE_Client *c)
	Continue receiving further messages from the given client. More...
struct GNUNET_MQ_Handle *	GNUNET_SERVICE_client_get_mq (struct GNUNET_SERVICE_Client *c)
	Obtain the message queue of c. More...
void	GNUNET_SERVICE_client_disable_continue_warning (struct GNUNET_SERVICE_Client *c)
	Disable the warning the server issues if a message is not acknowledged in a timely fashion. More...
void	GNUNET_SERVICE_client_drop (struct GNUNET_SERVICE_Client *c)
	Ask the server to disconnect from the given client. More...
void	GNUNET_SERVICE_shutdown (struct GNUNET_SERVICE_Handle *sh)
	Explicitly stops the service. More...
void	GNUNET_SERVICE_client_mark_monitor (struct GNUNET_SERVICE_Client *c)
	Set the 'monitor' flag on this client. More...
void	GNUNET_SERVICE_client_persist (struct GNUNET_SERVICE_Client *c)
	Set the persist option on this client. More...

Detailed Description

Start service processes.

See also

Documentation

Macro Definition Documentation

GNUNET_SERVICE_MAIN

#define GNUNET_SERVICE_MAIN	(		pd,
			service_name,
			service_options,
			init_cb,
			connect_cb,
			disconnect_cb,
			cls,
			...
	)

Value:

        int \
        main (int argc, \
              char *const *argv) \
        { \
          struct GNUNET_MQ_MessageHandler mh[] = { \
            __VA_ARGS__ \
          };                        \
          return GNUNET_SERVICE_run_ (pd, \
                                      argc, \
                                      argv, \
                                      service_name, \
                                      service_options, \
                                      init_cb, \
                                      connect_cb, \
                                      disconnect_cb, \
                                      cls, \
                                      mh); \
        }

Creates the "main" function for a GNUnet service.

You MUST use this macro to define GNUnet services (except for ARM, which MUST NOT use the macro). The reason is the GNUnet-as-a-library project, where we will not define a main function anywhere but in ARM.

The macro will launch the service with the name service_name using the service_options to configure its shutdown behavior. Once the service is ready, the init_cb will be called for service-specific initialization. init_cb will be given the service handler which can be used to control the service's availability. When clients connect or disconnect, the respective connect_cb or disconnect_cb functions will be called. For messages received from the clients, the respective handlers will be invoked; for the closure of the handlers we use the return value from the connect_cb invocation of the respective client.

Each handler MUST call GNUNET_SERVICE_client_continue() after each message to receive further messages from this client. If GNUNET_SERVICE_client_continue() is not called within a short time, a warning will be logged. If delays are expected, services should call GNUNET_SERVICE_client_disable_continue_warning() to disable the warning.

Clients sending invalid messages (based on handlers) will be dropped. Additionally, clients can be dropped at any time using GNUNET_SERVICE_client_drop().

Parameters

service_name	name of the service to run
service_options	options controlling shutdown of the service
init_cb	function to call once the service is ready
connect_cb	function to call whenever a client connects
disconnect_cb	function to call whenever a client disconnects
cls	closure argument for service_init_cb, connect_cb and disconnect_cb
...	array of message handlers for the service, terminated by GNUNET_MQ_handler_end(); the closure will be set to the value returned by the connect_cb for the respective connection

Returns

0 on success, non-zero on error

Sample invocation: GNUNET_SERVICE_MAIN ("resolver", GNUNET_SERVICE_OPTION_NONE, &init_cb, &connect_cb, &disconnect_cb, closure_for_cb, GNUNET_MQ_hd_var_size (get, GNUNET_MESSAGE_TYPE_RESOLVER_REQUEST, struct GNUNET_RESOLVER_GetMessage, NULL), GNUNET_MQ_handler_end ());

Definition at line 373 of file gnunet_service_lib.h.

Typedef Documentation

GNUNET_SERVICE_InitCallback

typedef void(* GNUNET_SERVICE_InitCallback) (void *cls, const struct GNUNET_CONFIGURATION_Handle *cfg, struct GNUNET_SERVICE_Handle *sh)

Callback to initialize a service, called exactly once when the service is run.

Parameters

cls	closure passed to GNUNET_SERVICE_MAIN
cfg	configuration to use for this service
sh	handle to the newly create service

Definition at line 120 of file gnunet_service_lib.h.

GNUNET_SERVICE_ConnectHandler

typedef void *(* GNUNET_SERVICE_ConnectHandler) (void *cls, struct GNUNET_SERVICE_Client *c, struct GNUNET_MQ_Handle *mq)

Callback to be called when a client connects to the service.

Parameters

cls	closure for the service
c	the new client that connected to the service
mq	the message queue used to send messages to the client

Returns

the client-specific (‘internal’) closure

Definition at line 134 of file gnunet_service_lib.h.

GNUNET_SERVICE_DisconnectHandler

typedef void(* GNUNET_SERVICE_DisconnectHandler) (void *cls, struct GNUNET_SERVICE_Client *c, void *internal_cls)

Callback to be called when a client disconnected from the service.

Parameters

cls	closure for the service
c	the client that disconnected
internal_cls	the client-specific (‘internal’) closure

Definition at line 147 of file gnunet_service_lib.h.

Enumeration Type Documentation

GNUNET_SERVICE_Options

enum GNUNET_SERVICE_Options

Options for the service (bitmask).

Enumerator
GNUNET_SERVICE_OPTION_NONE	Use defaults. Terminates all client connections and the listen sockets immediately upon receiving the shutdown signal.
GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN	Do not trigger server shutdown on signal at all; instead, allow for the user to terminate the server explicitly when needed by calling GNUNET_SERVICE_shutdown().
GNUNET_SERVICE_OPTION_SOFT_SHUTDOWN	Trigger a SOFT server shutdown on signals, allowing active non-monitor clients to complete their transactions.
GNUNET_SERVICE_OPTION_SHUTDOWN_BITMASK	Bitmask over the shutdown options.
GNUNET_SERVICE_OPTION_CLOSE_LSOCKS	Instead of listening on lsocks passed by the parent, close them after opening our own listen socket(s).

Definition at line 65 of file gnunet_service_lib.h.

{
  GNUNET_SERVICE_OPTION_NONE = 0,
 
  GNUNET_SERVICE_OPTION_MANUAL_SHUTDOWN = 1,
 
  GNUNET_SERVICE_OPTION_SOFT_SHUTDOWN = 2,
 
  GNUNET_SERVICE_OPTION_SHUTDOWN_BITMASK = 3,
 
  GNUNET_SERVICE_OPTION_CLOSE_LSOCKS = 4
};

Function Documentation

GNUNET_SERVICE_start()

struct GNUNET_SERVICE_Handle * GNUNET_SERVICE_start	(	const struct GNUNET_OS_ProjectData *	pd,
		const char *	service_name,
		const struct GNUNET_CONFIGURATION_Handle *	cfg,
		GNUNET_SERVICE_ConnectHandler	connect_cb,
		GNUNET_SERVICE_DisconnectHandler	disconnect_cb,
		void *	cls,
		const struct GNUNET_MQ_MessageHandler *	handlers
	)

Low-level function to start a service if the scheduler is already running.

Should only be used directly in special cases.

The function will launch the service with the name service_name using the service_options to configure its shutdown behavior. When clients connect or disconnect, the respective connect_cb or disconnect_cb functions will be called. For messages received from the clients, the respective handlers will be invoked; for the closure of the handlers we use the return value from the connect_cb invocation of the respective client.

Each handler MUST call GNUNET_SERVICE_client_continue() after each message to receive further messages from this client. If GNUNET_SERVICE_client_continue() is not called within a short time, a warning will be logged. If delays are expected, services should call GNUNET_SERVICE_client_disable_continue_warning() to disable the warning.

Clients sending invalid messages (based on handlers) will be dropped. Additionally, clients can be dropped at any time using GNUNET_SERVICE_client_drop().

The service must be stopped using GNUNET_SERVICE_stop().

Parameters

pd	project data for the service
service_name	name of the service to run
cfg	configuration to use
connect_cb	function to call whenever a client connects
disconnect_cb	function to call whenever a client disconnects
cls	closure argument for connect_cb and disconnect_cb
handlers	NULL-terminated array of message handlers for the service, the closure will be set to the value returned by the connect_cb for the respective connection

Returns

NULL on error

Definition at line 1883 of file service.c.

{
  struct GNUNET_SERVICE_Handle *sh;
 
  sh = GNUNET_new (struct GNUNET_SERVICE_Handle);
  sh->pd = pd;
  sh->service_name = service_name;
  sh->cfg = cfg;
  sh->connect_cb = connect_cb;
  sh->disconnect_cb = disconnect_cb;
  sh->cb_cls = cls;
  sh->handlers = GNUNET_MQ_copy_handlers2 (handlers,
                                           &return_agpl,
                                           NULL);
  if (GNUNET_OK !=
      setup_service (pd,
                     sh))
  {
    GNUNET_free (sh->handlers);
    GNUNET_free (sh);
    return NULL;
  }
  do_resume (sh,
             SUSPEND_STATE_NONE);
  return sh;
}

References GNUNET_IDENTITY_Handle::cb_cls, cfg, GNUNET_IDENTITY_Handle::cfg, connect_cb(), disconnect_cb(), do_resume(), GNUNET_free, GNUNET_MQ_copy_handlers2(), GNUNET_new, GNUNET_OK, handlers, GNUNET_SERVICE_Handle::pd, return_agpl(), service_name, setup_service(), sh, and SUSPEND_STATE_NONE.

Referenced by transport_communicator_start().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_SERVICE_stop()

void GNUNET_SERVICE_stop

(

struct GNUNET_SERVICE_Handle *

srv

)

Stops a service that was started with GNUNET_SERVICE_start().

Parameters

srv	service to stop

Definition at line 1958 of file service.c.

{
  struct GNUNET_SERVICE_Client *client;
 
  GNUNET_SERVICE_suspend (srv);
  while (NULL != (client = srv->clients_head))
  {
    if (NULL == client->drop_task)
      GNUNET_SERVICE_client_drop (client);
    GNUNET_SCHEDULER_cancel (client->drop_task);
    finish_client_drop (client);
  }
  teardown_service (srv);
  GNUNET_free (srv->handlers);
  GNUNET_free (srv);
}

References GNUNET_SERVICE_Handle::clients_head, GNUNET_SERVICE_Client::drop_task, finish_client_drop(), GNUNET_free, GNUNET_SCHEDULER_cancel(), GNUNET_SERVICE_client_drop(), GNUNET_SERVICE_suspend(), GNUNET_SERVICE_Handle::handlers, and teardown_service().

Referenced by shutdown_service().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_SERVICE_run_()

int GNUNET_SERVICE_run_	(	const struct GNUNET_OS_ProjectData *	pd,
		int	argc,
		char *const *	argv,
		const char *	service_name,
		enum GNUNET_SERVICE_Options	options,
		GNUNET_SERVICE_InitCallback	service_init_cb,
		GNUNET_SERVICE_ConnectHandler	connect_cb,
		GNUNET_SERVICE_DisconnectHandler	disconnect_cb,
		void *	cls,
		const struct GNUNET_MQ_MessageHandler *	handlers
	)

Creates the "main" function for a GNUnet service.

You should almost always use the GNUNET_SERVICE_MAIN macro instead of calling this function directly (except for ARM, which should call this function directly).

The function will launch the service with the name service_name using the service_options to configure its shutdown behavior. Once the service is ready, the init_cb will be called for service-specific initialization. init_cb will be given the service handler which can be used to control the service's availability. When clients connect or disconnect, the respective connect_cb or disconnect_cb functions will be called. For messages received from the clients, the respective handlers will be invoked; for the closure of the handlers we use the return value from the connect_cb invocation of the respective client.

Each handler MUST call GNUNET_SERVICE_client_continue() after each message to receive further messages from this client. If GNUNET_SERVICE_client_continue() is not called within a short time, a warning will be logged. If delays are expected, services should call GNUNET_SERVICE_client_disable_continue_warning() to disable the warning.

Clients sending invalid messages (based on handlers) will be dropped. Additionally, clients can be dropped at any time using GNUNET_SERVICE_client_drop().

Parameters

pd	project data for the service
argc	number of command-line arguments in argv
argv	array of command-line arguments
service_name	name of the service to run
options	options controlling shutdown of the service
service_init_cb	function to call once the service is ready
connect_cb	function to call whenever a client connects
disconnect_cb	function to call whenever a client disconnects
cls	closure argument for service_init_cb, connect_cb and disconnect_cb
handlers	NULL-terminated array of message handlers for the service, the closure will be set to the value returned by the connect_cb for the respective connection

Returns

0 on success, non-zero on error

Definition at line 1977 of file service.c.

{
  struct GNUNET_SERVICE_Handle sh;
 
#if ENABLE_NLS
  char *path;
#endif
  char *cfg_filename;
  char *opt_cfg_filename;
  char *loglev;
  const char *xdg;
  char *logfile;
  int do_daemonize;
  unsigned long long skew_offset;
  unsigned long long skew_variance;
  long long clock_offset;
  struct GNUNET_CONFIGURATION_Handle *cfg;
  int ret;
  int err;
  struct GNUNET_GETOPT_CommandLineOption service_options[] = {
    GNUNET_GETOPT_option_cfgfile (&opt_cfg_filename),
    GNUNET_GETOPT_option_flag ('d',
                               "daemonize",
                               gettext_noop (
                                 "do daemonize (detach from terminal)"),
                               &do_daemonize),
    GNUNET_GETOPT_option_help (pd,
                               NULL),
    GNUNET_GETOPT_option_loglevel (&loglev),
    GNUNET_GETOPT_option_logfile (&logfile),
    GNUNET_GETOPT_option_version (pd->version),
    GNUNET_GETOPT_OPTION_END
  };
 
  err = 1;
  memset (&sh, 0, sizeof(sh));
  xdg = getenv ("XDG_CONFIG_HOME");
  if (NULL != xdg)
    GNUNET_asprintf (&cfg_filename,
                     "%s%s%s",
                     xdg,
                     DIR_SEPARATOR_STR,
                     pd->config_file);
  else
    cfg_filename = GNUNET_strdup (pd->user_config_file);
  sh.pd = pd;
  sh.ready_confirm_fd = -1;
  sh.options = options;
  sh.cfg = cfg = GNUNET_CONFIGURATION_create (pd);
  sh.service_init_cb = service_init_cb;
  sh.connect_cb = connect_cb;
  sh.disconnect_cb = disconnect_cb;
  sh.cb_cls = cls;
  sh.handlers = (NULL == pd->agpl_url)
                ? GNUNET_MQ_copy_handlers (handlers)
                : GNUNET_MQ_copy_handlers2 (handlers,
                                            &return_agpl,
                                            NULL);
  sh.service_name = service_name;
  /* setup subsystems */
  loglev = NULL;
  logfile = NULL;
  opt_cfg_filename = NULL;
  do_daemonize = 0;
#if ENABLE_NLS
  if (NULL != pd->gettext_domain)
  {
    setlocale (LC_ALL, "");
    path = (NULL == pd->gettext_path)
      ? GNUNET_OS_installation_get_path (pd,
                                         GNUNET_OS_IPK_LOCALEDIR)
      : GNUNET_strdup (pd->gettext_path);
    if (NULL != path)
    {
      bindtextdomain (pd->gettext_domain, path);
      GNUNET_free (path);
    }
    textdomain (pd->gettext_domain);
  }
#endif
  ret = GNUNET_GETOPT_run (service_name,
                           service_options,
                           argc,
                           argv);
  if (GNUNET_SYSERR == ret)
    goto shutdown;
  if (GNUNET_NO == ret)
  {
    err = 0;
    goto shutdown;
  }
  if (GNUNET_OK != GNUNET_log_setup (service_name,
                                     loglev,
                                     logfile))
  {
    GNUNET_break (0);
    goto shutdown;
  }
  if (NULL != opt_cfg_filename)
  {
    if ((GNUNET_YES != GNUNET_DISK_file_test (opt_cfg_filename)) ||
        (GNUNET_SYSERR == GNUNET_CONFIGURATION_load (cfg, opt_cfg_filename)))
    {
      GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
                  _ ("Malformed configuration file `%s', exit ...\n"),
                  opt_cfg_filename);
      goto shutdown;
    }
  }
  else
  {
    if (GNUNET_YES ==
        GNUNET_DISK_file_test (cfg_filename))
    {
      if (GNUNET_SYSERR ==
          GNUNET_CONFIGURATION_load (cfg,
                                     cfg_filename))
      {
        GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
                    _ ("Malformed configuration file `%s', exit ...\n"),
                    cfg_filename);
        goto shutdown;
      }
    }
    else
    {
      if (GNUNET_SYSERR ==
          GNUNET_CONFIGURATION_load (cfg,
                                     NULL))
      {
        GNUNET_log (GNUNET_ERROR_TYPE_ERROR,
                    _ ("Malformed configuration, exit ...\n"));
        goto shutdown;
      }
    }
  }
  if (GNUNET_OK !=
      setup_service (pd,
                     &sh))
    goto shutdown;
  if ( (1 == do_daemonize) &&
       (GNUNET_OK !=
        detach_terminal (&sh)) )
  {
    GNUNET_break (0);
    goto shutdown;
  }
  if (GNUNET_OK != set_user_id (&sh))
    goto shutdown;
  LOG (GNUNET_ERROR_TYPE_DEBUG,
       "Service `%s' runs with configuration from `%s'\n",
       service_name,
       (NULL != opt_cfg_filename) ? opt_cfg_filename : cfg_filename);
  if ( (GNUNET_OK ==
        GNUNET_CONFIGURATION_get_value_number (sh.cfg,
                                               "TESTING",
                                               "SKEW_OFFSET",
                                               &skew_offset)) &&
       (GNUNET_OK ==
        GNUNET_CONFIGURATION_get_value_number (sh.cfg,
                                               "TESTING",
                                               "SKEW_VARIANCE",
                                               &skew_variance)) )
  {
    clock_offset = skew_offset - skew_variance;
    GNUNET_TIME_set_offset (clock_offset);
    LOG (GNUNET_ERROR_TYPE_DEBUG,
         "Skewing clock by %lld ms\n",
         (long long) clock_offset);
  }
  GNUNET_RESOLVER_connect (sh.cfg);
 
  /* actually run service */
  err = 0;
  GNUNET_SCHEDULER_run (&service_main, &sh);
  /* shutdown */
  if (1 == do_daemonize)
    pid_file_delete (&sh);
 
shutdown:
  if (-1 != sh.ready_confirm_fd)
  {
    if (1 != write (sh.ready_confirm_fd, err ? "I" : "S", 1))
      LOG_STRERROR (GNUNET_ERROR_TYPE_WARNING, "write");
    GNUNET_break (0 == close (sh.ready_confirm_fd));
  }
  teardown_service (&sh);
  GNUNET_free (sh.handlers);
  GNUNET_SPEEDUP_stop_ ();
  GNUNET_CONFIGURATION_destroy (cfg);
  GNUNET_free (logfile);
  GNUNET_free (loglev);
  GNUNET_free (cfg_filename);
  GNUNET_free (opt_cfg_filename);
 
  return err ? GNUNET_SYSERR : 0;
}

References _, GNUNET_OS_ProjectData::agpl_url, bindtextdomain, GNUNET_IDENTITY_Handle::cb_cls, cfg, GNUNET_IDENTITY_Handle::cfg, cfg_filename, GNUNET_OS_ProjectData::config_file, connect_cb(), detach_terminal(), DIR_SEPARATOR_STR, disconnect_cb(), getenv(), GNUNET_OS_ProjectData::gettext_domain, gettext_noop, GNUNET_OS_ProjectData::gettext_path, GNUNET_asprintf(), GNUNET_break, GNUNET_CONFIGURATION_create(), GNUNET_CONFIGURATION_destroy(), GNUNET_CONFIGURATION_get_value_number(), GNUNET_CONFIGURATION_load(), GNUNET_DISK_file_test(), GNUNET_ERROR_TYPE_DEBUG, GNUNET_ERROR_TYPE_ERROR, GNUNET_ERROR_TYPE_WARNING, GNUNET_free, GNUNET_GETOPT_option_cfgfile(), GNUNET_GETOPT_OPTION_END, GNUNET_GETOPT_option_flag(), GNUNET_GETOPT_option_help(), GNUNET_GETOPT_option_logfile(), GNUNET_GETOPT_option_loglevel(), GNUNET_GETOPT_option_version(), GNUNET_GETOPT_run(), GNUNET_log, GNUNET_log_setup(), GNUNET_MQ_copy_handlers(), GNUNET_MQ_copy_handlers2(), GNUNET_NO, GNUNET_OK, GNUNET_OS_installation_get_path(), GNUNET_OS_IPK_LOCALEDIR, GNUNET_RESOLVER_connect(), GNUNET_SCHEDULER_run(), GNUNET_SPEEDUP_stop_(), GNUNET_strdup, GNUNET_SYSERR, GNUNET_TIME_set_offset(), GNUNET_YES, handlers, LOG, LOG_STRERROR, options, pid_file_delete(), ret, return_agpl(), service_main(), service_name, set_user_id(), setup_service(), sh, teardown_service(), textdomain, GNUNET_OS_ProjectData::user_config_file, and GNUNET_OS_ProjectData::version.

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_SERVICE_register_()

int GNUNET_SERVICE_register_	(	const struct GNUNET_OS_ProjectData *	pd,
		const char *	service_name,
		enum GNUNET_SERVICE_Options	options,
		GNUNET_SERVICE_InitCallback	service_init_cb,
		GNUNET_SERVICE_ConnectHandler	connect_cb,
		GNUNET_SERVICE_DisconnectHandler	disconnect_cb,
		void *	cls,
		const struct GNUNET_MQ_MessageHandler *	handlers
	)

Registers the GNUnet service to be scheduled as part of a monilithic libgnunet.

You should almost always use the GNUNET_SERVICE_MAIN macro instead of calling this function directly.

The function will launch the service with the name service_name using the service_options to configure its shutdown behavior. Once the service is ready, the init_cb will be called for service-specific initialization. init_cb will be given the service handler which can be used to control the service's availability. When clients connect or disconnect, the respective connect_cb or disconnect_cb functions will be called. For messages received from the clients, the respective handlers will be invoked; for the closure of the handlers we use the return value from the connect_cb invocation of the respective client.

Each handler MUST call GNUNET_SERVICE_client_continue() after each message to receive further messages from this client. If GNUNET_SERVICE_client_continue() is not called within a short time, a warning will be logged. If delays are expected, services should call GNUNET_SERVICE_client_disable_continue_warning() to disable the warning.

Clients sending invalid messages (based on handlers) will be dropped. Additionally, clients can be dropped at any time using GNUNET_SERVICE_client_drop().

Parameters

pd	project data for the service
service_name	name of the service to run
options	options controlling shutdown of the service
service_init_cb	function to call once the service is ready
connect_cb	function to call whenever a client connects
disconnect_cb	function to call whenever a client disconnects
cls	closure argument for service_init_cb, connect_cb and disconnect_cb
handlers	NULL-terminated array of message handlers for the service, the closure will be set to the value returned by the connect_cb for the respective connection

Returns

0 on success, non-zero on error

Definition at line 2209 of file service.c.

{
  struct ServiceHandleList *hle;
  struct GNUNET_SERVICE_Handle *sh = GNUNET_new (struct GNUNET_SERVICE_Handle);
 
  sh->pd = pd;
  sh->ready_confirm_fd = -1;
  sh->options = options;
  sh->service_init_cb = service_init_cb;
  sh->connect_cb = connect_cb;
  sh->disconnect_cb = disconnect_cb;
  sh->cb_cls = cls;
  sh->handlers = (NULL == pd->agpl_url)
                ? GNUNET_MQ_copy_handlers (handlers)
                : GNUNET_MQ_copy_handlers2 (handlers, &return_agpl, NULL);
  sh->service_name = service_name;
  hle = GNUNET_new (struct ServiceHandleList);
  hle->sh = sh;
  GNUNET_CONTAINER_DLL_insert (hll_head,
                               hll_tail,
                               hle);
  return 0;
}

References GNUNET_OS_ProjectData::agpl_url, GNUNET_IDENTITY_Handle::cb_cls, connect_cb(), disconnect_cb(), GNUNET_CONTAINER_DLL_insert, GNUNET_MQ_copy_handlers(), GNUNET_MQ_copy_handlers2(), GNUNET_new, handlers, hll_head, hll_tail, options, GNUNET_SERVICE_Handle::pd, return_agpl(), GNUNET_SERVICE_Handle::service_init_cb, service_name, sh, and ServiceHandleList::sh.

Here is the call graph for this function:

GNUNET_SERVICE_main()

void GNUNET_SERVICE_main	(	const struct GNUNET_OS_ProjectData *	pd,
		int	argc,
		char *const *	argv,
		struct GNUNET_CONFIGURATION_Handle *	cfg,
		enum GNUNET_GenericReturnValue	with_scheduler
	)

Run the mainloop in a monolithic libgnunet.

Must be called such that services are actually launched.

Definition at line 2303 of file service.c.

{
  struct LaunchContext lc = {
    .pd = pd,
    .cfg = cfg
  };
 
  LOG (GNUNET_ERROR_TYPE_DEBUG,
       "Entering GNUNET_SERVICE_main\n");
  if (GNUNET_YES == with_scheduler)
  {
    if (GNUNET_YES !=
        GNUNET_PROGRAM_conf_and_options (pd,
                                         argc,
                                         argv,
                                         cfg))
      return;
    GNUNET_SCHEDULER_run (&launch_registered_services,
                          &lc);
  }
  else
  {
    launch_registered_services (&lc);
    GNUNET_RESOLVER_connect (cfg);
  }
}

References cfg, GNUNET_ERROR_TYPE_DEBUG, GNUNET_PROGRAM_conf_and_options(), GNUNET_RESOLVER_connect(), GNUNET_SCHEDULER_run(), GNUNET_YES, launch_registered_services(), LOG, and LaunchContext::pd.

Referenced by monolith_main().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_SERVICE_suspend()

void GNUNET_SERVICE_suspend

(

struct GNUNET_SERVICE_Handle *

sh

)

Suspend accepting connections from the listen socket temporarily.

Resume activity using GNUNET_SERVICE_resume.

Parameters

sh	service to stop accepting connections.

Definition at line 2336 of file service.c.

{
  do_suspend (sh,
              SUSPEND_STATE_APP);
}

References do_suspend(), sh, and SUSPEND_STATE_APP.

Referenced by GNUNET_SERVICE_stop(), and run().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_SERVICE_resume()

void GNUNET_SERVICE_resume

(

struct GNUNET_SERVICE_Handle *

sh

)

Resume accepting connections from the listen socket.

Parameters

sh	service to resume accepting connections.

Definition at line 2344 of file service.c.

{
  do_resume (sh,
             SUSPEND_STATE_APP);
}

References do_resume(), sh, and SUSPEND_STATE_APP.

Referenced by begin_service(), and run().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_SERVICE_client_continue()

void GNUNET_SERVICE_client_continue

(

struct GNUNET_SERVICE_Client *

c

)

Continue receiving further messages from the given client.

Must be called after each message received.

Parameters

c	the client to continue receiving from

Definition at line 2389 of file service.c.

{
  GNUNET_assert (NULL == c->drop_task);
  GNUNET_assert (c->needs_continue);
  GNUNET_assert (NULL == c->recv_task);
  c->needs_continue = false;
  if (NULL != c->warn_task)
  {
    GNUNET_SCHEDULER_cancel (c->warn_task);
    c->warn_task = NULL;
  }
  c->recv_task = GNUNET_SCHEDULER_add_now (&resume_client_receive,
                                           c);
}

References GNUNET_SERVICE_Client::drop_task, GNUNET_assert, GNUNET_SCHEDULER_add_now(), GNUNET_SCHEDULER_cancel(), GNUNET_SERVICE_Client::needs_continue, GNUNET_SERVICE_Client::recv_task, resume_client_receive(), and GNUNET_SERVICE_Client::warn_task.

Referenced by conclude_autoconfig_request(), continue_store_activity(), finish_cmc_handling_with_continue(), handle_add_address(), handle_add_global_address(), handle_add_queue_message(), handle_alice_client_message(), handle_alice_client_message_multipart(), handle_announce(), handle_attribute_delete_message(), handle_attribute_store_message(), handle_block_cache(), handle_bob_client_message(), handle_bob_client_message_multipart(), handle_channel_create(), handle_channel_destroy(), handle_client_accept(), handle_client_audio_message(), handle_client_call_message(), handle_client_cancel(), handle_client_conclude(), handle_client_copy_lazy_connect(), handle_client_copy_lazy_prepare(), handle_client_create_set(), handle_client_decrypt(), handle_client_evaluate(), handle_client_hangup_message(), handle_client_index_list_get(), handle_client_init(), handle_client_insert(), handle_client_iter_ack(), handle_client_iterate(), handle_client_join(), handle_client_keygen(), handle_client_listen(), handle_client_loc_sign(), handle_client_monitor_peers(), handle_client_mutation(), handle_client_pickup_message(), handle_client_recv_ok(), handle_client_redirect_to_ip(), handle_client_redirect_to_service(), handle_client_register_message(), handle_client_reject(), handle_client_response(), handle_client_resume_message(), handle_client_seed(), handle_client_send(), handle_client_send_request(), handle_client_set_add(), handle_client_start(), handle_client_start_search(), handle_client_start_sub(), handle_client_stop_sub(), handle_client_stream_cancel(), handle_client_stream_request(), handle_client_suspend_message(), handle_client_unindex(), handle_client_view_cancel(), handle_client_view_request(), handle_collect(), handle_communicator_available(), handle_communicator_backchannel(), handle_consume_ticket_message(), handle_create(), handle_create_message(), handle_credential_delete_message(), handle_credential_iteration_next(), handle_credential_iteration_start(), handle_credential_iteration_stop(), handle_credential_store_message(), handle_del_address(), handle_del_queue_message(), handle_delete_message(), handle_dht_local_get(), handle_dht_local_get_stop(), handle_dht_local_hello_get(), handle_dht_local_hello_offer(), handle_dht_local_monitor(), handle_dht_local_monitor_stop(), handle_dht_local_put(), handle_disconnect(), handle_drop(), handle_drop_message(), handle_edit_record_set(), handle_edit_record_set_cancel(), handle_get(), handle_get_key(), handle_get_message(), handle_get_peers(), handle_get_replication(), handle_get_zero_anonymity(), handle_incoming_msg(), handle_info_tunnels(), handle_issue_ticket_message(), handle_iterate_stop(), handle_iteration_next(), handle_iteration_start(), handle_iteration_stop(), handle_list(), handle_local_ack(), handle_local_data(), handle_lookup(), handle_lookup_block(), handle_lookup_by_suffix_message(), handle_lookup_message(), handle_monitor(), handle_monitor_next(), handle_monitor_start(), handle_port_close(), handle_port_open(), handle_put(), handle_query_message(), handle_queue_create_fail(), handle_queue_create_ok(), handle_record_lookup(), handle_record_store(), handle_register(), handle_release_reserve(), handle_remove(), handle_rename_message(), handle_request_connection_reversal(), handle_request_hello_validation(), handle_reserve(), handle_revoke_message(), handle_revoke_ticket_message(), handle_room_close(), handle_room_entry(), handle_room_open(), handle_room_sync(), handle_search(), handle_send_message(), handle_send_message_ack(), handle_set(), handle_show_path(), handle_start(), handle_start_message(), handle_stop(), handle_stun(), handle_suggest(), handle_suggest_cancel(), handle_test(), handle_ticket_iteration_next(), handle_ticket_iteration_start(), handle_ticket_iteration_stop(), handle_update_queue_message(), handle_verify(), handle_watch(), handle_zone_to_name(), hash_for_index_val(), iteration_done_client_continue(), return_agpl(), service_mq_error_handler(), signal_index_ok(), start_p2p_processing(), store_record_continuation(), and zone_iteration_done_client_continue().

Here is the call graph for this function:

GNUNET_SERVICE_client_get_mq()

struct GNUNET_MQ_Handle * GNUNET_SERVICE_client_get_mq

(

struct GNUNET_SERVICE_Client *

c

)

Obtain the message queue of c.

Convenience function.

Parameters

c	the client to continue receiving from

Returns

the message queue of c

Definition at line 2500 of file service.c.

{
  return c->mq;
}

References GNUNET_SERVICE_Client::mq.

Referenced by broadcast_status(), handle_list(), handle_lookup_by_suffix_message(), handle_lookup_message(), handle_monitor(), handle_query_message(), handle_revoke_message(), handle_start(), handle_start_message(), handle_test(), return_agpl(), send_client_reply(), send_end_msg(), send_intermediate_response(), send_lookup_response(), send_reply(), send_result_code(), signal_result(), transmit_item(), and transmit_status().

Here is the caller graph for this function:

GNUNET_SERVICE_client_disable_continue_warning()

void GNUNET_SERVICE_client_disable_continue_warning

(

struct GNUNET_SERVICE_Client *

c

)

Disable the warning the server issues if a message is not acknowledged in a timely fashion.

Use this call if a client is intentionally delayed for a while. Only applies to the current message.

Parameters

c	client for which to disable the warning

Definition at line 2406 of file service.c.

{
  GNUNET_break (NULL != c->warn_task);
  if (NULL != c->warn_task)
  {
    GNUNET_SCHEDULER_cancel (c->warn_task);
    c->warn_task = NULL;
  }
}

References GNUNET_break, GNUNET_SCHEDULER_cancel(), and GNUNET_SERVICE_Client::warn_task.

Referenced by handle_start_message().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_SERVICE_client_drop()

void GNUNET_SERVICE_client_drop

(

struct GNUNET_SERVICE_Client *

c

)

Ask the server to disconnect from the given client.

This is the same as returning GNUNET_SYSERR within the check procedure when handling a message, except that it allows dropping of a client even when not handling a message from that client. The disconnect_cb will be called on c even if the application closes the connection using this function.

This function should be called (outside of util's internal logic) if (and usually only if) the client has violated the protocol. Otherwise, we should leave it to the client to disconnect from the service.

Parameters

c	client to disconnect now

Definition at line 2418 of file service.c.

{
  struct GNUNET_SERVICE_Handle *sh = c->sh;
 
  GNUNET_log (GNUNET_ERROR_TYPE_DEBUG,
              "Client dropped: %p (MQ: %p)\n",
              c,
              c->mq);
#if EXECINFO
  {
    void *backtrace_array[MAX_TRACE_DEPTH];
    int num_backtrace_strings = backtrace (backtrace_array,
                                           MAX_TRACE_DEPTH);
    char **backtrace_strings =
      backtrace_symbols (backtrace_array,
                         t->num_backtrace_strings);
    for (unsigned int i = 0; i < num_backtrace_strings; i++)
      LOG (GNUNET_ERROR_TYPE_DEBUG,
           "client drop trace %u: %s\n",
           i,
           backtrace_strings[i]);
  }
#endif
  GNUNET_assert (NULL == c->drop_task);
  if (NULL != sh->disconnect_cb)
    sh->disconnect_cb (sh->cb_cls,
                       c,
                       c->user_context);
  if (NULL != c->warn_task)
  {
    GNUNET_SCHEDULER_cancel (c->warn_task);
    c->warn_task = NULL;
  }
  if (NULL != c->recv_task)
  {
    GNUNET_SCHEDULER_cancel (c->recv_task);
    c->recv_task = NULL;
  }
  if (NULL != c->send_task)
  {
    GNUNET_SCHEDULER_cancel (c->send_task);
    c->send_task = NULL;
  }
  c->drop_task = GNUNET_SCHEDULER_add_now (&finish_client_drop,
                                           c);
}

References GNUNET_IDENTITY_Handle::cb_cls, GNUNET_SERVICE_Client::drop_task, finish_client_drop(), GNUNET_assert, GNUNET_ERROR_TYPE_DEBUG, GNUNET_log, GNUNET_SCHEDULER_add_now(), GNUNET_SCHEDULER_cancel(), LOG, GNUNET_SERVICE_Client::mq, GNUNET_SERVICE_Client::recv_task, GNUNET_SERVICE_Client::send_task, sh, GNUNET_SERVICE_Client::sh, t, GNUNET_SERVICE_Client::user_context, and GNUNET_SERVICE_Client::warn_task.

Referenced by check_client_seed(), demultiplex_with_cmc(), destroy_service_session(), force_timeout(), GNUNET_SERVICE_shutdown(), GNUNET_SERVICE_stop(), GSC_CLIENTS_reject_request(), handle_add_queue_message(), handle_announce(), handle_attribute_delete_message(), handle_attribute_store_message(), handle_autoconfig_request(), handle_bob_client_message(), handle_channel_create(), handle_client_accept(), handle_client_audio_message(), handle_client_call_message(), handle_client_cancel(), handle_client_conclude(), handle_client_copy_lazy_connect(), handle_client_copy_lazy_prepare(), handle_client_create_set(), handle_client_decrypt(), handle_client_evaluate(), handle_client_hangup_message(), handle_client_insert(), handle_client_iter_ack(), handle_client_iterate(), handle_client_keygen(), handle_client_listen(), handle_client_mutation(), handle_client_pickup_message(), handle_client_recv_ok(), handle_client_redirect_to_ip(), handle_client_redirect_to_service(), handle_client_register_message(), handle_client_response(), handle_client_resume_message(), handle_client_set_add(), handle_client_start(), handle_client_suspend_message(), handle_create_message(), handle_credential_delete_message(), handle_credential_iteration_next(), handle_credential_iteration_start(), handle_credential_iteration_stop(), handle_credential_store_message(), handle_del_address(), handle_del_queue_message(), handle_destroy(), handle_dht_local_get_result_seen(), handle_dht_local_hello_offer(), handle_edit_record_set(), handle_edit_record_set_cancel(), handle_fragment_box(), handle_get_zero_anonymity(), handle_issue_ticket_message(), handle_iterate_next(), handle_iteration_next(), handle_iteration_start(), handle_iteration_stop(), handle_local_data(), handle_lookup_block(), handle_monitor_next(), handle_monitor_start(), handle_port_close(), handle_port_open(), handle_query_message(), handle_queue_create_fail(), handle_queue_create_ok(), handle_raw_message(), handle_record_lookup(), handle_record_store(), handle_register(), handle_request_connection_reversal(), handle_revoke_message(), handle_revoke_ticket_message(), handle_search(), handle_send_message_ack(), handle_store(), handle_stun(), handle_suggest(), handle_suggest_cancel(), handle_test(), handle_ticket_iteration_next(), handle_ticket_iteration_start(), handle_ticket_iteration_stop(), handle_watch(), handle_zone_to_name(), monitor_iteration_next(), process_get(), resume_client_receive(), send_lookup_response(), send_lookup_response_with_filter(), service_client_recv(), service_mq_error_handler(), and shutdown_task().

Here is the call graph for this function:

GNUNET_SERVICE_shutdown()

void GNUNET_SERVICE_shutdown

(

struct GNUNET_SERVICE_Handle *

sh

)

Explicitly stops the service.

Parameters

sh	server to shutdown

Definition at line 2467 of file service.c.

{
  if (0 == (sh->suspend_state & SUSPEND_STATE_SHUTDOWN))
    do_suspend (sh,
                SUSPEND_STATE_SHUTDOWN);
  for (struct GNUNET_SERVICE_Client *client = sh->clients_head;
       NULL != client;
       client = client->next)
  {
    if (NULL == client->drop_task)
      GNUNET_SERVICE_client_drop (client);
  }
}

References do_suspend(), GNUNET_SERVICE_client_drop(), sh, and SUSPEND_STATE_SHUTDOWN.

Referenced by destroy_service(), do_shutdown(), finish_client_drop(), GNUNET_SERVICE_client_mark_monitor(), and service_shutdown().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_SERVICE_client_mark_monitor()

void GNUNET_SERVICE_client_mark_monitor

(

struct GNUNET_SERVICE_Client *

c

)

Set the 'monitor' flag on this client.

Clients which have been marked as 'monitors' won't prevent the server from shutting down once #GNUNET_SERVICE_stop_listening() has been invoked. The idea is that for "normal" clients we likely want to allow them to process their requests; however, monitor-clients are likely to 'never' disconnect during shutdown and thus will not be considered when determining if the server should continue to exist after shutdown has been triggered.

Parameters

c	client to mark as a monitor

Definition at line 2483 of file service.c.

{
  c->is_monitor = true;
  if (((0 != (SUSPEND_STATE_SHUTDOWN & c->sh->suspend_state)) &&
       (! have_non_monitor_clients (c->sh))))
    GNUNET_SERVICE_shutdown (c->sh);
}

References GNUNET_SERVICE_shutdown(), have_non_monitor_clients(), GNUNET_SERVICE_Client::is_monitor, GNUNET_SERVICE_Client::sh, GNUNET_SERVICE_Handle::suspend_state, and SUSPEND_STATE_SHUTDOWN.

Referenced by client_connect_cb(), handle_monitor_start(), handle_start_message(), and handle_watch().

Here is the call graph for this function:

Here is the caller graph for this function:

GNUNET_SERVICE_client_persist()

void GNUNET_SERVICE_client_persist

(

struct GNUNET_SERVICE_Client *

c

)

Set the persist option on this client.

Indicates that the underlying socket or fd should never really be closed. Used for indicating process death.

Parameters

c	client to persist the socket (never to be closed)

Definition at line 2493 of file service.c.

{
  c->persist = true;
}

References GNUNET_SERVICE_Client::persist.

Referenced by handle_stop().

Here is the caller graph for this function: