GDBusServer: GIO Reference Manual

## GDBusServer GDBusServer — Helper for accepting connections |

## Functions

GDBusServer * | g_dbus_server_new_sync ()
void | g_dbus_server_start ()
void | g_dbus_server_stop ()
gboolean | g_dbus_server_is_active ()
const gchar * | g_dbus_server_get_guid ()
GDBusServerFlags | g_dbus_server_get_flags ()
const gchar * | g_dbus_server_get_client_address ()

## Properties

gboolean | active | Read
char * | address | Read / Write / Construct Only
GDBusAuthObserver * | authentication-observer | Read / Write / Construct Only
char * | client-address | Read
GDBusServerFlags | flags | Read / Write / Construct Only
char * | guid | Read / Write / Construct Only

## Signals

gboolean | new-connection | Run Last

## Types and Values

| GDBusServer
enum | GDBusServerFlags

## Object Hierarchy

        GFlags
        ╰── GDBusServerFlags
        GObject
        ╰── GDBusServer

## Implemented Interfaces

GDBusServer implements GInitable.

## Includes

    #include <gio/gio.h>

## Description

GDBusServer is a helper for listening to and accepting D-Bus connections. This can be used to create a new D-Bus server, allowing two peers to use the D-Bus protocol for their own specialized communication. A server instance provided in this way will not perform message routing or implement the org.freedesktop.DBus interface.

To just export an object on a well-known name on a message bus, such as the session or system bus, you should instead use `g_bus_own_name()`.

An example of peer-to-peer communication with G-DBus can be found in gdbus-example-peer.c.

Note that a minimal GDBusServer will accept connections from any peer. In many use-cases it will be necessary to add a GDBusAuthObserver that only accepts connections that have successfully authenticated as the same user that is running the GDBusServer.

## Functions

### g_dbus_server_new_sync ()

    GDBusServer *
    g_dbus_server_new_sync (const gchar *address,
                            GDBusServerFlags flags,
                            const gchar *guid,
                            GDBusAuthObserver *observer,
                            GCancellable *cancellable,
                            GError **error);

Creates a new D-Bus server that listens on the first address in `address` that works.

Once constructed, you can use `g_dbus_server_get_client_address()` to get a D-Bus address string that clients can use to connect.

To have control over the available authentication mechanisms and the users that are authorized to connect, it is strongly recommended to provide a non-`NULL` GDBusAuthObserver.

Connect to the “new-connection” signal to handle incoming connections.

The returned GDBusServer isn't active - you have to start it with `g_dbus_server_start()`.

GDBusServer is used in this example.

This is a synchronous failable constructor. There is currently no asynchronous version.

#### Parameters

address | A D-Bus address. |
flags | Flags from the GDBusServerFlags enumeration. |
guid | A D-Bus GUID. |
observer | A GDBusAuthObserver or `NULL`. | [nullable]
cancellable | A GCancellable or `NULL`. | [nullable]
error | Return location for server or `NULL`. |

#### Returns

A GDBusServer or `NULL` if `error` is set. Free with `g_object_unref()`.

Since: 2.26

### g_dbus_server_start ()

    void
    g_dbus_server_start (GDBusServer *server);

Starts `server` .

#### Parameters

server | A GDBusServer. |

Since: 2.26

### g_dbus_server_stop ()

    void
    g_dbus_server_stop (GDBusServer *server);

Stops `server` .

#### Parameters

server | A GDBusServer. |

Since: 2.26

### g_dbus_server_is_active ()

    gboolean
    g_dbus_server_is_active (GDBusServer *server);

Gets whether `server` is active.

#### Parameters

server | A GDBusServer. |

#### Returns

`TRUE` if server is active, `FALSE` otherwise.

Since: 2.26

### g_dbus_server_get_guid ()

    const gchar *
    g_dbus_server_get_guid (GDBusServer *server);

Gets the GUID for `server` .

#### Parameters

server | A GDBusServer. |

#### Returns

A D-Bus GUID. Do not free this string, it is owned by `server` .

Since: 2.26

### g_dbus_server_get_flags ()

    GDBusServerFlags
    g_dbus_server_get_flags (GDBusServer *server);

Gets the flags for `server` .

#### Parameters

server | A GDBusServer. |

#### Returns

A set of flags from the GDBusServerFlags enumeration.

Since: 2.26

### g_dbus_server_get_client_address ()

    const gchar *
    g_dbus_server_get_client_address (GDBusServer *server);

Gets a D-Bus address string that can be used by clients to connect to `server` .

#### Parameters

server | A GDBusServer. |

#### Returns

A D-Bus address string. Do not free, the string is owned by `server` .

Since: 2.26

## Types and Values

### GDBusServer

    typedef struct _GDBusServer GDBusServer;

The GDBusServer structure contains only private data and should only be accessed using the provided API.

Since: 2.26

### enum GDBusServerFlags

Flags used when creating a GDBusServer.

#### Members

G_DBUS_SERVER_FLAGS_NONE | No flags set. |
G_DBUS_SERVER_FLAGS_RUN_IN_THREAD | All “new-connection” signals will run in separated dedicated threads (see signal for details). |
G_DBUS_SERVER_FLAGS_AUTHENTICATION_ALLOW_ANONYMOUS | Allow the anonymous authentication method. |

Since: 2.26

## Property Details

### The `“active”` property

      “active”                   gboolean

Whether the server is currently active.

Owner: GDBusServer

Flags: Read

Default value: FALSE

Since: 2.26

### The `“address”` property

      “address”                  char *

The D-Bus address to listen on.

Owner: GDBusServer

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.26

### The `“authentication-observer”` property

      “authentication-observer”  GDBusAuthObserver *

A GDBusAuthObserver object to assist in the authentication process or `NULL`.

Owner: GDBusServer

Flags: Read / Write / Construct Only

Since: 2.26

### The `“client-address”` property

      “client-address”           char *

The D-Bus address that clients can use.

Owner: GDBusServer

Flags: Read

Default value: NULL

Since: 2.26

### The `“flags”` property

      “flags”                    GDBusServerFlags

Flags from the GDBusServerFlags enumeration.

Owner: GDBusServer

Flags: Read / Write / Construct Only

Since: 2.26

### The `“guid”` property

      “guid”                     char *

The guid of the server.

Owner: GDBusServer

Flags: Read / Write / Construct Only

Default value: NULL

Since: 2.26

## Signal Details

### The `“new-connection”` signal

    gboolean
    user_function (GDBusServer     *server,
                   GDBusConnection *connection,
                   gpointer         user_data)

Emitted when a new authenticated connection has been made. Use `g_dbus_connection_get_peer_credentials()` to figure out what identity (if any), was authenticated.

If you want to accept the connection, take a reference to the `connection` object and return `TRUE`. When you are done with the connection call `g_dbus_connection_close()` and give up your reference. Note that the other peer may disconnect at any time - a typical thing to do when accepting a connection is to listen to the “closed” signal.

If “flags” contains `G_DBUS_SERVER_FLAGS_RUN_IN_THREAD` then the signal is emitted in a new thread dedicated to the connection. Otherwise the signal is emitted in the thread-default main context of the thread that `server` was constructed in.

You are guaranteed that signal handlers for this signal runs before incoming messages on `connection` are processed. This means that it's suitable to call `g_dbus_connection_register_object()` or similar from the signal handler.

#### Parameters

server | The GDBusServer emitting the signal. |
connection | A GDBusConnection for the new connection. |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` to claim `connection` , `FALSE` to let other handlers run.

Flags: Run Last

Since: 2.26