By default, gio.dbus_proxy.DBusProxy 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.types.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
gobject.object.ObjectG.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
gio.types.DBusProxyFlags.DoNotAutoStart 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 gio.dbus_proxy.DBusProxy 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 gio.dbus_proxy.DBusProxy — use direct D-Bus method calls and signal
connections.
The generic signal@Gio.DBusProxy::g-properties-changed and
signal@Gio.DBusProxy::g-signal signals are not very convenient to work
with. Therefore, the recommended way of working with proxies is to subclass
gio.dbus_proxy.DBusProxy, 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.
gio.dbus_proxy.DBusProxy is a base class used for proxies to access a D-Bus interface on a remote object. A gio.dbus_proxy.DBusProxy can be constructed for both well-known and unique names.
By default, gio.dbus_proxy.DBusProxy 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.types.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 gobject.object.ObjectG.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 gio.types.DBusProxyFlags.DoNotAutoStart 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 gio.dbus_proxy.DBusProxy 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 gio.dbus_proxy.DBusProxy — use direct D-Bus method calls and signal connections.
The generic signal@Gio.DBusProxy::g-properties-changed and signal@Gio.DBusProxy::g-signal signals are not very convenient to work with. Therefore, the recommended way of working with proxies is to subclass gio.dbus_proxy.DBusProxy, 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 gio.dbus_proxy.DBusProxy instance can be used from multiple threads but note that all signals (e.g. signal@Gio.DBusProxy::g-signal, signal@Gio.DBusProxy::g-properties-changed and gobject.object.ObjectG.notify) are emitted in the thread-default main context (see glib.main_context.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`.