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
DBusProxy:gNameOwner. Connect to the
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
DBusProxy:gNameOwner 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
DBusProxy::gPropertiesChanged and
DBusProxy::gSignal 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.
DBusProxy::gSignal,
DBusProxy::gPropertiesChanged and
Object::notify) are
emitted in the thread-default main context (see
mainContextPushThreadDefault) 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