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 GDBus 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. Since GLib 2.68 this can be achieved more simply by passing the G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER flag to the server.

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 , as provided to g_dbus_server_new_sync().

Parameters

server

A GDBusServer.

  

Returns

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

[not nullable]

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 .

This is valid and non-empty if initializing the GDBusServer succeeded.

Parameters

server

A GDBusServer.

  

Returns

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

[not nullable]

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.

  

G_DBUS_SERVER_FLAGS_AUTHENTICATION_REQUIRE_SAME_USER

Require the UID of the peer to be the same as the UID of the server when authenticating. (Since: 2.68)

  

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.

See “guid” for more details.

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

Generated by GTK-Doc V1.33.1