## EDBusServer

EDBusServer — An abstract base class for a D-Bus server

## Synopsis

    #include <libebackend/libebackend.h>

    struct              EDBusServer;
    enum                EDBusServerExitCode;
    EDBusServerExitCode e_dbus_server_run                   (EDBusServer *server,
                                                             gboolean wait_for_client);
    void                e_dbus_server_quit                  (EDBusServer *server,
                                                             EDBusServerExitCode code);
    void                e_dbus_server_hold                  (EDBusServer *server);
    void                e_dbus_server_release               (EDBusServer *server);
    void                e_dbus_server_load_modules          (EDBusServer *server);

## Object Hierarchy

      GObject
       +----EDBusServer
             +----EDataFactory
             +----EUserPrompterServer

## Implemented Interfaces

EDBusServer implements EExtensible.

## Signals

      "bus-acquired"                                   : Run Last
      "bus-name-acquired"                              : Run Last
      "bus-name-lost"                                  : Run Last
      "quit-server"                                    : Run Last
      "run-server"                                     : Run Last

## Description

## Details

### struct EDBusServer

    struct EDBusServer;

Contains only private data that should be read and manipulated using the functions below.

Since 3.4

### enum EDBusServerExitCode

    typedef enum {
    	E_DBUS_SERVER_EXIT_NONE,
    	E_DBUS_SERVER_EXIT_NORMAL,
    	E_DBUS_SERVER_EXIT_RELOAD
    } EDBusServerExitCode;

Exit codes submitted to `e_dbus_server_quit()` and returned by `e_dbus_server_run()`.

`E_DBUS_SERVER_EXIT_NONE` | The server's run state is unchanged.
`E_DBUS_SERVER_EXIT_NORMAL` | Normal termination. The process itself may now terminate.
`E_DBUS_SERVER_EXIT_RELOAD` | The server should reload its configuration and start again. Servers that do not support reloading may wish to intercept this exit code and stop the "quit-server" emission.

Since 3.6

### e_dbus_server_run ()

    EDBusServerExitCode e_dbus_server_run                   (EDBusServer *server,
                                                             gboolean wait_for_client);

Emits the "run" signal.

By default the `server` will start its main loop and attempt to acquire its well-known session bus name. If the `server`'s main loop is already running, the function will immediately return E_DBUS_SERVER_EXIT_NONE. Otherwise the function blocks until `e_dbus_server_quit()` is called.

If `wait_for_client` is `TRUE`, the `server` will continue running until the first client connection is made instead of quitting on its own if no client connection is made within the first few seconds.

`server` : | an EDBusServer
`wait_for_client` : | continue running until a client connects
Returns : | the exit code passed to `e_dbus_server_quit()`

Since 3.4

### e_dbus_server_quit ()

    void                e_dbus_server_quit                  (EDBusServer *server,
                                                             EDBusServerExitCode code);

Emits the "quit" signal with the given `code`.

By default the `server` will quit its main loop and cause `e_dbus_server_run()` to return `code`.

`server` : | an EDBusServer
`code` : | an EDBusServerExitCode

Since 3.4

### e_dbus_server_hold ()

    void                e_dbus_server_hold                  (EDBusServer *server);

Increases the use count of `server`.

Use this function to indicate that the server has a reason to continue to run. To cancel the hold, call `e_dbus_server_release()`.

`server` : | an EDBusServer

Since 3.4

### e_dbus_server_release ()

    void                e_dbus_server_release               (EDBusServer *server);

Decreates the use count of `server`.

When the use count reaches zero, the server will stop running.

Never call this function except to cancel the effect of a previous call to `e_dbus_server_hold()`.

`server` : | an EDBusServer

Since 3.4

### e_dbus_server_load_modules ()

    void                e_dbus_server_load_modules          (EDBusServer *server);

This function should be called once during `server` initialization to load all available library modules to extend the `server`'s functionality.

`server` : | an EDBusServer

Since 3.4

## Signal Details

### The `"bus-acquired"` signal

    void                user_function                      (EDBusServer     *server,
                                                            GDBusConnection *connection,
                                                            gpointer         user_data)       : Run Last

Emitted when `server` acquires a connection to the session bus.

`server` : | the EDBusServer which emitted the signal
`connection` : | the GDBusConnection to the session bus
`user_data` : | user data set when the signal handler was connected.

### The `"bus-name-acquired"` signal

    void                user_function                      (EDBusServer     *server,
                                                            GDBusConnection *connection,
                                                            gpointer         user_data)       : Run Last

Emitted when `server` acquires its well-known session bus name.

`server` : | the EDBusServer which emitted the signal
`connection` : | the GDBusConnection to the session bus
`user_data` : | user data set when the signal handler was connected.

### The `"bus-name-lost"` signal

    void                user_function                      (EDBusServer     *server,
                                                            GDBusConnection *connection,
                                                            gpointer         user_data)       : Run Last

Emitted when `server` loses its well-known session bus name or the session bus connection has been closed.

`server` : | the EDBusServer which emitted the signal
`connection` : | the GDBusconnection to the session bus, or `NULL` if the connection has been closed
`user_data` : | user data set when the signal handler was connected.

### The `"quit-server"` signal

    void                user_function                      (EDBusServer        *server,
                                                            EDBusServerExitCode code,
                                                            gpointer            user_data)      : Run Last

Emitted to request that `server` quit its main loop.

`server` : | the EDBusServer which emitted the signal
`code` : | an EDBusServerExitCode
`user_data` : | user data set when the signal handler was connected.

### The `"run-server"` signal

    EDBusServerExitCode user_function                      (EDBusServer *server,
                                                            gpointer     user_data)      : Run Last

Emitted to request that `server` start its main loop and attempt to acquire its well-known session bus name.

`server` : | the EDBusServer which emitted the signal
`user_data` : | user data set when the signal handler was connected.
Returns : | an EDBusServerExitCode