Package org.gnome.gio

Class DBusServer

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gio.DBusServer

All Implemented Interfaces:

Proxy, Initable

@Generated("io.github.jwharm.JavaGI")
public class DBusServer
extends GObject
implements Initable

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 Gio.busOwnName(org.gnome.gio.BusType, java.lang.String, java.util.Set<org.gnome.gio.BusNameOwnerFlags>, org.gnome.gobject.Closure, org.gnome.gobject.Closure, org.gnome.gobject.Closure).

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 DBusAuthObserver 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.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	DBusServer.Builder<B extends DBusServer.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static interface	DBusServer.NewConnectionCallback	Functional interface declaration of the NewConnectionCallback callback.

Nested classes/interfaces inherited from class org.gnome.gobject.GObject

GObject.NotifyCallback, GObject.ObjectClass

Nested classes/interfaces inherited from interface org.gnome.gio.Initable

Initable.InitableIface, Initable.InitableImpl

Constructor Summary

Constructors

Constructor	Description
DBusServer(MemorySegment address)	Create a DBusServer proxy instance for the provided memory address.

Method Summary

Modifier and Type	Method	Description
protected DBusServer	asParent()	Returns this instance as if it were its parent type.
static DBusServer.Builder<? extends DBusServer.Builder>	builder()	A DBusServer.Builder object constructs a DBusServer with the specified properties.
boolean	emitNewConnection(DBusConnection connection)	Emits the "new-connection" signal.
String	getClientAddress()	Gets a D-Bus address string that can be used by clients to connect to this DBusServer.
Set<DBusServerFlags>	getFlags()	Gets the flags for this DBusServer.
String	getGuid()	Gets the GUID for this DBusServer, as provided to g_dbus_server_new_sync().
static Type	getType()	Get the GType of the DBusServer class
boolean	isActive()	Gets whether this DBusServer is active.
SignalConnection<DBusServer.NewConnectionCallback>	onNewConnection(DBusServer.NewConnectionCallback handler)	Emitted when a new authenticated connection has been made.
void	start()	Starts this DBusServer.
void	stop()	Stops this DBusServer.
static DBusServer	sync(String address, Set<DBusServerFlags> flags, String guid, @Nullable DBusAuthObserver observer, @Nullable Cancellable cancellable)	Creates a new D-Bus server that listens on the first address in address that works.
static DBusServer	sync(String address, DBusServerFlags flags, String guid, @Nullable DBusAuthObserver observer, @Nullable Cancellable cancellable)	Creates a new D-Bus server that listens on the first address in address that works.

Methods inherited from class org.gnome.gobject.GObject

addToggleRef, addWeakPointer, bindProperty, bindProperty, bindProperty, bindPropertyFull, bindPropertyFull, bindPropertyWithClosures, bindPropertyWithClosures, compatControl, connect, connect, connect, constructed, disconnect, dispatchPropertiesChanged, dispose, dupData, dupQdata, emit, emitNotify, finalize_, forceFloating, freezeNotify, get, getData, getMemoryLayout, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, newv, notify, notify, notifyByPspec, onNotify, ref, refSink, removeToggleRef, removeWeakPointer, replaceData, replaceQdata, runDispose, set, setData, setDataFull, setProperty, setProperty, setProperty, setQdata, setQdataFull, setv, stealData, stealQdata, takeRef, thawNotify, unref, watchClosure, weakRef, weakUnref, withProperties

Methods inherited from class org.gnome.gobject.TypeInstance

callParent, callParent, getPrivate, readGClass, writeGClass

Methods inherited from class io.github.jwharm.javagi.base.ProxyInstance

equals, handle, hashCode

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface org.gnome.gio.Initable

init

Methods inherited from interface io.github.jwharm.javagi.base.Proxy

handle

Constructor Details

DBusServer

public DBusServer(MemorySegment address)

Create a DBusServer proxy instance for the provided memory address.

Parameters:

address - the memory address of the native object

Method Details

getType

public static Type getType()

Get the GType of the DBusServer class

Returns:

the GType

asParent

protected DBusServer asParent()

Returns this instance as if it were its parent type. This is mostly synonymous to the Java super keyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" with super.methodName() doesn't work, because it invokes the overridden function pointer again. To chain up, call asParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type.

Overrides:

asParent in class GObject

sync

public static DBusServer sync(String address,
 Set<DBusServerFlags> flags,
 String guid,
 @Nullable
 @Nullable DBusAuthObserver observer,
 @Nullable
 @Nullable Cancellable cancellable)
                       throws GErrorException

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 GDBusServer::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][gdbus-peer-to-peer].

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.

cancellable - A GCancellable or null.

Returns:

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

Throws:

GErrorException - see GError

sync

public static DBusServer sync(String address,
 DBusServerFlags flags,
 String guid,
 @Nullable
 @Nullable DBusAuthObserver observer,
 @Nullable
 @Nullable Cancellable cancellable)
                       throws GErrorException

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 GDBusServer::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][gdbus-peer-to-peer].

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.

cancellable - A GCancellable or null.

Returns:

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

Throws:

GErrorException - see GError

getClientAddress

public String getClientAddress()

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

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

Returns:

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

getFlags

public Set<DBusServerFlags> getFlags()

Gets the flags for this DBusServer.

Returns:

A set of flags from the GDBusServerFlags enumeration.

getGuid

public String getGuid()

Gets the GUID for this DBusServer, as provided to g_dbus_server_new_sync().

Returns:

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

isActive

public boolean isActive()

Gets whether this DBusServer is active.

Returns:

true if server is active, false otherwise.

start

public void start()

Starts this DBusServer.

stop

public void stop()

Stops this DBusServer.

onNewConnection

public SignalConnection<DBusServer.NewConnectionCallback> onNewConnection(DBusServer.NewConnectionCallback handler)

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 GDBusConnection::closed signal.

If GDBusServer:flags contains DBusServerFlags.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][g-main-context-push-thread-default] 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:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• DBusServer.NewConnectionCallback.run(org.gnome.gio.DBusConnection)

emitNewConnection

public boolean emitNewConnection(DBusConnection connection)

Emits the "new-connection" signal. See onNewConnection(org.gnome.gio.DBusServer.NewConnectionCallback).

builder

public static DBusServer.Builder<? extends DBusServer.Builder> builder()

A DBusServer.Builder object constructs a DBusServer with the specified properties. Use the various set...() methods to set properties, and finish construction with DBusServer.Builder.build().