Skip to content

Gio.DBusObjectManagerClient

class — extends GObject.Object, AsyncInitable, DBusObjectManager, Initable

GDBusObjectManagerClient is used to create, monitor and delete object proxies for remote objects exported by a DBusObjectManagerServer (or any code implementing the org.freedesktop.DBus.ObjectManager interface).

Once an instance of this type has been created, you can connect to the DBusObjectManager.object-added and [signalGio.DBusObjectManager::object-removed signals] and inspect the DBusObjectProxy objects returned by DBusObjectManager.get_objects.

If the name for a GDBusObjectManagerClient is not owned by anyone at object construction time, the default behavior is to request the message bus to launch an owner for the name. This behavior can be disabled using the G_DBUS_OBJECT_MANAGER_CLIENT_FLAGS_DO_NOT_AUTO_START flag. It’s also worth noting that this only works if the name of interest is activatable in the first place. E.g. in some cases it is not possible to launch an owner for the requested name. In this case, GDBusObjectManagerClient object construction still succeeds but there will be no object proxies (e.g. DBusObjectManager.get_objects returns the empty list) and the DBusObjectManagerClient.name-owner property is NULL.

The owner of the requested name can come and go (for example consider a system service being restarted) – GDBusObjectManagerClient handles this case too; simply connect to the GObject.Object.notify signal to watch for changes on the DBusObjectManagerClient.name-owner property. When the name owner vanishes, the behavior is that DBusObjectManagerClient.name-owner is set to NULL (this includes emission of the GObject.Object.notify signal) and then DBusObjectManager.object-removed signals are synthesized for all currently existing object proxies. Since DBusObjectManagerClient.name-owner is NULL when this happens, you can use this information to disambiguate a synthesized signal from a genuine signal caused by object removal on the remote DBusObjectManager. Similarly, when a new name owner appears, DBusObjectManager.object-added signals are synthesized while DBusObjectManagerClient.name-owner is still NULL. Only when all object proxies have been added, the DBusObjectManagerClient.name-owner is set to the new name owner (this includes emission of the GObject.Object.notify signal). Furthermore, you are guaranteed that DBusObjectManagerClient.name-owner will alternate between a name owner (e.g. :1.42) and NULL even in the case where the name of interest is atomically replaced

Ultimately, GDBusObjectManagerClient is used to obtain DBusProxy instances. All signals (including the org.freedesktop.DBus.Properties::PropertiesChanged signal) delivered to DBusProxy instances are guaranteed to originate from the name owner. This guarantee along with the behavior described above, means that certain race conditions including the “half the proxy is from the old owner and the other half is from the new owner” problem cannot happen.

To avoid having the application connect to signals on the returned DBusObjectProxy and DBusProxy objects, the DBusObject.interface-added, DBusObject.interface-removed, DBusProxy.g-properties-changed and DBusProxy.g-signal signals are also emitted on the GDBusObjectManagerClient instance managing these objects. The signals emitted are DBusObjectManager.interface-added, DBusObjectManager.interface-removed, DBusObjectManagerClient.interface-proxy-properties-changed and DBusObjectManagerClient.interface-proxy-signal.

Note that all callbacks and signals are emitted in the thread-default main context (see GLib.MainContext.push_thread_default) that the GDBusObjectManagerClient object was constructed in. Additionally, the DBusObjectProxy and DBusProxy objects originating from the GDBusObjectManagerClient object will be created in the same context and, consequently, will deliver signals in the same main loop.

Constructors

new_finish

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

Finishes an operation started with DBusObjectManagerClient.new.

Parameters:

new_for_bus_finish

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

Finishes an operation started with DBusObjectManagerClient.new_for_bus.

Parameters:

new_for_bus_sync

@classmethod
def new_for_bus_sync(cls, bus_type: BusType | int, flags: DBusObjectManagerClientFlags | int, name: str, object_path: str, get_proxy_type_func: DBusProxyTypeFunc | None = ..., cancellable: Cancellable | None = ...) -> DBusObjectManagerClient

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

This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See DBusObjectManagerClient.new_for_bus for the asynchronous version.

Parameters:

  • bus_type — A BusType.
  • flags — Zero or more flags from the DBusObjectManagerClientFlags enumeration.
  • name — The owner of the control object (unique or well-known name).
  • object_path — The object path of the control object.
  • get_proxy_type_func — A GDBusProxyTypeFunc function or None to always construct DBusProxy proxies.
  • cancellable — A Cancellable or None

new_sync

@classmethod
def new_sync(cls, connection: DBusConnection, flags: DBusObjectManagerClientFlags | int, name: str | None, object_path: str, get_proxy_type_func: DBusProxyTypeFunc | None = ..., cancellable: Cancellable | None = ...) -> DBusObjectManagerClient

Creates a new DBusObjectManagerClient object.

This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See DBusObjectManagerClient.new for the asynchronous version.

Parameters:

  • connection — A DBusConnection.
  • flags — Zero or more flags from the DBusObjectManagerClientFlags enumeration.
  • name — The owner of the control object (unique or well-known name), or None when not using a message bus connection.
  • object_path — The object path of the control object.
  • get_proxy_type_func — A GDBusProxyTypeFunc function or None to always construct DBusProxy proxies.
  • cancellable — A Cancellable or None

