Package org.gnome.gio

Class DBusProxy

java.lang.Object

io.github.jwharm.javagi.base.ProxyInstance

org.gnome.gobject.TypeInstance

org.gnome.gobject.GObject

org.gnome.gio.DBusProxy

All Implemented Interfaces:

Proxy, AsyncInitable, DBusInterface, Initable

@Generated("io.github.jwharm.JavaGI")
public class DBusProxy
extends GObject
implements AsyncInitable, DBusInterface, Initable

GDBusProxy is a base class used for proxies to access a D-Bus interface on a remote object. A GDBusProxy can be constructed for both well-known and unique names.

By default, GDBusProxy will cache all properties (and listen to changes) of the remote object, and proxy all signals that get emitted. This behaviour can be changed by passing suitable Gio.DBusProxyFlags when the proxy is created. If the proxy is for a well-known name, the property cache is flushed when the name owner vanishes and reloaded when a name owner appears.

The unique name owner of the proxy’s name is tracked and can be read from Gio.DBusProxy:g-name-owner. Connect to the GObject.Object::notify signal to get notified of changes. Additionally, only signals and property changes emitted from the current name owner are considered and calls are always sent to the current name owner. This avoids a number of race conditions when the name is lost by one owner and claimed by another. However, if no name owner currently exists, then calls will be sent to the well-known name which may result in the message bus launching an owner (unless G_DBUS_PROXY_FLAGS_DO_NOT_AUTO_START is set).

If the proxy is for a stateless D-Bus service, where the name owner may be started and stopped between calls, the Gio.DBusProxy:g-name-owner tracking of GDBusProxy will cause the proxy to drop signal and property changes from the service after it has restarted for the first time. When interacting with a stateless D-Bus service, do not use GDBusProxy — use direct D-Bus method calls and signal connections.

The generic Gio.DBusProxy::g-properties-changed and Gio.DBusProxy::g-signal signals are not very convenient to work with. Therefore, the recommended way of working with proxies is to subclass GDBusProxy, and have more natural properties and signals in your derived class. This example shows how this can easily be done using the gdbus-codegen tool.

A GDBusProxy instance can be used from multiple threads but note that all signals (e.g. Gio.DBusProxy::g-signal, Gio.DBusProxy::g-properties-changed and GObject.Object::notify) are emitted in the thread-default main context (see MainContext.pushThreadDefault()) of the thread where the instance was constructed.

An example using a proxy for a well-known name can be found in gdbus-example-watch-proxy.c.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	DBusProxy.Builder<B extends DBusProxy.Builder<B>>	Inner class implementing a builder pattern to construct a GObject with properties.
static class	DBusProxy.DBusProxyClass	Class structure for GDBusProxy.
static interface	DBusProxy.GPropertiesChangedCallback	Functional interface declaration of the GPropertiesChangedCallback callback.
static interface	DBusProxy.GSignalCallback	Functional interface declaration of the GSignalCallback callback.

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

GObject.NotifyCallback, GObject.ObjectClass

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

AsyncInitable.AsyncInitableIface, AsyncInitable.AsyncInitableImpl

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

DBusInterface.DBusInterfaceIface, DBusInterface.DBusInterfaceImpl

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

Initable.InitableIface, Initable.InitableImpl

Constructor Summary

Constructors

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

Method Summary

