Gio.DBusProxy¶

class — extends GObject.Object, 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 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.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 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 DBusProxy.g-properties-changed and 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. DBusProxy.g-signal, DBusProxy.g-properties-changed and GObject.Object.notify) are emitted in the thread-default main context (see GLib.MainContext.push_thread_default) 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.

Constructors¶

new_finish¶

@classmethod
def new_finish(cls, res: AsyncResult) -> DBusProxy

Finishes creating a DBusProxy.

Parameters:

res — A AsyncResult obtained from the GAsyncReadyCallback function passed to DBusProxy.new.

new_for_bus_finish¶

@classmethod
def new_for_bus_finish(cls, res: AsyncResult) -> DBusProxy

Finishes creating a DBusProxy.

Parameters:

res — A AsyncResult obtained from the GAsyncReadyCallback function passed to DBusProxy.new_for_bus.

new_for_bus_sync¶

@classmethod
def new_for_bus_sync(cls, bus_type: BusType | int, flags: DBusProxyFlags | int, info: DBusInterfaceInfo | None, name: str, object_path: str, interface_name: str, cancellable: Cancellable | None = ...) -> DBusProxy

Like DBusProxy.new_sync but takes a BusType instead of a DBusConnection.

DBusProxy is used in this [example][classGio.DBusProxy#a-watch-proxy-example].

Parameters:

bus_type — A BusType.
flags — Flags used when constructing the proxy.
info — A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or None.
name — A bus name (well-known or unique).
object_path — An object path.
interface_name — A D-Bus interface name.
cancellable — A Cancellable or None.

new_sync¶

@classmethod
def new_sync(cls, connection: DBusConnection, flags: DBusProxyFlags | int, info: DBusInterfaceInfo | None, name: str | None, object_path: str, interface_name: str, cancellable: Cancellable | None = ...) -> DBusProxy

Creates a proxy for accessing interface_name on the remote object at object_path 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 DBusProxy::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 DBusProxy.new and DBusProxy.new_finish for the asynchronous version.

DBusProxy is used in this [example][classGio.DBusProxy#a-watch-proxy-example].

Parameters:

connection — A DBusConnection.
flags — Flags used when constructing the proxy.
info — A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or None.
name — A bus name (well-known or unique) or None if connection is not a message bus connection.
object_path — An object path.
interface_name — A D-Bus interface name.
cancellable — A Cancellable or None.

Methods¶

call¶

def call(self, method_name: str, parameters: GLib.Variant | None, flags: DBusCallFlags | int, timeout_msec: int, cancellable: Cancellable | None = ..., callback: Callable[[DBusProxy | None, AsyncResult], None] | None = ...) -> None

Asynchronously invokes the method_name method on proxy.

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

If the DBusConnection associated with proxy 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 GLib.Variant 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 proxy has an expected interface (see DBusProxy:g-interface-info) and method_name 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 (see GLib.MainContext.push_thread_default) of the thread you are calling this method from. You can then call DBusProxy.call_finish to get the result of the operation. See DBusProxy.call_sync for the synchronous version of this method.

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

Parameters:

method_name — Name of method to invoke.
parameters — A GLib.Variant tuple with parameters for the signal or None if not passing parameters.
flags — Flags from the DBusCallFlags enumeration.
timeout_msec — The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.
cancellable — A Cancellable or None.
callback — A GAsyncReadyCallback to call when the request is satisfied or None if you don't care about the result of the method invocation.

call_finish¶

def call_finish(self, res: AsyncResult) -> GLib.Variant

Finishes an operation started with DBusProxy.call.

Parameters:

res — A AsyncResult obtained from the GAsyncReadyCallback passed to DBusProxy.call.

call_sync¶

def call_sync(self, method_name: str, parameters: GLib.Variant | None, flags: DBusCallFlags | int, timeout_msec: int, cancellable: Cancellable | None = ...) -> GLib.Variant

Synchronously invokes the method_name method on proxy.

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

If the DBusConnection associated with proxy 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 GLib.Variant 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 DBusProxy.call for the asynchronous version of this method.

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

Parameters:

method_name — Name of method to invoke.
parameters — A GLib.Variant tuple with parameters for the signal or None if not passing parameters.
flags — Flags from the DBusCallFlags enumeration.
timeout_msec — The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.
cancellable — A Cancellable or None.

call_with_unix_fd_list¶

def call_with_unix_fd_list(self, method_name: str, parameters: GLib.Variant | None, flags: DBusCallFlags | int, timeout_msec: int, fd_list: UnixFDList | None = ..., cancellable: Cancellable | None = ..., callback: Callable[[DBusProxy | None, AsyncResult], None] | None = ...) -> None

Like DBusProxy.call but also takes a UnixFDList object.

This method is only available on UNIX.

Parameters:

method_name — Name of method to invoke.
parameters — A GLib.Variant tuple with parameters for the signal or None if not passing parameters.
flags — Flags from the DBusCallFlags enumeration.
timeout_msec — The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.
fd_list — A UnixFDList or None.
cancellable — A Cancellable or None.
callback — A GAsyncReadyCallback to call when the request is satisfied or None if you don't care about the result of the method invocation.

call_with_unix_fd_list_finish¶

def call_with_unix_fd_list_finish(self, res: AsyncResult) -> tuple[GLib.Variant, UnixFDList]

Finishes an operation started with DBusProxy.call_with_unix_fd_list.

Parameters:

res — A AsyncResult obtained from the GAsyncReadyCallback passed to DBusProxy.call_with_unix_fd_list.

call_with_unix_fd_list_sync¶

def call_with_unix_fd_list_sync(self, method_name: str, parameters: GLib.Variant | None, flags: DBusCallFlags | int, timeout_msec: int, fd_list: UnixFDList | None = ..., cancellable: Cancellable | None = ...) -> tuple[GLib.Variant, UnixFDList]

Like DBusProxy.call_sync but also takes and returns UnixFDList objects.

This method is only available on UNIX.

Parameters:

method_name — Name of method to invoke.
parameters — A GLib.Variant tuple with parameters for the signal or None if not passing parameters.
flags — Flags from the DBusCallFlags enumeration.
timeout_msec — The timeout in milliseconds (with G_MAXINT meaning "infinite") or -1 to use the proxy default timeout.
fd_list — A UnixFDList or None.
cancellable — A Cancellable or None.

get_cached_property¶

def get_cached_property(self, property_name: str) -> GLib.Variant | None

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

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

Parameters:

property_name — Property name.

get_cached_property_names¶

def get_cached_property_names(self) -> list[str] | None

Gets the names of all cached properties on proxy.

get_connection¶

def get_connection(self) -> DBusConnection

Gets the connection proxy is for.

get_default_timeout¶

def get_default_timeout(self) -> int

Gets the timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the DBusProxy.call and DBusProxy.call_sync functions.

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

get_flags¶

def get_flags(self) -> DBusProxyFlags

Gets the flags that proxy was constructed with.

get_interface_info¶

def get_interface_info(self) -> DBusInterfaceInfo | None

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

get_interface_name¶

def get_interface_name(self) -> str

Gets the D-Bus interface name proxy is for.

get_name¶

def get_name(self) -> str | None

Gets the name that proxy was constructed for.

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

get_name_owner¶

def get_name_owner(self) -> str | None

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

get_object_path¶

def get_object_path(self) -> str

Gets the object path proxy is for.

set_cached_property¶

def set_cached_property(self, property_name: str, value: GLib.Variant | None = ...) -> None

If value is not None, sets the cached value for the property with name property_name to the value in value.

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

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

If the value GLib.Variant 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 proxy 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:

property_name — Property name.
value — Value for the property or None to remove it from the cache.

set_default_timeout¶

def set_default_timeout(self, timeout_msec: int) -> None

Sets the timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the DBusProxy.call and DBusProxy.call_sync functions.

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

Parameters:

timeout_msec — Timeout in milliseconds.

set_interface_info¶

def set_interface_info(self, info: DBusInterfaceInfo | None = ...) -> None

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

Parameters:

info — Minimum interface this proxy conforms to or None to unset.

Static functions¶

new¶

@staticmethod
def new(connection: DBusConnection, flags: DBusProxyFlags | int, info: DBusInterfaceInfo | None, name: str | None, object_path: str, interface_name: str, cancellable: Cancellable | None = ..., callback: AsyncReadyCallback | None = ...) -> None

Creates a proxy for accessing interface_name on the remote object at object_path owned by name at connection and asynchronously loads D-Bus properties unless the DBusProxyFlags.DO_NOT_LOAD_PROPERTIES flag is used. Connect to the DBusProxy::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 DBusProxy::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 DBusProxy.new_finish to get the result.

See DBusProxy.new_sync and for a synchronous version of this constructor.

DBusProxy is used in this [example][classGio.DBusProxy#a-watch-proxy-example].

Parameters:

connection — A DBusConnection.
flags — Flags used when constructing the proxy.
info — A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or None.
name — A bus name (well-known or unique) or None if connection is not a message bus connection.
object_path — An object path.
interface_name — A D-Bus interface name.
cancellable — A Cancellable or None.
callback — Callback function to invoke when the proxy is ready.

new_for_bus¶

@staticmethod
def new_for_bus(bus_type: BusType | int, flags: DBusProxyFlags | int, info: DBusInterfaceInfo | None, name: str, object_path: str, interface_name: str, cancellable: Cancellable | None = ..., callback: AsyncReadyCallback | None = ...) -> None

Like DBusProxy.new but takes a BusType instead of a DBusConnection.

DBusProxy is used in this [example][classGio.DBusProxy#a-watch-proxy-example].

Parameters:

bus_type — A BusType.
flags — Flags used when constructing the proxy.
info — A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or None.
name — A bus name (well-known or unique).
object_path — An object path.
interface_name — A D-Bus interface name.
cancellable — A Cancellable or None.
callback — Callback function to invoke when the proxy is ready.

Virtual methods¶

do_g_properties_changed¶

def do_g_properties_changed(self, changed_properties: GLib.Variant, invalidated_properties: str) -> None

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

do_g_signal¶

def do_g_signal(self, sender_name: str, signal_name: str, parameters: GLib.Variant) -> None

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

Properties¶

g_bus_type¶

g_bus_type: BusType | int  # read/write

If this property is not BusType.NONE, then DBusProxy:g-connection must be None and will be set to the DBusConnection obtained by calling bus_get with the value of this property.

g_connection¶

g_connection: DBusConnection  # read/write

The DBusConnection the proxy is for.

g_default_timeout¶

g_default_timeout: int  # read/write

The timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the DBusProxy.call and DBusProxy.call_sync functions.

This allows applications to set a proxy-wide timeout for all remote method invocations on the proxy. If this property is -1, the default timeout (typically 25 seconds) is used. If set to G_MAXINT, then no timeout is used.

g_flags¶

g_flags: DBusProxyFlags | int  # read/write

Flags from the DBusProxyFlags enumeration.

g_interface_info¶

g_interface_info: DBusInterfaceInfo  # read/write

Ensure that interactions with this proxy conform to the given interface. This is mainly to ensure that malformed data received from the other peer is ignored. The given DBusInterfaceInfo is said to be the "expected interface".

The checks performed are: - When completing a method call, if the type signature of the reply message isn't what's expected, the reply is discarded and the GLib.Error is set to IOErrorEnum.INVALID_ARGUMENT.

Received signals that have a type signature mismatch are dropped and a warning is logged via g_warning().
Properties received via the initial GetAll() call or via the ::PropertiesChanged signal (on the org.freedesktop.DBus.Properties interface) or set using DBusProxy.set_cached_property with a type signature mismatch are ignored and a warning is logged via g_warning().

Note that these checks are never done on methods, signals and properties that are not referenced in the given DBusInterfaceInfo, since extending a D-Bus interface on the service-side is not considered an ABI break.

g_interface_name¶

g_interface_name: str  # read/write

The D-Bus interface name the proxy is for.

g_name¶

g_name: str  # read/write

The well-known or unique name that the proxy is for.

g_name_owner¶

g_name_owner: str  # read-only

The unique name that owns DBusProxy:g-name or None if no-one currently owns that name. You may connect to GObject.Object::notify signal to track changes to this property.

g_object_path¶

g_object_path: str  # read/write

The object path the proxy is for.

Signals¶

g-properties-changed¶

def on_g_properties_changed(self, changed_properties: GLib.Variant, invalidated_properties: list[str]) -> None: ...

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 changed_properties and invalidated_properties are guaranteed to never be None (either may be empty though).

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

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

g-signal¶

def on_g_signal(self, sender_name: str | None, signal_name: str, parameters: GLib.Variant) -> None: ...

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.