Methods

get_connection

def get_connection(self) -> DBusConnection

Gets the DBusConnection used by manager.

get_flags

def get_flags(self) -> DBusObjectManagerClientFlags

Gets the flags that manager was constructed with.

get_name

def get_name(self) -> str

Gets the name that manager is for, or None if not a message bus connection.

get_name_owner

def get_name_owner(self) -> str | None

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

Static functions

new

@staticmethod
def new(connection: DBusConnection, flags: DBusObjectManagerClientFlags | int, name: str, object_path: str, get_proxy_type_func: DBusProxyTypeFunc | None = ..., cancellable: Cancellable | None = ..., callback: AsyncReadyCallback | None = ...) -> None

Asynchronously creates a new DBusObjectManagerClient object.

This is an asynchronous failable constructor. When the result is ready, 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 DBusObjectManagerClient.new_finish to get the result. See DBusObjectManagerClient.new_sync for the synchronous version.

Parameters:

  • connection — A DBusConnection.
  • flags — Zero or more flags from the DBusObjectManagerClientFlags enumeration.
  • name — The owner of the control object (unique or well-known name).
  • object_path — The object path of the control object.
  • get_proxy_type_func — A GDBusProxyTypeFunc function or None to always construct DBusProxy proxies.
  • cancellable — A Cancellable or None
  • callback — A GAsyncReadyCallback to call when the request is satisfied.

new_for_bus

@staticmethod
def new_for_bus(bus_type: BusType | int, flags: DBusObjectManagerClientFlags | int, name: str, object_path: str, get_proxy_type_func: DBusProxyTypeFunc | None = ..., cancellable: Cancellable | None = ..., callback: AsyncReadyCallback | None = ...) -> None

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

This is an asynchronous failable constructor. When the result is ready, 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 DBusObjectManagerClient.new_for_bus_finish to get the result. See DBusObjectManagerClient.new_for_bus_sync for the synchronous version.

Parameters:

  • bus_type — A BusType.
  • flags — Zero or more flags from the DBusObjectManagerClientFlags enumeration.
  • name — The owner of the control object (unique or well-known name).
  • object_path — The object path of the control object.
  • get_proxy_type_func — A GDBusProxyTypeFunc function or None to always construct DBusProxy proxies.
  • cancellable — A Cancellable or None
  • callback — A GAsyncReadyCallback to call when the request is satisfied.

Virtual methods

do_interface_proxy_properties_changed

def do_interface_proxy_properties_changed(self, object_proxy: DBusObjectProxy, interface_proxy: DBusProxy, changed_properties: GLib.Variant, invalidated_properties: str) -> None

Signal class handler for the DBusObjectManagerClient::interface-proxy-properties-changed signal.

do_interface_proxy_signal

def do_interface_proxy_signal(self, object_proxy: DBusObjectProxy, interface_proxy: DBusProxy, sender_name: str, signal_name: str, parameters: GLib.Variant) -> None

Signal class handler for the DBusObjectManagerClient::interface-proxy-signal signal.

Properties

bus_type

bus_type: BusType | int  # read/write

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

connection

connection: DBusConnection  # read/write

The DBusConnection to use.

flags

flags: DBusObjectManagerClientFlags | int  # read/write

Flags from the DBusObjectManagerClientFlags enumeration.

get_proxy_type_destroy_notify

get_proxy_type_destroy_notify: int  # read/write

A GDestroyNotify for the #gpointer user_data in DBusObjectManagerClient:get-proxy-type-user-data.

get_proxy_type_func

get_proxy_type_func: int  # read/write

The GDBusProxyTypeFunc to use when determining what GType to use for interface proxies or None.

get_proxy_type_user_data

get_proxy_type_user_data: int  # read/write

The #gpointer user_data to pass to DBusObjectManagerClient:get-proxy-type-func.

name

name: str  # read/write

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

name_owner

name_owner: str  # read-only

The unique name that owns DBusObjectManagerClient:name or None if no-one is currently owning the name. Connect to the GObject.Object::notify signal to track changes to this property.

object_path

object_path: str  # read/write

The object path the manager is for.

Signals

interface-proxy-properties-changed

def on_interface_proxy_properties_changed(self, object_proxy: DBusObjectProxy, interface_proxy: DBusProxy, 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).

This signal exists purely as a convenience to avoid having to connect signals to all interface proxies managed by manager.

This signal is emitted in the thread-default main context (see GLib.MainContext.push_thread_default) that manager was constructed in.

interface-proxy-signal

def on_interface_proxy_signal(self, object_proxy: DBusObjectProxy, interface_proxy: DBusProxy, sender_name: str, signal_name: str, parameters: GLib.Variant) -> None: ...

Emitted when a D-Bus signal is received on interface_proxy.

This signal exists purely as a convenience to avoid having to connect signals to all interface proxies managed by manager.

This signal is emitted in the thread-default main context (see GLib.MainContext.push_thread_default) that manager was constructed in.