Modifier and Type	Method	Description
protected DBusProxy	asParent()	Returns this instance as if it were its parent type.
static DBusProxy.Builder<? extends DBusProxy.Builder>	builder()	A DBusProxy.Builder object constructs a DBusProxy with the specified properties.
void	call(String methodName, @Nullable Variant parameters, Set<DBusCallFlags> flags, int timeoutMsec, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	Asynchronously invokes the methodName method on this DBusProxy.
void	call(String methodName, @Nullable Variant parameters, DBusCallFlags flags, int timeoutMsec, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	Asynchronously invokes the methodName method on this DBusProxy.
Variant	callFinish(AsyncResult res)	Finishes an operation started with g_dbus_proxy_call().
Variant	callSync(String methodName, @Nullable Variant parameters, Set<DBusCallFlags> flags, int timeoutMsec, @Nullable Cancellable cancellable)	Synchronously invokes the methodName method on this DBusProxy.
Variant	callSync(String methodName, @Nullable Variant parameters, DBusCallFlags flags, int timeoutMsec, @Nullable Cancellable cancellable)	Synchronously invokes the methodName method on this DBusProxy.
void	callWithUnixFdList(String methodName, @Nullable Variant parameters, Set<DBusCallFlags> flags, int timeoutMsec, @Nullable UnixFDList fdList, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	Like g_dbus_proxy_call() but also takes a GUnixFDList object.
void	callWithUnixFdList(String methodName, @Nullable Variant parameters, DBusCallFlags flags, int timeoutMsec, @Nullable UnixFDList fdList, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	Like g_dbus_proxy_call() but also takes a GUnixFDList object.
Variant	callWithUnixFdListFinish(@Nullable Out<UnixFDList> outFdList, AsyncResult res)	Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().
Variant	callWithUnixFdListSync(String methodName, @Nullable Variant parameters, Set<DBusCallFlags> flags, int timeoutMsec, @Nullable UnixFDList fdList, @Nullable Out<UnixFDList> outFdList, @Nullable Cancellable cancellable)	Like g_dbus_proxy_call_sync() but also takes and returns GUnixFDList objects.
Variant	callWithUnixFdListSync(String methodName, @Nullable Variant parameters, DBusCallFlags flags, int timeoutMsec, @Nullable UnixFDList fdList, @Nullable Out<UnixFDList> outFdList, @Nullable Cancellable cancellable)	Like g_dbus_proxy_call_sync() but also takes and returns GUnixFDList objects.
void	emitGPropertiesChanged(Variant changedProperties, String[] invalidatedProperties)	Emits the "g-properties-changed" signal.
void	emitGSignal(@Nullable String detail, @Nullable String senderName, String signalName, Variant parameters)	Emits the "g-signal" signal.
static DBusProxy	finish(AsyncResult res)	Finishes creating a GDBusProxy.
static DBusProxy	forBusFinish(AsyncResult res)	Finishes creating a GDBusProxy.
static DBusProxy	forBusSync(BusType busType, Set<DBusProxyFlags> flags, @Nullable DBusInterfaceInfo info, String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable)	Like g_dbus_proxy_new_sync() but takes a GBusType instead of a GDBusConnection.
static DBusProxy	forBusSync(BusType busType, DBusProxyFlags flags, @Nullable DBusInterfaceInfo info, String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable)	Like g_dbus_proxy_new_sync() but takes a GBusType instead of a GDBusConnection.
Variant	getCachedProperty(String propertyName)	Looks up the value for a property from the cache.
String[]	getCachedPropertyNames()	Gets the names of all cached properties on this DBusProxy.
DBusConnection	getConnection()	Gets the connection this DBusProxy is for.
int	getDefaultTimeout()	Gets the timeout to use if -1 (specifying default timeout) is passed as timeoutMsec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions.
Set<DBusProxyFlags>	getFlags()	Gets the flags that this DBusProxy was constructed with.
DBusInterfaceInfo	getInterfaceInfo()	Returns the GDBusInterfaceInfo, if any, specifying the interface that this DBusProxy conforms to.
String	getInterfaceName()	Gets the D-Bus interface name this DBusProxy is for.
static MemoryLayout	getMemoryLayout()	The memory layout of the native struct.
String	getName()	Gets the name that this DBusProxy was constructed for.
String	getNameOwner()	The unique name that owns the name that this DBusProxy is for or null if no-one currently owns that name.
String	getObjectPath()	Gets the object path this DBusProxy is for.
static Type	getType()	Get the GType of the DBusProxy class
protected void	gPropertiesChanged(Variant changedProperties, String invalidatedProperties)	Signal class handler for the GDBusProxy::g-properties-changed signal.
protected void	gSignal(String senderName, String signalName, Variant parameters)	Signal class handler for the GDBusProxy::g-signal signal.
static void	new_(DBusConnection connection, Set<DBusProxyFlags> flags, @Nullable DBusInterfaceInfo info, @Nullable String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	Creates a proxy for accessing interfaceName on the remote object at objectPath owned by name at connection and asynchronously loads D-Bus properties unless the DBusProxyFlags.DO_NOT_LOAD_PROPERTIES flag is used.
static void	new_(DBusConnection connection, DBusProxyFlags flags, @Nullable DBusInterfaceInfo info, @Nullable String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	Creates a proxy for accessing interfaceName on the remote object at objectPath owned by name at connection and asynchronously loads D-Bus properties unless the DBusProxyFlags.DO_NOT_LOAD_PROPERTIES flag is used.
static void	newForBus(BusType busType, Set<DBusProxyFlags> flags, @Nullable DBusInterfaceInfo info, String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	Like g_dbus_proxy_new() but takes a GBusType instead of a GDBusConnection.
static void	newForBus(BusType busType, DBusProxyFlags flags, @Nullable DBusInterfaceInfo info, String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback)	Like g_dbus_proxy_new() but takes a GBusType instead of a GDBusConnection.
SignalConnection<DBusProxy.GPropertiesChangedCallback>	onGPropertiesChanged(DBusProxy.GPropertiesChangedCallback handler)	Emitted when one or more D-Bus properties on proxy changes.
SignalConnection<DBusProxy.GSignalCallback>	onGSignal(@Nullable String detail, DBusProxy.GSignalCallback handler)	Emitted when a signal from the remote object and interface that proxy is for, has been received.
void	setCachedProperty(String propertyName, @Nullable Variant value)	If value is not null, sets the cached value for the property with name propertyName to the value in value.
void	setDefaultTimeout(int timeoutMsec)	Sets the timeout to use if -1 (specifying default timeout) is passed as timeoutMsec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions.
void	setInterfaceInfo(@Nullable DBusInterfaceInfo info)	Ensure that interactions with this DBusProxy conform to the given interface.
static DBusProxy	sync(DBusConnection connection, Set<DBusProxyFlags> flags, @Nullable DBusInterfaceInfo info, @Nullable String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable)	Creates a proxy for accessing interfaceName on the remote object at objectPath owned by name at connection and synchronously loads D-Bus properties unless the DBusProxyFlags.DO_NOT_LOAD_PROPERTIES flag is used.
static DBusProxy	sync(DBusConnection connection, DBusProxyFlags flags, @Nullable DBusInterfaceInfo info, @Nullable String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable)	Creates a proxy for accessing interfaceName on the remote object at objectPath owned by name at connection and synchronously loads D-Bus properties unless the DBusProxyFlags.DO_NOT_LOAD_PROPERTIES flag is used.

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, getProperty, getProperty, getProperty, getQdata, getv, interfaceFindProperty, interfaceInstallProperty, interfaceListProperties, isFloating, newInstance, newInstance, 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.AsyncInitable

initAsync, initFinish

Methods inherited from interface org.gnome.gio.DBusInterface

getInfo, getObject, setObject

Methods inherited from interface org.gnome.gio.Initable

init

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

handle

Constructor Details

DBusProxy

public DBusProxy(MemorySegment address)

Create a DBusProxy 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 DBusProxy class

Returns:

the GType

getMemoryLayout

public static MemoryLayout getMemoryLayout()

The memory layout of the native struct.

Returns:

the memory layout

asParent

protected DBusProxy 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

finish

public static DBusProxy finish(AsyncResult res)
                        throws GErrorException

Finishes creating a GDBusProxy.

Parameters:

res - A GAsyncResult obtained from the GAsyncReadyCallback function passed to g_dbus_proxy_new().

Returns:

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

Throws:

GErrorException - see GError

forBusFinish

public static DBusProxy forBusFinish(AsyncResult res)
                              throws GErrorException

Finishes creating a GDBusProxy.

Parameters:

res - A GAsyncResult obtained from the GAsyncReadyCallback function passed to g_dbus_proxy_new_for_bus().

Returns:

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

Throws:

GErrorException - see GError

forBusSync

public static DBusProxy forBusSync(BusType busType,
 Set<DBusProxyFlags> flags,
 @Nullable
 @Nullable DBusInterfaceInfo info,
 String name,
 String objectPath,
 String interfaceName,
 @Nullable
 @Nullable Cancellable cancellable)
                            throws GErrorException

Like g_dbus_proxy_new_sync() but takes a GBusType instead of a GDBusConnection.

GDBusProxy is used in this [example][gdbus-wellknown-proxy].

Parameters:

busType - A GBusType.

flags - Flags used when constructing the proxy.

info - A GDBusInterfaceInfo specifying the minimal interface that proxy conforms to or null.

name - A bus name (well-known or unique).

objectPath - An object path.

interfaceName - A D-Bus interface name.

cancellable - A GCancellable or null.

Returns:

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

Throws:

GErrorException - see GError

forBusSync

public static DBusProxy forBusSync(BusType busType,
 DBusProxyFlags flags,
 @Nullable
 @Nullable DBusInterfaceInfo info,
 String name,
 String objectPath,
 String interfaceName,
 @Nullable
 @Nullable Cancellable cancellable)
                            throws GErrorException

Like g_dbus_proxy_new_sync() but takes a GBusType instead of a GDBusConnection.

GDBusProxy is used in this [example][gdbus-wellknown-proxy].

Parameters:

busType - A GBusType.

flags - Flags used when constructing the proxy.

info - A GDBusInterfaceInfo specifying the minimal interface that proxy conforms to or null.

name - A bus name (well-known or unique).

objectPath - An object path.

interfaceName - A D-Bus interface name.

cancellable - A GCancellable or null.

Returns:

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

Throws:

GErrorException - see GError

sync

public static DBusProxy sync(DBusConnection connection,
 Set<DBusProxyFlags> flags,
 @Nullable
 @Nullable DBusInterfaceInfo info,
 @Nullable
 @Nullable String name,
 String objectPath,
 String interfaceName,
 @Nullable
 @Nullable Cancellable cancellable)
                      throws GErrorException

Creates a proxy for accessing interfaceName on the remote object at objectPath owned by name at connection and synchronously loads D-Bus properties unless the DBusProxyFlags.DO_NOT_LOAD_PROPERTIES flag is used.

If the DBusProxyFlags.DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the GDBusProxy::g-signal signal to handle signals from the remote object.

If both DBusProxyFlags.DO_NOT_LOAD_PROPERTIES and DBusProxyFlags.DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to return immediately without blocking.

If name is a well-known name and the DBusProxyFlags.DO_NOT_AUTO_START and DBusProxyFlags.DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

This is a synchronous failable constructor. See g_dbus_proxy_new() and g_dbus_proxy_new_finish() for the asynchronous version.

GDBusProxy is used in this [example][gdbus-wellknown-proxy].

Parameters:

connection - A GDBusConnection.

flags - Flags used when constructing the proxy.

info - A GDBusInterfaceInfo specifying the minimal interface that proxy conforms to or null.

name - A bus name (well-known or unique) or null if connection is not a message bus connection.

objectPath - An object path.

interfaceName - A D-Bus interface name.

cancellable - A GCancellable or null.

Returns:

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

Throws:

GErrorException - see GError

sync

public static DBusProxy sync(DBusConnection connection,
 DBusProxyFlags flags,
 @Nullable
 @Nullable DBusInterfaceInfo info,
 @Nullable
 @Nullable String name,
 String objectPath,
 String interfaceName,
 @Nullable
 @Nullable Cancellable cancellable)
                      throws GErrorException

Creates a proxy for accessing interfaceName on the remote object at objectPath owned by name at connection and synchronously loads D-Bus properties unless the DBusProxyFlags.DO_NOT_LOAD_PROPERTIES flag is used.

If the DBusProxyFlags.DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the GDBusProxy::g-signal signal to handle signals from the remote object.

If both DBusProxyFlags.DO_NOT_LOAD_PROPERTIES and DBusProxyFlags.DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to return immediately without blocking.

If name is a well-known name and the DBusProxyFlags.DO_NOT_AUTO_START and DBusProxyFlags.DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

This is a synchronous failable constructor. See g_dbus_proxy_new() and g_dbus_proxy_new_finish() for the asynchronous version.

GDBusProxy is used in this [example][gdbus-wellknown-proxy].

Parameters:

connection - A GDBusConnection.

flags - Flags used when constructing the proxy.

info - A GDBusInterfaceInfo specifying the minimal interface that proxy conforms to or null.

name - A bus name (well-known or unique) or null if connection is not a message bus connection.

objectPath - An object path.

interfaceName - A D-Bus interface name.

cancellable - A GCancellable or null.

Returns:

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

Throws:

GErrorException - see GError

new_

public static void new_(DBusConnection connection,
 Set<DBusProxyFlags> flags,
 @Nullable
 @Nullable DBusInterfaceInfo info,
 @Nullable
 @Nullable String name,
 String objectPath,
 String interfaceName,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

Creates a proxy for accessing interfaceName on the remote object at objectPath owned by name at connection and asynchronously loads D-Bus properties unless the DBusProxyFlags.DO_NOT_LOAD_PROPERTIES flag is used. Connect to the GDBusProxy::g-properties-changed signal to get notified about property changes.

If the DBusProxyFlags.DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the GDBusProxy::g-signal signal to handle signals from the remote object.

If both DBusProxyFlags.DO_NOT_LOAD_PROPERTIES and DBusProxyFlags.DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to complete immediately without blocking.

If name is a well-known name and the DBusProxyFlags.DO_NOT_AUTO_START and DBusProxyFlags.DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

This is a failable asynchronous constructor - when the proxy is ready, callback will be invoked and you can use g_dbus_proxy_new_finish() to get the result.

See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.

GDBusProxy is used in this [example][gdbus-wellknown-proxy].

Parameters:

connection - A GDBusConnection.

flags - Flags used when constructing the proxy.

info - A GDBusInterfaceInfo specifying the minimal interface that proxy conforms to or null.

name - A bus name (well-known or unique) or null if connection is not a message bus connection.

objectPath - An object path.

interfaceName - A D-Bus interface name.

cancellable - A GCancellable or null.

callback - Callback function to invoke when the proxy is ready.

new_

public static void new_(DBusConnection connection,
 DBusProxyFlags flags,
 @Nullable
 @Nullable DBusInterfaceInfo info,
 @Nullable
 @Nullable String name,
 String objectPath,
 String interfaceName,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

Creates a proxy for accessing interfaceName on the remote object at objectPath owned by name at connection and asynchronously loads D-Bus properties unless the DBusProxyFlags.DO_NOT_LOAD_PROPERTIES flag is used. Connect to the GDBusProxy::g-properties-changed signal to get notified about property changes.

If the DBusProxyFlags.DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the GDBusProxy::g-signal signal to handle signals from the remote object.

If both DBusProxyFlags.DO_NOT_LOAD_PROPERTIES and DBusProxyFlags.DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to complete immediately without blocking.

If name is a well-known name and the DBusProxyFlags.DO_NOT_AUTO_START and DBusProxyFlags.DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren't set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

This is a failable asynchronous constructor - when the proxy is ready, callback will be invoked and you can use g_dbus_proxy_new_finish() to get the result.

See g_dbus_proxy_new_sync() and for a synchronous version of this constructor.

GDBusProxy is used in this [example][gdbus-wellknown-proxy].

Parameters:

connection - A GDBusConnection.

flags - Flags used when constructing the proxy.

info - A GDBusInterfaceInfo specifying the minimal interface that proxy conforms to or null.

name - A bus name (well-known or unique) or null if connection is not a message bus connection.

objectPath - An object path.

interfaceName - A D-Bus interface name.

cancellable - A GCancellable or null.

callback - Callback function to invoke when the proxy is ready.

newForBus

public static void newForBus(BusType busType,
 Set<DBusProxyFlags> flags,
 @Nullable
 @Nullable DBusInterfaceInfo info,
 String name,
 String objectPath,
 String interfaceName,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

Like g_dbus_proxy_new() but takes a GBusType instead of a GDBusConnection.

GDBusProxy is used in this [example][gdbus-wellknown-proxy].

Parameters:

busType - A GBusType.

flags - Flags used when constructing the proxy.

info - A GDBusInterfaceInfo specifying the minimal interface that proxy conforms to or null.

name - A bus name (well-known or unique).

objectPath - An object path.

interfaceName - A D-Bus interface name.

cancellable - A GCancellable or null.

callback - Callback function to invoke when the proxy is ready.

newForBus

public static void newForBus(BusType busType,
 DBusProxyFlags flags,
 @Nullable
 @Nullable DBusInterfaceInfo info,
 String name,
 String objectPath,
 String interfaceName,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

Like g_dbus_proxy_new() but takes a GBusType instead of a GDBusConnection.

GDBusProxy is used in this [example][gdbus-wellknown-proxy].

Parameters:

busType - A GBusType.

flags - Flags used when constructing the proxy.

info - A GDBusInterfaceInfo specifying the minimal interface that proxy conforms to or null.

name - A bus name (well-known or unique).

objectPath - An object path.

interfaceName - A D-Bus interface name.

cancellable - A GCancellable or null.

callback - Callback function to invoke when the proxy is ready.

call

public void call(String methodName,
 @Nullable
 @Nullable Variant parameters,
 Set<DBusCallFlags> flags,
 int timeoutMsec,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

Asynchronously invokes the methodName method on this DBusProxy.

If methodName contains any dots, then name is split into interface and method name parts. This allows using this DBusProxy for invoking methods on other interfaces.

If the GDBusConnection associated with this DBusProxy is closed then the operation will fail with IOErrorEnum.CLOSED. If cancellable is canceled, the operation will fail with IOErrorEnum.CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with IOErrorEnum.INVALID_ARGUMENT.

If the parameters GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.:

 g_dbus_proxy_call (proxy,
                     "TwoStrings",
                     g_variant_new ("(ss)",
                                    "Thing One",
                                    "Thing Two"),
                     G_DBUS_CALL_FLAGS_NONE,
                     -1,
                     NULL,
                     (GAsyncReadyCallback) two_strings_done,
                     &data);
 

If this DBusProxy has an expected interface (see GDBusProxy:g-interface-info) and methodName is referenced by it, then the return value is checked against the return type.

This is an asynchronous method. When the operation is finished, callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call g_dbus_proxy_call_finish() to get the result of the operation. See g_dbus_proxy_call_sync() for the synchronous version of this method.

If callback is null then the D-Bus method call message will be sent with the DBusMessageFlags.NO_REPLY_EXPECTED flag set.

Parameters:

methodName - Name of method to invoke.

parameters - A GVariant tuple with parameters for the signal or null if not passing parameters.

flags - Flags from the GDBusCallFlags enumeration.

timeoutMsec - The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.

cancellable - A GCancellable or null.

callback - A GAsyncReadyCallback to call when the request is satisfied or null if you don't care about the result of the method invocation.

call

public void call(String methodName,
 @Nullable
 @Nullable Variant parameters,
 DBusCallFlags flags,
 int timeoutMsec,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

Asynchronously invokes the methodName method on this DBusProxy.

If methodName contains any dots, then name is split into interface and method name parts. This allows using this DBusProxy for invoking methods on other interfaces.

If the GDBusConnection associated with this DBusProxy is closed then the operation will fail with IOErrorEnum.CLOSED. If cancellable is canceled, the operation will fail with IOErrorEnum.CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with IOErrorEnum.INVALID_ARGUMENT.

If the parameters GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.:

 g_dbus_proxy_call (proxy,
                     "TwoStrings",
                     g_variant_new ("(ss)",
                                    "Thing One",
                                    "Thing Two"),
                     G_DBUS_CALL_FLAGS_NONE,
                     -1,
                     NULL,
                     (GAsyncReadyCallback) two_strings_done,
                     &data);
 

If this DBusProxy has an expected interface (see GDBusProxy:g-interface-info) and methodName is referenced by it, then the return value is checked against the return type.

This is an asynchronous method. When the operation is finished, callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call g_dbus_proxy_call_finish() to get the result of the operation. See g_dbus_proxy_call_sync() for the synchronous version of this method.

If callback is null then the D-Bus method call message will be sent with the DBusMessageFlags.NO_REPLY_EXPECTED flag set.

Parameters:

methodName - Name of method to invoke.

parameters - A GVariant tuple with parameters for the signal or null if not passing parameters.

flags - Flags from the GDBusCallFlags enumeration.

timeoutMsec - The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.

cancellable - A GCancellable or null.

callback - A GAsyncReadyCallback to call when the request is satisfied or null if you don't care about the result of the method invocation.

callFinish

public Variant callFinish(AsyncResult res)
                   throws GErrorException

Finishes an operation started with g_dbus_proxy_call().

Parameters:

res - A GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_proxy_call().

Returns:

null if error is set. Otherwise a GVariant tuple with return values. Free with g_variant_unref().

Throws:

GErrorException - see GError

callSync

public Variant callSync(String methodName,
 @Nullable
 @Nullable Variant parameters,
 Set<DBusCallFlags> flags,
 int timeoutMsec,
 @Nullable
 @Nullable Cancellable cancellable)
                 throws GErrorException

Synchronously invokes the methodName method on this DBusProxy.

If methodName contains any dots, then name is split into interface and method name parts. This allows using this DBusProxy for invoking methods on other interfaces.

If the GDBusConnection associated with this DBusProxy is disconnected then the operation will fail with IOErrorEnum.CLOSED. If cancellable is canceled, the operation will fail with IOErrorEnum.CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with IOErrorEnum.INVALID_ARGUMENT.

If the parameters GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.:

 g_dbus_proxy_call_sync (proxy,
                          "TwoStrings",
                          g_variant_new ("(ss)",
                                         "Thing One",
                                         "Thing Two"),
                          G_DBUS_CALL_FLAGS_NONE,
                          -1,
                          NULL,
                          &error);
 

The calling thread is blocked until a reply is received. See g_dbus_proxy_call() for the asynchronous version of this method.

If this DBusProxy has an expected interface (see GDBusProxy:g-interface-info) and methodName is referenced by it, then the return value is checked against the return type.

Parameters:

methodName - Name of method to invoke.

parameters - A GVariant tuple with parameters for the signal or null if not passing parameters.

flags - Flags from the GDBusCallFlags enumeration.

timeoutMsec - The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.

cancellable - A GCancellable or null.

Returns:

null if error is set. Otherwise a GVariant tuple with return values. Free with g_variant_unref().

Throws:

GErrorException - see GError

callSync

public Variant callSync(String methodName,
 @Nullable
 @Nullable Variant parameters,
 DBusCallFlags flags,
 int timeoutMsec,
 @Nullable
 @Nullable Cancellable cancellable)
                 throws GErrorException

Synchronously invokes the methodName method on this DBusProxy.

If methodName contains any dots, then name is split into interface and method name parts. This allows using this DBusProxy for invoking methods on other interfaces.

If the GDBusConnection associated with this DBusProxy is disconnected then the operation will fail with IOErrorEnum.CLOSED. If cancellable is canceled, the operation will fail with IOErrorEnum.CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with IOErrorEnum.INVALID_ARGUMENT.

If the parameters GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.:

 g_dbus_proxy_call_sync (proxy,
                          "TwoStrings",
                          g_variant_new ("(ss)",
                                         "Thing One",
                                         "Thing Two"),
                          G_DBUS_CALL_FLAGS_NONE,
                          -1,
                          NULL,
                          &error);
 

The calling thread is blocked until a reply is received. See g_dbus_proxy_call() for the asynchronous version of this method.

If this DBusProxy has an expected interface (see GDBusProxy:g-interface-info) and methodName is referenced by it, then the return value is checked against the return type.

Parameters:

methodName - Name of method to invoke.

parameters - A GVariant tuple with parameters for the signal or null if not passing parameters.

flags - Flags from the GDBusCallFlags enumeration.

timeoutMsec - The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.

cancellable - A GCancellable or null.

Returns:

null if error is set. Otherwise a GVariant tuple with return values. Free with g_variant_unref().

Throws:

GErrorException - see GError

callWithUnixFdList

public void callWithUnixFdList(String methodName,
 @Nullable
 @Nullable Variant parameters,
 Set<DBusCallFlags> flags,
 int timeoutMsec,
 @Nullable
 @Nullable UnixFDList fdList,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

Like g_dbus_proxy_call() but also takes a GUnixFDList object.

This method is only available on UNIX.

Parameters:

methodName - Name of method to invoke.

parameters - A GVariant tuple with parameters for the signal or null if not passing parameters.

flags - Flags from the GDBusCallFlags enumeration.

timeoutMsec - The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.

fdList - A GUnixFDList or null.

cancellable - A GCancellable or null.

callback - A GAsyncReadyCallback to call when the request is satisfied or null if you don't care about the result of the method invocation.

callWithUnixFdList

public void callWithUnixFdList(String methodName,
 @Nullable
 @Nullable Variant parameters,
 DBusCallFlags flags,
 int timeoutMsec,
 @Nullable
 @Nullable UnixFDList fdList,
 @Nullable
 @Nullable Cancellable cancellable,
 @Nullable
 @Nullable AsyncReadyCallback callback)

Like g_dbus_proxy_call() but also takes a GUnixFDList object.

This method is only available on UNIX.

Parameters:

methodName - Name of method to invoke.

parameters - A GVariant tuple with parameters for the signal or null if not passing parameters.

flags - Flags from the GDBusCallFlags enumeration.

timeoutMsec - The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.

fdList - A GUnixFDList or null.

cancellable - A GCancellable or null.

callback - A GAsyncReadyCallback to call when the request is satisfied or null if you don't care about the result of the method invocation.

callWithUnixFdListFinish

public Variant callWithUnixFdListFinish(@Nullable
 @Nullable Out<UnixFDList> outFdList,
 AsyncResult res)
                                 throws GErrorException

Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().

Parameters:

outFdList - Return location for a GUnixFDList or null.

res - A GAsyncResult obtained from the GAsyncReadyCallback passed to g_dbus_proxy_call_with_unix_fd_list().

Returns:

null if error is set. Otherwise a GVariant tuple with return values. Free with g_variant_unref().

Throws:

GErrorException - see GError

callWithUnixFdListSync

public Variant callWithUnixFdListSync(String methodName,
 @Nullable
 @Nullable Variant parameters,
 Set<DBusCallFlags> flags,
 int timeoutMsec,
 @Nullable
 @Nullable UnixFDList fdList,
 @Nullable
 @Nullable Out<UnixFDList> outFdList,
 @Nullable
 @Nullable Cancellable cancellable)
                               throws GErrorException

Like g_dbus_proxy_call_sync() but also takes and returns GUnixFDList objects.

This method is only available on UNIX.

Parameters:

methodName - Name of method to invoke.

parameters - A GVariant tuple with parameters for the signal or null if not passing parameters.

flags - Flags from the GDBusCallFlags enumeration.

timeoutMsec - The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.

fdList - A GUnixFDList or null.

outFdList - Return location for a GUnixFDList or null.

cancellable - A GCancellable or null.

Returns:

null if error is set. Otherwise a GVariant tuple with return values. Free with g_variant_unref().

Throws:

GErrorException - see GError

callWithUnixFdListSync

public Variant callWithUnixFdListSync(String methodName,
 @Nullable
 @Nullable Variant parameters,
 DBusCallFlags flags,
 int timeoutMsec,
 @Nullable
 @Nullable UnixFDList fdList,
 @Nullable
 @Nullable Out<UnixFDList> outFdList,
 @Nullable
 @Nullable Cancellable cancellable)
                               throws GErrorException

Like g_dbus_proxy_call_sync() but also takes and returns GUnixFDList objects.

This method is only available on UNIX.

Parameters:

methodName - Name of method to invoke.

parameters - A GVariant tuple with parameters for the signal or null if not passing parameters.

flags - Flags from the GDBusCallFlags enumeration.

timeoutMsec - The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.

fdList - A GUnixFDList or null.

outFdList - Return location for a GUnixFDList or null.

cancellable - A GCancellable or null.

Returns:

null if error is set. Otherwise a GVariant tuple with return values. Free with g_variant_unref().

Throws:

GErrorException - see GError

getCachedProperty

public Variant getCachedProperty(String propertyName)

Looks up the value for a property from the cache. This call does no blocking IO.

If this DBusProxy has an expected interface (see GDBusProxy:g-interface-info) and propertyName is referenced by it, then value is checked against the type of the property.

Parameters:

propertyName - Property name.

Returns:

A reference to the GVariant instance that holds the value for propertyName or null if the value is not in the cache. The returned reference must be freed with g_variant_unref().

getCachedPropertyNames

public String[] getCachedPropertyNames()

Gets the names of all cached properties on this DBusProxy.

Returns:

A null-terminated array of strings or null if this DBusProxy has no cached properties. Free the returned array with g_strfreev().

getConnection

public DBusConnection getConnection()

Gets the connection this DBusProxy is for.

Returns:

A GDBusConnection owned by this DBusProxy. Do not free.

getDefaultTimeout

public int getDefaultTimeout()

Gets the timeout to use if -1 (specifying default timeout) is passed as timeoutMsec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions.

See the GDBusProxy:g-default-timeout property for more details.

Returns:

Timeout to use for this DBusProxy.

getFlags

public Set<DBusProxyFlags> getFlags()

Gets the flags that this DBusProxy was constructed with.

Returns:

Flags from the GDBusProxyFlags enumeration.

getInterfaceInfo

public DBusInterfaceInfo getInterfaceInfo()

Returns the GDBusInterfaceInfo, if any, specifying the interface that this DBusProxy conforms to. See the GDBusProxy:g-interface-info property for more details.

Returns:

A GDBusInterfaceInfo or null. Do not unref the returned object, it is owned by this DBusProxy.

getInterfaceName

public String getInterfaceName()

Gets the D-Bus interface name this DBusProxy is for.

Returns:

A string owned by this DBusProxy. Do not free.

getName

public String getName()

Gets the name that this DBusProxy was constructed for.

When connected to a message bus, this will usually be non-null. However, it may be null for a proxy that communicates using a peer-to-peer pattern.

Returns:

A string owned by this DBusProxy. Do not free.

getNameOwner

public String getNameOwner()

The unique name that owns the name that this DBusProxy is for or null if no-one currently owns that name. You may connect to the GObject::notify signal to track changes to the GDBusProxy:g-name-owner property.

Returns:

The name owner or null if no name owner exists. Free with g_free().

getObjectPath

public String getObjectPath()

Gets the object path this DBusProxy is for.

Returns:

A string owned by this DBusProxy. Do not free.

setCachedProperty

public void setCachedProperty(String propertyName,
 @Nullable
 @Nullable Variant value)

If value is not null, sets the cached value for the property with name propertyName to the value in value.

If value is null, then the cached value is removed from the property cache.

If this DBusProxy has an expected interface (see GDBusProxy:g-interface-info) and propertyName is referenced by it, then value is checked against the type of the property.

If the value GVariant is floating, it is consumed. This allows convenient 'inline' use of g_variant_new(), e.g.

 g_dbus_proxy_set_cached_property (proxy,
                                    "SomeProperty",
                                    g_variant_new ("(si)",
                                                  "A String",
                                                  42));
 

Normally you will not need to use this method since this DBusProxy is tracking changes using the org.freedesktop.DBus.Properties.PropertiesChanged D-Bus signal. However, for performance reasons an object may decide to not use this signal for some properties and instead use a proprietary out-of-band mechanism to transmit changes.

As a concrete example, consider an object with a property ChatroomParticipants which is an array of strings. Instead of transmitting the same (long) array every time the property changes, it is more efficient to only transmit the delta using e.g. signals ChatroomParticipantJoined(String name) and ChatroomParticipantParted(String name).

Parameters:

propertyName - Property name.

value - Value for the property or null to remove it from the cache.

setDefaultTimeout

public void setDefaultTimeout(int timeoutMsec)

Sets the timeout to use if -1 (specifying default timeout) is passed as timeoutMsec in the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions.

See the GDBusProxy:g-default-timeout property for more details.

Parameters:

timeoutMsec - Timeout in milliseconds.

setInterfaceInfo

public void setInterfaceInfo(@Nullable
 @Nullable DBusInterfaceInfo info)

Ensure that interactions with this DBusProxy conform to the given interface. See the GDBusProxy:g-interface-info property for more details.

Parameters:

info - Minimum interface this proxy conforms to or null to unset.

gPropertiesChanged

protected void gPropertiesChanged(Variant changedProperties,
 String invalidatedProperties)

Signal class handler for the GDBusProxy::g-properties-changed signal.

gSignal

protected void gSignal(String senderName,
 String signalName,
 Variant parameters)

Signal class handler for the GDBusProxy::g-signal signal.

onGPropertiesChanged

public SignalConnection<DBusProxy.GPropertiesChangedCallback> onGPropertiesChanged(DBusProxy.GPropertiesChangedCallback handler)

Emitted when one or more D-Bus properties on proxy changes. The local cache has already been updated when this signal fires. Note that both changedProperties and invalidatedProperties are guaranteed to never be null (either may be empty though).

If the proxy has the flag DBusProxyFlags.GET_INVALIDATED_PROPERTIES set, then invalidatedProperties will always be empty.

This signal corresponds to the PropertiesChanged D-Bus signal on the org.freedesktop.DBus.Properties interface.

Parameters:

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• DBusProxy.GPropertiesChangedCallback.run(org.gnome.glib.Variant, java.lang.String[])

emitGPropertiesChanged

public void emitGPropertiesChanged(Variant changedProperties,
 String[] invalidatedProperties)

Emits the "g-properties-changed" signal. See onGPropertiesChanged(org.gnome.gio.DBusProxy.GPropertiesChangedCallback).

onGSignal

public SignalConnection<DBusProxy.GSignalCallback> onGSignal(@Nullable
 @Nullable String detail,
 DBusProxy.GSignalCallback handler)

Emitted when a signal from the remote object and interface that proxy is for, has been received.

Since 2.72 this signal supports detailed connections. You can connect to the detailed signal g-signal::x in order to receive callbacks only when signal x is received from the remote object.

Parameters:

detail - the signal detail

handler - the signal handler

Returns:

a signal handler ID to keep track of the signal connection

See Also:

• DBusProxy.GSignalCallback.run(java.lang.String, java.lang.String, org.gnome.glib.Variant)

emitGSignal

public void emitGSignal(@Nullable
 @Nullable String detail,
 @Nullable
 @Nullable String senderName,
 String signalName,
 Variant parameters)

Emits the "g-signal" signal. See onGSignal(java.lang.String, org.gnome.gio.DBusProxy.GSignalCallback).

builder

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

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