`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 [flags@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 [property@Gio.DBusProxy:g-name-owner]. Connect to the [
signal@GObject.Object:GDBusProxy: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 [
property@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 [signal@Gio.DBusProxy:GDBusProxy:g-properties-changed
] and [signal@Gio.DBusProxy:GDBusProxy: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](migrating-gdbus.html#using-gdbus-codegen) shows how
this can easily be done using the [`gdbus-codegen`](gdbus-codegen.html) tool.
A `GDBusProxy` instance can be used from multiple threads but note that all signals (e.g. [signal@Gio.DBusProxy:GDBusProxy:g-signal
], [signal@Gio.DBusProxy:GDBusProxy:g-properties-changed
] and [signal@GObject.Object:GDBusProxy:notify
])
are emitted in the thread-default main context (see [method@GLib.MainContext.push_thread_default]) 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`.
- public async Variant call (string method_name, Variant? parameters, DBusCallFlags flags, int timeout_msec, Cancellable? cancellable = null) throws Error
Asynchronously invokes the method_name
method on
this.
- public Variant call_sync (string method_name, Variant? parameters, DBusCallFlags flags, int timeout_msec, Cancellable? cancellable = null) throws Error
Synchronously invokes the method_name
method on
this.
- public async Variant call_with_unix_fd_list (string method_name, Variant? parameters, DBusCallFlags flags, int timeout_msec, UnixFDList? fd_list = null, Cancellable? cancellable = null, out UnixFDList? out_fd_list = null) throws Error
- public Variant call_with_unix_fd_list_sync (string method_name, Variant? parameters, DBusCallFlags flags, int timeout_msec, UnixFDList? fd_list = null, out UnixFDList? out_fd_list = null, Cancellable? cancellable = null) throws Error
- public Variant? get_cached_property (string property_name)
Looks up the value for a property from the cache.
- public string[]? get_cached_property_names ()
Gets the names of all cached properties on
this.
- public unowned DBusConnection get_connection ()
Gets the connection this is for.
- public int get_default_timeout ()
Gets the timeout to use if -1 (specifying default timeout) is passed
as timeout_msec
in the call and
call_sync functions.
- public DBusProxyFlags get_flags ()
Gets the flags that this was
constructed with.
- public unowned DBusInterfaceInfo? get_interface_info ()
Returns the
DBusInterfaceInfo, if any, specifying the interface that this conforms to.
- public unowned string get_interface_name ()
Gets the D-Bus interface name this
is for.
- public unowned string? get_name ()
Gets the name that this was
constructed for.
- public string? get_name_owner ()
The unique name that owns the name that
this is for or null if no-one currently owns that name.
- public unowned string get_object_path ()
Gets the object path this is for.
- public void set_cached_property (string property_name, Variant? value)
If value
is not null,
sets the cached value for the property with name property_name
to the value in value
.
- public void set_default_timeout (int timeout_msec)
Sets the timeout to use if -1 (specifying default timeout) is passed
as timeout_msec
in the call and
call_sync functions.
- public void set_interface_info (DBusInterfaceInfo? info)
Ensure that interactions with this
conform to the given interface.