GssService

GssService — System service base class

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

Includes

#include <libgsystemservice/service.h>

Description

A skeleton implementation of a system service, which exposes itself on the bus with a well-known name.

It follows the implementation recommendations in man 7 daemon.

Functions

gss_service_add_option_group ()

void
gss_service_add_option_group (GssService *self,
                              GOptionGroup *group);

Add an option group to the command line options. The options in this group will be listed in the help output, and their values will be set when gss_service_run() is called.

This is effectively a wrapper around g_option_context_add_group(), so see the documentation for that for more information.

Parameters

self

a GssService

 

group

an option group to add.

[transfer none]

Since: 0.1.0


gss_service_run ()

void
gss_service_run (GssService *self,
                 int argc,
                 char **argv,
                 GError **error);

Run the service, and return when the process should exit. If it should exit with an error status, error is set; otherwise it should exit with exit code zero (success).

This handles UNIX signals and command line parsing. If you wish to schedule some work to happen asynchronously while gss_service_run() is running in your main() function, use g_idle_add(). This function, like the rest of the library, is not thread-safe.

Parameters

self

a GssService

 

argc

number of arguments in argv

 

argv

argument array.

[array length=argc]

error

return location for a GError

 

Since: 0.1.0


gss_service_exit ()

void
gss_service_exit (GssService *self,
                  const GError *error,
                  int signum);

Cause the service to exit from gss_service_run(). If error is non-NULL, the service will exit with the given error; otherwise it will exit successfully. If this is called multiple times, all errors except the first will be ignored, so it may be safely used for error handling in shutdown code.

Parameters

self

a GssService

 

error

error which caused the process to exit, or NULL for a successful exit.

[nullable]

signum

signal which caused the process to exit, or 0 for a successful exit

 

Since: 0.1.0


gss_service_get_dbus_connection ()

GDBusConnection *
gss_service_get_dbus_connection (GssService *self);

Get the GDBusConnection used to export the service’s well-known name, as specified in “bus-type”.

Parameters

self

a GssService

 

Returns

D-Bus connection.

[transfer none]

Since: 0.1.0


gss_service_get_exit_signal ()

int
gss_service_get_exit_signal (GssService *self);

Get the number of the signal which caused the GssService to exit.

Parameters

self

a GssService

 

Returns

exit signal number, or 0 if unset

Since: 0.1.0


gss_service_get_inactivity_timeout ()

guint
gss_service_get_inactivity_timeout (GssService *self);

Get the value of “inactivity-timeout”.

Parameters

self

a GssService

 

Returns

inactivity timeout, in milliseconds, or zero if inactivity is ignored

Since: 0.1.0


gss_service_set_inactivity_timeout ()

void
gss_service_set_inactivity_timeout (GssService *self,
                                    guint timeout_ms);

Set the value of “inactivity-timeout”.

Parameters

self

a GssService

 

timeout_ms

inactivity timeout (in ms), or zero for no timeout

 

Since: 0.1.0


gss_service_hold ()

void
gss_service_hold (GssService *self);

Increase the hold count of the service, and hence prevent it from automatically exiting after the “inactivity-timeout” period expires with no activity.

Call gss_service_release() to decrement the hold count. Calls to these two methods must be paired; it is a programmer error not to.

Parameters

self

a GssService

 

Since: 0.1.0


gss_service_release ()

void
gss_service_release (GssService *self);

Decrease the hold count of the service, and hence potentially (if the hold count reaches zero) allow it to automatically exit after the “inactivity-timeout” period expires with no activity.

Call gss_service_hold() to increment the hold count. Calls to these two methods must be paired; it is a programmer error not to.

Parameters

self

a GssService

 

Since: 0.1.0

Types and Values

GssService

typedef struct _GssService GssService;

A skeleton implementation of a system service, which exposes itself on the bus with a well-known name.

It follows the implementation recommendations in man 7 daemon.

Since: 0.1.0


struct GssServiceClass

struct GssServiceClass {
  GObjectClass parent_class;

  GOptionEntry *(*get_main_option_entries) (GssService *service);

  void (*startup_async)  (GssService          *service,
                          GCancellable        *cancellable,
                          GAsyncReadyCallback  callback,
                          gpointer             user_data);
  void (*startup_finish) (GssService          *service,
                          GAsyncResult        *result,
                          GError             **error);
  void (*shutdown)       (GssService          *service);
};

Class structure for a GssService implementation.

All services must implement startup_async , startup_finish and shutdown , which are called by gss_service_run() to start up and shut down the service.

If your service needs to support additional command line options in the main group, implement get_main_option_entries ; otherwise leave it unimplemented.

Members

get_main_option_entries ()

Get a NULL-terminated array of GOptionEntrys to add to the main option group for the service. If implemented, this must return a non-NULL value.

[nullable]

startup_async ()

Asynchronous service startup implementation. This should start performing the startup for the service, when called by gss_service_run(). startup_finish will be called to complete the startup, and a GMainContext will be iterated between the two. This method must be implemented.

[not nullable]

startup_finish ()

Finish asynchronous startup started with startup_async . This method must be implemented.

[not nullable]

shutdown ()

Synchronous service shutdown implementation. This should perform all shutdown for the service, and is called from gss_service_run() once the service shutdown is triggered. This method must be implemented.

[not nullable]

Since: 0.1.0


enum GssServiceError

Errors from running a service.

Members

GSS_SERVICE_ERROR_SIGNALLED

Process was signalled with SIGINT or SIGTERM.

 

GSS_SERVICE_ERROR_INVALID_OPTIONS

Invalid command line options.

 

GSS_SERVICE_ERROR_NAME_UNAVAILABLE

Bus or well-known name unavailable.

 

GSS_SERVICE_ERROR_INVALID_ENVIRONMENT

Runtime environment is insecure or otherwise invalid for running the daemon.

 

GSS_SERVICE_ERROR_TIMEOUT

Inactivity timeout reached.

 

Since: 0.1.0