Class DBusProxy
- All Implemented Interfaces:
AsyncInitable,DBusInterface,Initable,Proxy
- Direct Known Subclasses:
Collection,Item,Prompt,Service
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.
A watch proxy example
An example using a proxy for a well-known name can be found in
gdbus-example-watch-proxy.c.
- Since:
- 2.26
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic classDBusProxy.Builder<B extends DBusProxy.Builder<B>>Inner class implementing a builder pattern to construct a GObject with properties.static classClass structure forGDBusProxy.static interfaceFunctional interface declaration of theGPropertiesChangedCallbackcallback.static interfaceFunctional interface declaration of theGSignalCallbackcallback.Nested classes/interfaces inherited from class org.gnome.gobject.GObject
GObject.NotifyCallback, GObject.ObjectClassNested classes/interfaces inherited from interface org.gnome.gio.AsyncInitable
AsyncInitable.AsyncInitable$Impl, AsyncInitable.AsyncInitableIfaceNested classes/interfaces inherited from interface org.gnome.gio.DBusInterface
DBusInterface.DBusInterface$Impl, DBusInterface.DBusInterfaceIfaceNested classes/interfaces inherited from interface org.gnome.gio.Initable
Initable.Initable$Impl, Initable.InitableIface -
Constructor Summary
ConstructorsConstructorDescriptionCreates a new DBusProxy.DBusProxy(MemorySegment address) Create a DBusProxy proxy instance for the provided memory address. -
Method Summary
Modifier and TypeMethodDescriptionprotected DBusProxyasParent()Returns this instance as if it were its parent type.static DBusProxy.Builder<? extends DBusProxy.Builder> builder()ADBusProxy.Builderobject constructs aDBusProxywith the specified properties.voidcall(String methodName, @Nullable Variant parameters, Set<DBusCallFlags> flags, int timeoutMsec, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback) Asynchronously invokes themethodNamemethod onproxy.voidcall(String methodName, @Nullable Variant parameters, DBusCallFlags flags, int timeoutMsec, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback) Asynchronously invokes themethodNamemethod onproxy.callFinish(AsyncResult res) Finishes an operation started with g_dbus_proxy_call().callSync(String methodName, @Nullable Variant parameters, Set<DBusCallFlags> flags, int timeoutMsec, @Nullable Cancellable cancellable) Synchronously invokes themethodNamemethod onproxy.callSync(String methodName, @Nullable Variant parameters, DBusCallFlags flags, int timeoutMsec, @Nullable Cancellable cancellable) Synchronously invokes themethodNamemethod onproxy.voidcallWithUnixFdList(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 aGUnixFDListobject.voidcallWithUnixFdList(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 aGUnixFDListobject.callWithUnixFdListFinish(@Nullable Out<UnixFDList> outFdList, AsyncResult res) Finishes an operation started with g_dbus_proxy_call_with_unix_fd_list().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 returnsGUnixFDListobjects.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 returnsGUnixFDListobjects.voidemitGPropertiesChanged(@Nullable Variant changedProperties, @Nullable String @Nullable [] invalidatedProperties) Emits the "g-properties-changed" signal.voidemitGSignal(@Nullable String detail, @Nullable String senderName, String signalName, @Nullable Variant parameters) Emits the "g-signal" signal.static DBusProxyfinish(AsyncResult res) Finishes creating aGDBusProxy.static DBusProxyforBusFinish(AsyncResult res) Finishes creating aGDBusProxy.static DBusProxyforBusSync(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 aGBusTypeinstead of aGDBusConnection.static DBusProxyforBusSync(BusType busType, DBusProxyFlags flags, @Nullable DBusInterfaceInfo info, String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable) Like g_dbus_proxy_new_sync() but takes aGBusTypeinstead of aGDBusConnection.@Nullable VariantgetCachedProperty(String propertyName) Looks up the value for a property from the cache.@Nullable String @Nullable []Gets the names of all cached properties onproxy.Gets the connection this DBusProxy is for.intGets the timeout to use if -1 (specifying default timeout) is passed astimeoutMsecin the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions.getFlags()Gets the flags that this DBusProxy was constructed with.@Nullable DBusInterfaceInfoReturns theGDBusInterfaceInfo, if any, specifying the interface that this DBusProxy conforms to.Gets the D-Bus interface name this DBusProxy is for.static MemoryLayoutThe memory layout of the native struct.@Nullable StringgetName()Gets the name that this DBusProxy was constructed for.@Nullable StringThe unique name that owns the name that this DBusProxy is for ornullif no-one currently owns that name.Gets the object path this DBusProxy is for.static @Nullable TypegetType()Get the GType of the DBusProxy classprotected voidgPropertiesChanged(Variant changedProperties, String invalidatedProperties) Signal class handler for theGDBusProxy::g-properties-changed signal.protected voidSignal class handler for theGDBusProxy::g-signal signal.static voidnew_(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 accessinginterfaceNameon the remote object atobjectPathowned bynameatconnectionand asynchronously loads D-Bus properties unless theDBusProxyFlags.DO_NOT_LOAD_PROPERTIESflag is used.static voidnew_(DBusConnection connection, DBusProxyFlags flags, @Nullable DBusInterfaceInfo info, @Nullable String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback) Creates a proxy for accessinginterfaceNameon the remote object atobjectPathowned bynameatconnectionand asynchronously loads D-Bus properties unless theDBusProxyFlags.DO_NOT_LOAD_PROPERTIESflag is used.static voidnewForBus(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 aGBusTypeinstead of aGDBusConnection.static voidnewForBus(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 aGBusTypeinstead of aGDBusConnection.Emitted when one or more D-Bus properties onproxychanges.onGSignal(@Nullable String detail, DBusProxy.GSignalCallback handler) Emitted when a signal from the remote object and interface thatproxyis for, has been received.voidsetCachedProperty(String propertyName, @Nullable Variant value) Ifvalueis notnull, sets the cached value for the property with namepropertyNameto the value invalue.voidsetDefaultTimeout(int timeoutMsec) Sets the timeout to use if -1 (specifying default timeout) is passed astimeoutMsecin the g_dbus_proxy_call() and g_dbus_proxy_call_sync() functions.voidsetInterfaceInfo(@Nullable DBusInterfaceInfo info) Ensure that interactions with this DBusProxy conform to the given interface.static DBusProxysync(DBusConnection connection, Set<DBusProxyFlags> flags, @Nullable DBusInterfaceInfo info, @Nullable String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable) Creates a proxy for accessinginterfaceNameon the remote object atobjectPathowned bynameatconnectionand synchronously loads D-Bus properties unless theDBusProxyFlags.DO_NOT_LOAD_PROPERTIESflag is used.static DBusProxysync(DBusConnection connection, DBusProxyFlags flags, @Nullable DBusInterfaceInfo info, @Nullable String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable) Creates a proxy for accessinginterfaceNameon the remote object atobjectPathowned bynameatconnectionand synchronously loads D-Bus properties unless theDBusProxyFlags.DO_NOT_LOAD_PROPERTIESflag 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, 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, withPropertiesMethods inherited from class org.gnome.gobject.TypeInstance
callParent, callParent, cast, getPrivate, readGClass, writeGClassMethods inherited from class org.javagi.base.ProxyInstance
equals, handle, hashCodeMethods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, waitMethods inherited from interface org.gnome.gio.AsyncInitable
initAsync, initFinishMethods inherited from interface org.gnome.gio.DBusInterface
getInfo, getObject, setObject
-
Constructor Details
-
DBusProxy
Create a DBusProxy proxy instance for the provided memory address.- Parameters:
address- the memory address of the native object
-
DBusProxy
public DBusProxy()Creates a new DBusProxy.
-
-
Method Details
-
getType
-
getMemoryLayout
The memory layout of the native struct.- Returns:
- the memory layout
-
asParent
Returns this instance as if it were its parent type. This is mostly synonymous to the Javasuperkeyword, but will set the native typeclass function pointers to the parent type. When overriding a native virtual method in Java, "chaining up" withsuper.methodName()doesn't work, because it invokes the overridden function pointer again. To chain up, callasParent().methodName(). This will call the native function pointer of this virtual method in the typeclass of the parent type. -
finish
Finishes creating aGDBusProxy.- Parameters:
res- AGAsyncResultobtained from theGAsyncReadyCallbackfunction passed to g_dbus_proxy_new().- Returns:
- A
GDBusProxyornulliferroris set. Free with g_object_unref(). - Throws:
GErrorException- seeGError- Since:
- 2.26
-
forBusFinish
Finishes creating aGDBusProxy.- Parameters:
res- AGAsyncResultobtained from theGAsyncReadyCallbackfunction passed to g_dbus_proxy_new_for_bus().- Returns:
- A
GDBusProxyornulliferroris set. Free with g_object_unref(). - Throws:
GErrorException- seeGError- Since:
- 2.26
-
forBusSync
public static DBusProxy forBusSync(BusType busType, Set<DBusProxyFlags> flags, @Nullable DBusInterfaceInfo info, String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable) throws GErrorException Like g_dbus_proxy_new_sync() but takes aGBusTypeinstead of aGDBusConnection.GDBusProxyis used in thisGio.DBusProxy#a-watch-proxy-example.- Parameters:
busType- AGBusType.flags- Flags used when constructing the proxy.info- AGDBusInterfaceInfospecifying the minimal interface thatproxyconforms to ornull.name- A bus name (well-known or unique).objectPath- An object path.interfaceName- A D-Bus interface name.cancellable- AGCancellableornull.- Returns:
- A
GDBusProxyornullif error is set. Free with g_object_unref(). - Throws:
GErrorException- seeGError- Since:
- 2.26
-
forBusSync
public static DBusProxy forBusSync(BusType busType, DBusProxyFlags flags, @Nullable DBusInterfaceInfo info, String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable) throws GErrorException Like g_dbus_proxy_new_sync() but takes aGBusTypeinstead of aGDBusConnection.GDBusProxyis used in thisGio.DBusProxy#a-watch-proxy-example.- Parameters:
busType- AGBusType.flags- Flags used when constructing the proxy.info- AGDBusInterfaceInfospecifying the minimal interface thatproxyconforms to ornull.name- A bus name (well-known or unique).objectPath- An object path.interfaceName- A D-Bus interface name.cancellable- AGCancellableornull.- Returns:
- A
GDBusProxyornullif error is set. Free with g_object_unref(). - Throws:
GErrorException- seeGError- Since:
- 2.26
-
sync
public static DBusProxy sync(DBusConnection connection, Set<DBusProxyFlags> flags, @Nullable DBusInterfaceInfo info, @Nullable String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable) throws GErrorException Creates a proxy for accessinginterfaceNameon the remote object atobjectPathowned bynameatconnectionand synchronously loads D-Bus properties unless theDBusProxyFlags.DO_NOT_LOAD_PROPERTIESflag is used.If the
DBusProxyFlags.DO_NOT_CONNECT_SIGNALSflag is not set, also sets up match rules for signals. Connect to theGDBusProxy::g-signal signal to handle signals from the remote object.If both
DBusProxyFlags.DO_NOT_LOAD_PROPERTIESandDBusProxyFlags.DO_NOT_CONNECT_SIGNALSare set, this constructor is guaranteed to return immediately without blocking.If
nameis a well-known name and theDBusProxyFlags.DO_NOT_AUTO_STARTandDBusProxyFlags.DO_NOT_AUTO_START_AT_CONSTRUCTIONflags 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.
GDBusProxyis used in thisGio.DBusProxy#a-watch-proxy-example.- Parameters:
connection- AGDBusConnection.flags- Flags used when constructing the proxy.info- AGDBusInterfaceInfospecifying the minimal interface thatproxyconforms to ornull.name- A bus name (well-known or unique) ornullifconnectionis not a message bus connection.objectPath- An object path.interfaceName- A D-Bus interface name.cancellable- AGCancellableornull.- Returns:
- A
GDBusProxyornullif error is set. Free with g_object_unref(). - Throws:
GErrorException- seeGError- Since:
- 2.26
-
sync
public static DBusProxy sync(DBusConnection connection, DBusProxyFlags flags, @Nullable DBusInterfaceInfo info, @Nullable String name, String objectPath, String interfaceName, @Nullable Cancellable cancellable) throws GErrorException Creates a proxy for accessinginterfaceNameon the remote object atobjectPathowned bynameatconnectionand synchronously loads D-Bus properties unless theDBusProxyFlags.DO_NOT_LOAD_PROPERTIESflag is used.If the
DBusProxyFlags.DO_NOT_CONNECT_SIGNALSflag is not set, also sets up match rules for signals. Connect to theGDBusProxy::g-signal signal to handle signals from the remote object.If both
DBusProxyFlags.DO_NOT_LOAD_PROPERTIESandDBusProxyFlags.DO_NOT_CONNECT_SIGNALSare set, this constructor is guaranteed to return immediately without blocking.If
nameis a well-known name and theDBusProxyFlags.DO_NOT_AUTO_STARTandDBusProxyFlags.DO_NOT_AUTO_START_AT_CONSTRUCTIONflags 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.
GDBusProxyis used in thisGio.DBusProxy#a-watch-proxy-example.- Parameters:
connection- AGDBusConnection.flags- Flags used when constructing the proxy.info- AGDBusInterfaceInfospecifying the minimal interface thatproxyconforms to ornull.name- A bus name (well-known or unique) ornullifconnectionis not a message bus connection.objectPath- An object path.interfaceName- A D-Bus interface name.cancellable- AGCancellableornull.- Returns:
- A
GDBusProxyornullif error is set. Free with g_object_unref(). - Throws:
GErrorException- seeGError- Since:
- 2.26
-
new_
public 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 accessinginterfaceNameon the remote object atobjectPathowned bynameatconnectionand asynchronously loads D-Bus properties unless theDBusProxyFlags.DO_NOT_LOAD_PROPERTIESflag is used. Connect to theGDBusProxy::g-properties-changed signal to get notified about property changes.If the
DBusProxyFlags.DO_NOT_CONNECT_SIGNALSflag is not set, also sets up match rules for signals. Connect to theGDBusProxy::g-signal signal to handle signals from the remote object.If both
DBusProxyFlags.DO_NOT_LOAD_PROPERTIESandDBusProxyFlags.DO_NOT_CONNECT_SIGNALSare set, this constructor is guaranteed to complete immediately without blocking.If
nameis a well-known name and theDBusProxyFlags.DO_NOT_AUTO_STARTandDBusProxyFlags.DO_NOT_AUTO_START_AT_CONSTRUCTIONflags 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,
callbackwill 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.
GDBusProxyis used in thisGio.DBusProxy#a-watch-proxy-example.- Parameters:
connection- AGDBusConnection.flags- Flags used when constructing the proxy.info- AGDBusInterfaceInfospecifying the minimal interface thatproxyconforms to ornull.name- A bus name (well-known or unique) ornullifconnectionis not a message bus connection.objectPath- An object path.interfaceName- A D-Bus interface name.cancellable- AGCancellableornull.callback- Callback function to invoke when the proxy is ready.- Since:
- 2.26
-
new_
public 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 accessinginterfaceNameon the remote object atobjectPathowned bynameatconnectionand asynchronously loads D-Bus properties unless theDBusProxyFlags.DO_NOT_LOAD_PROPERTIESflag is used. Connect to theGDBusProxy::g-properties-changed signal to get notified about property changes.If the
DBusProxyFlags.DO_NOT_CONNECT_SIGNALSflag is not set, also sets up match rules for signals. Connect to theGDBusProxy::g-signal signal to handle signals from the remote object.If both
DBusProxyFlags.DO_NOT_LOAD_PROPERTIESandDBusProxyFlags.DO_NOT_CONNECT_SIGNALSare set, this constructor is guaranteed to complete immediately without blocking.If
nameis a well-known name and theDBusProxyFlags.DO_NOT_AUTO_STARTandDBusProxyFlags.DO_NOT_AUTO_START_AT_CONSTRUCTIONflags 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,
callbackwill 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.
GDBusProxyis used in thisGio.DBusProxy#a-watch-proxy-example.- Parameters:
connection- AGDBusConnection.flags- Flags used when constructing the proxy.info- AGDBusInterfaceInfospecifying the minimal interface thatproxyconforms to ornull.name- A bus name (well-known or unique) ornullifconnectionis not a message bus connection.objectPath- An object path.interfaceName- A D-Bus interface name.cancellable- AGCancellableornull.callback- Callback function to invoke when the proxy is ready.- Since:
- 2.26
-
newForBus
public 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 aGBusTypeinstead of aGDBusConnection.GDBusProxyis used in thisGio.DBusProxy#a-watch-proxy-example.- Parameters:
busType- AGBusType.flags- Flags used when constructing the proxy.info- AGDBusInterfaceInfospecifying the minimal interface thatproxyconforms to ornull.name- A bus name (well-known or unique).objectPath- An object path.interfaceName- A D-Bus interface name.cancellable- AGCancellableornull.callback- Callback function to invoke when the proxy is ready.- Since:
- 2.26
-
newForBus
public 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 aGBusTypeinstead of aGDBusConnection.GDBusProxyis used in thisGio.DBusProxy#a-watch-proxy-example.- Parameters:
busType- AGBusType.flags- Flags used when constructing the proxy.info- AGDBusInterfaceInfospecifying the minimal interface thatproxyconforms to ornull.name- A bus name (well-known or unique).objectPath- An object path.interfaceName- A D-Bus interface name.cancellable- AGCancellableornull.callback- Callback function to invoke when the proxy is ready.- Since:
- 2.26
-
call
public void call(String methodName, @Nullable Variant parameters, Set<DBusCallFlags> flags, int timeoutMsec, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback) Asynchronously invokes themethodNamemethod onproxy.If
methodNamecontains any dots, thennameis split into interface and method name parts. This allows using this DBusProxy for invoking methods on other interfaces.If the
GDBusConnectionassociated with this DBusProxy is closed then the operation will fail withIOErrorEnum.CLOSED. Ifcancellableis canceled, the operation will fail withIOErrorEnum.CANCELLED. Ifparameterscontains a value not compatible with the D-Bus protocol, the operation fails withIOErrorEnum.INVALID_ARGUMENT.If the
parametersGVariantis 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) andmethodNameis referenced by it, then the return value is checked against the return type.This is an asynchronous method. When the operation is finished,
callbackwill be invoked in the thread-default main context (seeMainContext.pushThreadDefault()) 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
callbackisnullthen the D-Bus method call message will be sent with theDBusMessageFlags.NO_REPLY_EXPECTEDflag set.- Parameters:
methodName- Name of method to invoke.parameters- AGVarianttuple with parameters for the signal ornullif not passing parameters.flags- Flags from theGDBusCallFlagsenumeration.timeoutMsec- The timeout in milliseconds (withG_MAXINTmeaning "infinite") or -1 to use the proxy default timeout.cancellable- AGCancellableornull.callback- AGAsyncReadyCallbackto call when the request is satisfied ornullif you don't care about the result of the method invocation.- Since:
- 2.26
-
call
public void call(String methodName, @Nullable Variant parameters, DBusCallFlags flags, int timeoutMsec, @Nullable Cancellable cancellable, @Nullable AsyncReadyCallback callback) Asynchronously invokes themethodNamemethod onproxy.If
methodNamecontains any dots, thennameis split into interface and method name parts. This allows using this DBusProxy for invoking methods on other interfaces.If the
GDBusConnectionassociated with this DBusProxy is closed then the operation will fail withIOErrorEnum.CLOSED. Ifcancellableis canceled, the operation will fail withIOErrorEnum.CANCELLED. Ifparameterscontains a value not compatible with the D-Bus protocol, the operation fails withIOErrorEnum.INVALID_ARGUMENT.If the
parametersGVariantis 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) andmethodNameis referenced by it, then the return value is checked against the return type.This is an asynchronous method. When the operation is finished,
callbackwill be invoked in the thread-default main context (seeMainContext.pushThreadDefault()) 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
callbackisnullthen the D-Bus method call message will be sent with theDBusMessageFlags.NO_REPLY_EXPECTEDflag set.- Parameters:
methodName- Name of method to invoke.parameters- AGVarianttuple with parameters for the signal ornullif not passing parameters.flags- Flags from theGDBusCallFlagsenumeration.timeoutMsec- The timeout in milliseconds (withG_MAXINTmeaning "infinite") or -1 to use the proxy default timeout.cancellable- AGCancellableornull.callback- AGAsyncReadyCallbackto call when the request is satisfied ornullif you don't care about the result of the method invocation.- Since:
- 2.26
-
callFinish
Finishes an operation started with g_dbus_proxy_call().- Parameters:
res- AGAsyncResultobtained from theGAsyncReadyCallbackpassed to g_dbus_proxy_call().- Returns:
nulliferroris set. Otherwise aGVarianttuple with return values. Free with g_variant_unref().- Throws:
GErrorException- seeGError- Since:
- 2.26
-
callSync
public Variant callSync(String methodName, @Nullable Variant parameters, Set<DBusCallFlags> flags, int timeoutMsec, @Nullable Cancellable cancellable) throws GErrorException Synchronously invokes themethodNamemethod onproxy.If
methodNamecontains any dots, thennameis split into interface and method name parts. This allows using this DBusProxy for invoking methods on other interfaces.If the
GDBusConnectionassociated with this DBusProxy is disconnected then the operation will fail withIOErrorEnum.CLOSED. Ifcancellableis canceled, the operation will fail withIOErrorEnum.CANCELLED. Ifparameterscontains a value not compatible with the D-Bus protocol, the operation fails withIOErrorEnum.INVALID_ARGUMENT.If the
parametersGVariantis 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) andmethodNameis referenced by it, then the return value is checked against the return type.- Parameters:
methodName- Name of method to invoke.parameters- AGVarianttuple with parameters for the signal ornullif not passing parameters.flags- Flags from theGDBusCallFlagsenumeration.timeoutMsec- The timeout in milliseconds (withG_MAXINTmeaning "infinite") or -1 to use the proxy default timeout.cancellable- AGCancellableornull.- Returns:
nulliferroris set. Otherwise aGVarianttuple with return values. Free with g_variant_unref().- Throws:
GErrorException- seeGError- Since:
- 2.26
-
callSync
public Variant callSync(String methodName, @Nullable Variant parameters, DBusCallFlags flags, int timeoutMsec, @Nullable Cancellable cancellable) throws GErrorException Synchronously invokes themethodNamemethod onproxy.If
methodNamecontains any dots, thennameis split into interface and method name parts. This allows using this DBusProxy for invoking methods on other interfaces.If the
GDBusConnectionassociated with this DBusProxy is disconnected then the operation will fail withIOErrorEnum.CLOSED. Ifcancellableis canceled, the operation will fail withIOErrorEnum.CANCELLED. Ifparameterscontains a value not compatible with the D-Bus protocol, the operation fails withIOErrorEnum.INVALID_ARGUMENT.If the
parametersGVariantis 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) andmethodNameis referenced by it, then the return value is checked against the return type.- Parameters:
methodName- Name of method to invoke.parameters- AGVarianttuple with parameters for the signal ornullif not passing parameters.flags- Flags from theGDBusCallFlagsenumeration.timeoutMsec- The timeout in milliseconds (withG_MAXINTmeaning "infinite") or -1 to use the proxy default timeout.cancellable- AGCancellableornull.- Returns:
nulliferroris set. Otherwise aGVarianttuple with return values. Free with g_variant_unref().- Throws:
GErrorException- seeGError- Since:
- 2.26
-
callWithUnixFdList
public 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 aGUnixFDListobject.This method is only available on UNIX.
- Parameters:
methodName- Name of method to invoke.parameters- AGVarianttuple with parameters for the signal ornullif not passing parameters.flags- Flags from theGDBusCallFlagsenumeration.timeoutMsec- The timeout in milliseconds (withG_MAXINTmeaning "infinite") or -1 to use the proxy default timeout.fdList- AGUnixFDListornull.cancellable- AGCancellableornull.callback- AGAsyncReadyCallbackto call when the request is satisfied ornullif you don't care about the result of the method invocation.- Since:
- 2.30
-
callWithUnixFdList
public 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 aGUnixFDListobject.This method is only available on UNIX.
- Parameters:
methodName- Name of method to invoke.parameters- AGVarianttuple with parameters for the signal ornullif not passing parameters.flags- Flags from theGDBusCallFlagsenumeration.timeoutMsec- The timeout in milliseconds (withG_MAXINTmeaning "infinite") or -1 to use the proxy default timeout.fdList- AGUnixFDListornull.cancellable- AGCancellableornull.callback- AGAsyncReadyCallbackto call when the request is satisfied ornullif you don't care about the result of the method invocation.- Since:
- 2.30
-
callWithUnixFdListFinish
public Variant callWithUnixFdListFinish(@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 aGUnixFDListornull.res- AGAsyncResultobtained from theGAsyncReadyCallbackpassed to g_dbus_proxy_call_with_unix_fd_list().- Returns:
nulliferroris set. Otherwise aGVarianttuple with return values. Free with g_variant_unref().- Throws:
GErrorException- seeGError- Since:
- 2.30
-
callWithUnixFdListSync
public Variant callWithUnixFdListSync(String methodName, @Nullable Variant parameters, Set<DBusCallFlags> flags, int timeoutMsec, @Nullable UnixFDList fdList, @Nullable Out<UnixFDList> outFdList, @Nullable Cancellable cancellable) throws GErrorException Like g_dbus_proxy_call_sync() but also takes and returnsGUnixFDListobjects.This method is only available on UNIX.
- Parameters:
methodName- Name of method to invoke.parameters- AGVarianttuple with parameters for the signal ornullif not passing parameters.flags- Flags from theGDBusCallFlagsenumeration.timeoutMsec- The timeout in milliseconds (withG_MAXINTmeaning "infinite") or -1 to use the proxy default timeout.fdList- AGUnixFDListornull.outFdList- Return location for aGUnixFDListornull.cancellable- AGCancellableornull.- Returns:
nulliferroris set. Otherwise aGVarianttuple with return values. Free with g_variant_unref().- Throws:
GErrorException- seeGError- Since:
- 2.30
-
callWithUnixFdListSync
public Variant callWithUnixFdListSync(String methodName, @Nullable Variant parameters, DBusCallFlags flags, int timeoutMsec, @Nullable UnixFDList fdList, @Nullable Out<UnixFDList> outFdList, @Nullable Cancellable cancellable) throws GErrorException Like g_dbus_proxy_call_sync() but also takes and returnsGUnixFDListobjects.This method is only available on UNIX.
- Parameters:
methodName- Name of method to invoke.parameters- AGVarianttuple with parameters for the signal ornullif not passing parameters.flags- Flags from theGDBusCallFlagsenumeration.timeoutMsec- The timeout in milliseconds (withG_MAXINTmeaning "infinite") or -1 to use the proxy default timeout.fdList- AGUnixFDListornull.outFdList- Return location for aGUnixFDListornull.cancellable- AGCancellableornull.- Returns:
nulliferroris set. Otherwise aGVarianttuple with return values. Free with g_variant_unref().- Throws:
GErrorException- seeGError- Since:
- 2.30
-
getCachedProperty
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) andpropertyNameis referenced by it, thenvalueis checked against the type of the property.- Parameters:
propertyName- Property name.- Returns:
- A reference to the
GVariantinstance that holds the value forpropertyNameornullif the value is not in the cache. The returned reference must be freed with g_variant_unref(). - Since:
- 2.26
-
getCachedPropertyNames
Gets the names of all cached properties onproxy.- Returns:
- A
null-terminated array of strings ornullif this DBusProxy has no cached properties. Free the returned array with g_strfreev(). - Since:
- 2.26
-
getConnection
Gets the connection this DBusProxy is for.- Returns:
- A
GDBusConnectionowned byproxy.Do not free. - Since:
- 2.26
-
getDefaultTimeout
public int getDefaultTimeout()Gets the timeout to use if -1 (specifying default timeout) is passed astimeoutMsecin 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
proxy. - Since:
- 2.26
-
getFlags
Gets the flags that this DBusProxy was constructed with.- Returns:
- Flags from the
GDBusProxyFlagsenumeration. - Since:
- 2.26
-
getInterfaceInfo
Returns theGDBusInterfaceInfo, if any, specifying the interface that this DBusProxy conforms to. See theGDBusProxy:g-interface-info property for more details.- Returns:
- A
GDBusInterfaceInfoornull. Do not unref the returned object, it is owned byproxy. - Since:
- 2.26
-
getInterfaceName
Gets the D-Bus interface name this DBusProxy is for.- Returns:
- A string owned by
proxy.Do not free. - Since:
- 2.26
-
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 benullfor a proxy that communicates using a peer-to-peer pattern.- Returns:
- A string owned by
proxy.Do not free. - Since:
- 2.26
-
getNameOwner
The unique name that owns the name that this DBusProxy is for ornullif no-one currently owns that name. You may connect to theGObject::notify signal to track changes to theGDBusProxy:g-name-owner property.- Returns:
- The name owner or
nullif no name owner exists. Free with g_free(). - Since:
- 2.26
-
getObjectPath
Gets the object path this DBusProxy is for.- Returns:
- A string owned by
proxy.Do not free. - Since:
- 2.26
-
setCachedProperty
Ifvalueis notnull, sets the cached value for the property with namepropertyNameto the value invalue.If
valueisnull, then the cached value is removed from the property cache.If this DBusProxy has an expected interface (see
GDBusProxy:g-interface-info) andpropertyNameis referenced by it, thenvalueis checked against the type of the property.If the
valueGVariantis 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.PropertiesChangedD-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
ChatroomParticipantswhich 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. signalsChatroomParticipantJoined(String name)andChatroomParticipantParted(String name).- Parameters:
propertyName- Property name.value- Value for the property ornullto remove it from the cache.- Since:
- 2.26
-
setDefaultTimeout
public void setDefaultTimeout(int timeoutMsec) Sets the timeout to use if -1 (specifying default timeout) is passed astimeoutMsecin 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.- Since:
- 2.26
-
setInterfaceInfo
Ensure that interactions with this DBusProxy conform to the given interface. See theGDBusProxy:g-interface-info property for more details.- Parameters:
info- Minimum interface this proxy conforms to ornullto unset.- Since:
- 2.26
-
gPropertiesChanged
-
gSignal
-
onGPropertiesChanged
public SignalConnection<DBusProxy.GPropertiesChangedCallback> onGPropertiesChanged(DBusProxy.GPropertiesChangedCallback handler) Emitted when one or more D-Bus properties onproxychanges. The local cache has already been updated when this signal fires. Note that bothchangedPropertiesandinvalidatedPropertiesare guaranteed to never benull(either may be empty though).If the proxy has the flag
DBusProxyFlags.GET_INVALIDATED_PROPERTIESset, theninvalidatedPropertieswill always be empty.This signal corresponds to the
PropertiesChangedD-Bus signal on theorg.freedesktop.DBus.Propertiesinterface.- Parameters:
handler- the signal handler- Returns:
- a signal handler ID to keep track of the signal connection
- Since:
- 2.26
- See Also:
-
emitGPropertiesChanged
public void emitGPropertiesChanged(@Nullable Variant changedProperties, @Nullable String @Nullable [] invalidatedProperties) Emits the "g-properties-changed" signal. SeeonGPropertiesChanged(org.gnome.gio.DBusProxy.GPropertiesChangedCallback). -
onGSignal
public SignalConnection<DBusProxy.GSignalCallback> onGSignal(@Nullable String detail, DBusProxy.GSignalCallback handler) Emitted when a signal from the remote object and interface thatproxyis for, has been received.Since 2.72 this signal supports detailed connections. You can connect to the detailed signal
g-signal::xin order to receive callbacks only when signalxis received from the remote object.- Parameters:
detail- the signal detailhandler- the signal handler- Returns:
- a signal handler ID to keep track of the signal connection
- Since:
- 2.26
- See Also:
-
emitGSignal
public void emitGSignal(@Nullable String detail, @Nullable String senderName, String signalName, @Nullable Variant parameters) Emits the "g-signal" signal. SeeonGSignal(java.lang.String, org.gnome.gio.DBusProxy.GSignalCallback). -
builder
ADBusProxy.Builderobject constructs aDBusProxywith the specified properties. Use the variousset...()methods to set properties, and finish construction withDBusProxy.Builder.build().- Returns:
- the builder object
-