:right-sidebar: True DBusObjectManagerClient =================================================================== .. currentmodule:: gi.repository.Gio .. versionadded:: 2.30 .. class:: DBusObjectManagerClient(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gio.AsyncInitable`, :class:`~gi.repository.Gio.DBusObjectManager`, :class:`~gi.repository.Gio.Initable` ``GDBusObjectManagerClient`` is used to create, monitor and delete object proxies for remote objects exported by a :obj:`~gi.repository.Gio.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 :obj:`~gi.repository.Gio.DBusObjectManager.signals.object_added` and :obj:`~gi.repository.Gio.DBusObjectManager.signals.object_removed signals` and inspect the :obj:`~gi.repository.Gio.DBusObjectProxy` objects returned by :obj:`~gi.repository.Gio.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. :obj:`~gi.repository.Gio.DBusObjectManager.get_objects` returns the empty list) and the :obj:`~gi.repository.Gio.DBusObjectManagerClient.props.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 :obj:`~gi.repository.GObject.Object.signals.notify` signal to watch for changes on the :obj:`~gi.repository.Gio.DBusObjectManagerClient.props.name_owner` property. When the name owner vanishes, the behavior is that :obj:`~gi.repository.Gio.DBusObjectManagerClient.props.name_owner` is set to ``NULL`` (this includes emission of the :obj:`~gi.repository.GObject.Object.signals.notify` signal) and then :obj:`~gi.repository.Gio.DBusObjectManager.signals.object_removed` signals are synthesized for all currently existing object proxies. Since :obj:`~gi.repository.Gio.DBusObjectManagerClient.props.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 :obj:`~gi.repository.Gio.DBusObjectManager`\. Similarly, when a new name owner appears, :obj:`~gi.repository.Gio.DBusObjectManager.signals.object_added` signals are synthesized while :obj:`~gi.repository.Gio.DBusObjectManagerClient.props.name_owner` is still ``NULL``\. Only when all object proxies have been added, the :obj:`~gi.repository.Gio.DBusObjectManagerClient.props.name_owner` is set to the new name owner (this includes emission of the :obj:`~gi.repository.GObject.Object.signals.notify` signal). Furthermore, you are guaranteed that :obj:`~gi.repository.Gio.DBusObjectManagerClient.props.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 :obj:`~gi.repository.Gio.DBusProxy` instances. All signals (including the ``org.freedesktop.DBus.Properties::PropertiesChanged`` signal) delivered to :obj:`~gi.repository.Gio.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 :obj:`~gi.repository.Gio.DBusObjectProxy` and :obj:`~gi.repository.Gio.DBusProxy` objects, the :obj:`~gi.repository.Gio.DBusObject.signals.interface_added`\, :obj:`~gi.repository.Gio.DBusObject.signals.interface_removed`\, :obj:`~gi.repository.Gio.DBusProxy.signals.g_properties_changed` and :obj:`~gi.repository.Gio.DBusProxy.signals.g_signal` signals are also emitted on the ``GDBusObjectManagerClient`` instance managing these objects. The signals emitted are :obj:`~gi.repository.Gio.DBusObjectManager.signals.interface_added`\, :obj:`~gi.repository.Gio.DBusObjectManager.signals.interface_removed`\, :obj:`~gi.repository.Gio.DBusObjectManagerClient.signals.interface_proxy_properties_changed` and :obj:`~gi.repository.Gio.DBusObjectManagerClient.signals.interface_proxy_signal`\. Note that all callbacks and signals are emitted in the thread-default main context (see :obj:`~gi.repository.GLib.MainContext.push_thread_default`\) that the ``GDBusObjectManagerClient`` object was constructed in. Additionally, the :obj:`~gi.repository.Gio.DBusObjectProxy` and :obj:`~gi.repository.Gio.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 ------------ .. rst-class:: interim-class .. class:: DBusObjectManagerClient :no-index: .. classmethod:: new_finish(res: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.DBusObjectManagerClient Finishes an operation started with :func:`~gi.repository.Gio.DBusObjectManagerClient.new`. .. versionadded:: 2.30 :param res: A :obj:`~gi.repository.Gio.AsyncResult` obtained from the :obj:`~gi.repository.Gio.AsyncReadyCallback` passed to :func:`~gi.repository.Gio.DBusObjectManagerClient.new`. .. classmethod:: new_for_bus_finish(res: ~gi.repository.Gio.AsyncResult) -> ~gi.repository.Gio.DBusObjectManagerClient Finishes an operation started with :func:`~gi.repository.Gio.DBusObjectManagerClient.new_for_bus`. .. versionadded:: 2.30 :param res: A :obj:`~gi.repository.Gio.AsyncResult` obtained from the :obj:`~gi.repository.Gio.AsyncReadyCallback` passed to :func:`~gi.repository.Gio.DBusObjectManagerClient.new_for_bus`. .. classmethod:: new_for_bus_sync(bus_type: ~gi.repository.Gio.BusType, flags: ~gi.repository.Gio.DBusObjectManagerClientFlags, name: str, object_path: str, get_proxy_type_func: ~typing.Callable[[~gi.repository.Gio.DBusObjectManagerClient, str, str | None, ~typing.Any], ~gobject.GType] | None = None, get_proxy_type_user_data: ~typing.Any = None, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.Gio.DBusObjectManagerClient Like :func:`~gi.repository.Gio.DBusObjectManagerClient.new_sync` but takes a :obj:`~gi.repository.Gio.BusType` instead of a :obj:`~gi.repository.Gio.DBusConnection`\. This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See :func:`~gi.repository.Gio.DBusObjectManagerClient.new_for_bus` for the asynchronous version. .. versionadded:: 2.30 :param bus_type: A :obj:`~gi.repository.Gio.BusType`\. :param flags: Zero or more flags from the :obj:`~gi.repository.Gio.DBusObjectManagerClientFlags` enumeration. :param name: The owner of the control object (unique or well-known name). :param object_path: The object path of the control object. :param get_proxy_type_func: A :obj:`~gi.repository.Gio.DBusProxyTypeFunc` function or :const:`None` to always construct :obj:`~gi.repository.Gio.DBusProxy` proxies. :param get_proxy_type_user_data: User data to pass to ``get_proxy_type_func``\. :param cancellable: A :obj:`~gi.repository.Gio.Cancellable` or :const:`None` .. classmethod:: new_sync(connection: ~gi.repository.Gio.DBusConnection, flags: ~gi.repository.Gio.DBusObjectManagerClientFlags, name: str | None, object_path: str, get_proxy_type_func: ~typing.Callable[[~gi.repository.Gio.DBusObjectManagerClient, str, str | None, ~typing.Any], ~gobject.GType] | None = None, get_proxy_type_user_data: ~typing.Any = None, cancellable: ~gi.repository.Gio.Cancellable | None = None) -> ~gi.repository.Gio.DBusObjectManagerClient Creates a new :obj:`~gi.repository.Gio.DBusObjectManagerClient` object. This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See :func:`~gi.repository.Gio.DBusObjectManagerClient.new` for the asynchronous version. .. versionadded:: 2.30 :param connection: A :obj:`~gi.repository.Gio.DBusConnection`\. :param flags: Zero or more flags from the :obj:`~gi.repository.Gio.DBusObjectManagerClientFlags` enumeration. :param name: The owner of the control object (unique or well-known name), or :const:`None` when not using a message bus connection. :param object_path: The object path of the control object. :param get_proxy_type_func: A :obj:`~gi.repository.Gio.DBusProxyTypeFunc` function or :const:`None` to always construct :obj:`~gi.repository.Gio.DBusProxy` proxies. :param get_proxy_type_user_data: User data to pass to ``get_proxy_type_func``\. :param cancellable: A :obj:`~gi.repository.Gio.Cancellable` or :const:`None` Methods ------- .. rst-class:: interim-class .. class:: DBusObjectManagerClient :no-index: .. method:: do_interface_proxy_properties_changed(self, object_proxy: ~gi.repository.Gio.DBusObjectProxy, interface_proxy: ~gi.repository.Gio.DBusProxy, changed_properties: ~gi.repository.GLib.Variant, invalidated_properties: str) -> None :param object_proxy: :param interface_proxy: :param changed_properties: :param invalidated_properties: .. method:: do_interface_proxy_signal(self, object_proxy: ~gi.repository.Gio.DBusObjectProxy, interface_proxy: ~gi.repository.Gio.DBusProxy, sender_name: str, signal_name: str, parameters: ~gi.repository.GLib.Variant) -> None :param object_proxy: :param interface_proxy: :param sender_name: :param signal_name: :param parameters: .. method:: get_connection() -> ~gi.repository.Gio.DBusConnection Gets the :obj:`~gi.repository.Gio.DBusConnection` used by ``manager``\. .. versionadded:: 2.30 .. method:: get_flags() -> ~gi.repository.Gio.DBusObjectManagerClientFlags Gets the flags that ``manager`` was constructed with. .. versionadded:: 2.30 .. method:: get_name() -> str Gets the name that ``manager`` is for, or :const:`None` if not a message bus connection. .. versionadded:: 2.30 .. method:: get_name_owner() -> str | None The unique name that owns the name that ``manager`` is for or :const:`None` if no-one currently owns that name. You can connect to the :obj:`~gi.repository.GObject.Object`\::notify signal to track changes to the :obj:`~gi.repository.Gio.DBusObjectManagerClient`\:name-owner property. .. versionadded:: 2.30 .. classmethod:: new(flags: ~gi.repository.Gio.DBusObjectManagerClientFlags, name: str, object_path: str, get_proxy_type_func: ~typing.Callable[[~gi.repository.Gio.DBusObjectManagerClient, str, str | None, ~typing.Any], ~gobject.GType] | None = None, get_proxy_type_user_data: ~typing.Any = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Asynchronously creates a new :obj:`~gi.repository.Gio.DBusObjectManagerClient` object. This is an asynchronous failable constructor. When the result is ready, ``callback`` will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call :func:`~gi.repository.Gio.DBusObjectManagerClient.new_finish` to get the result. See :func:`~gi.repository.Gio.DBusObjectManagerClient.new_sync` for the synchronous version. .. versionadded:: 2.30 :param flags: Zero or more flags from the :obj:`~gi.repository.Gio.DBusObjectManagerClientFlags` enumeration. :param name: The owner of the control object (unique or well-known name). :param object_path: The object path of the control object. :param get_proxy_type_func: A :obj:`~gi.repository.Gio.DBusProxyTypeFunc` function or :const:`None` to always construct :obj:`~gi.repository.Gio.DBusProxy` proxies. :param get_proxy_type_user_data: User data to pass to ``get_proxy_type_func``\. :param cancellable: A :obj:`~gi.repository.Gio.Cancellable` or :const:`None` :param callback: A :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the request is satisfied. :param user_data: The data to pass to ``callback``\. .. classmethod:: new_for_bus(flags: ~gi.repository.Gio.DBusObjectManagerClientFlags, name: str, object_path: str, get_proxy_type_func: ~typing.Callable[[~gi.repository.Gio.DBusObjectManagerClient, str, str | None, ~typing.Any], ~gobject.GType] | None = None, get_proxy_type_user_data: ~typing.Any = None, cancellable: ~gi.repository.Gio.Cancellable | None = None, callback: ~typing.Callable[[~gi.repository.GObject.Object | None, ~gi.repository.Gio.AsyncResult, ~typing.Any], None] | None = None, user_data: ~typing.Any = None) -> None Like :func:`~gi.repository.Gio.DBusObjectManagerClient.new` but takes a :obj:`~gi.repository.Gio.BusType` instead of a :obj:`~gi.repository.Gio.DBusConnection`\. This is an asynchronous failable constructor. When the result is ready, ``callback`` will be invoked in the [thread-default main loop][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call :func:`~gi.repository.Gio.DBusObjectManagerClient.new_for_bus_finish` to get the result. See :func:`~gi.repository.Gio.DBusObjectManagerClient.new_for_bus_sync` for the synchronous version. .. versionadded:: 2.30 :param flags: Zero or more flags from the :obj:`~gi.repository.Gio.DBusObjectManagerClientFlags` enumeration. :param name: The owner of the control object (unique or well-known name). :param object_path: The object path of the control object. :param get_proxy_type_func: A :obj:`~gi.repository.Gio.DBusProxyTypeFunc` function or :const:`None` to always construct :obj:`~gi.repository.Gio.DBusProxy` proxies. :param get_proxy_type_user_data: User data to pass to ``get_proxy_type_func``\. :param cancellable: A :obj:`~gi.repository.Gio.Cancellable` or :const:`None` :param callback: A :obj:`~gi.repository.Gio.AsyncReadyCallback` to call when the request is satisfied. :param user_data: The data to pass to ``callback``\. Properties ---------- .. rst-class:: interim-class .. class:: DBusObjectManagerClient :no-index: .. attribute:: props.bus_type :type: ~gi.repository.Gio.BusType The type of the None singleton. .. versionadded:: 2.30 .. attribute:: props.connection :type: ~gi.repository.Gio.DBusConnection The type of the None singleton. .. versionadded:: 2.30 .. attribute:: props.flags :type: ~gi.repository.Gio.DBusObjectManagerClientFlags The type of the None singleton. .. versionadded:: 2.30 .. attribute:: props.get_proxy_type_destroy_notify :type: ~typing.Any The type of the None singleton. .. versionadded:: 2.30 .. attribute:: props.get_proxy_type_func :type: ~typing.Any The type of the None singleton. .. versionadded:: 2.30 .. attribute:: props.get_proxy_type_user_data :type: ~typing.Any The type of the None singleton. .. versionadded:: 2.30 .. attribute:: props.name :type: str The type of the None singleton. .. versionadded:: 2.30 .. attribute:: props.name_owner :type: str The type of the None singleton. .. versionadded:: 2.30 .. attribute:: props.object_path :type: str The type of the None singleton. .. versionadded:: 2.30 Signals ------- .. rst-class:: interim-class .. class:: DBusObjectManagerClient.signals :no-index: .. method:: interface_proxy_properties_changed(object_proxy: ~gi.repository.Gio.DBusObjectProxy, interface_proxy: ~gi.repository.Gio.DBusProxy, changed_properties: ~gi.repository.GLib.Variant, invalidated_properties: list[str]) -> None The type of the None singleton. .. versionadded:: 2.30 :param object_proxy: The :obj:`~gi.repository.Gio.DBusObjectProxy` on which an interface has properties that are changing. :param interface_proxy: The :obj:`~gi.repository.Gio.DBusProxy` that has properties that are changing. :param changed_properties: A :obj:`~gi.repository.GLib.Variant` containing the properties that changed (type: ``a{sv}``\). :param invalidated_properties: A :const:`None` terminated array of properties that were invalidated. .. method:: interface_proxy_signal(object_proxy: ~gi.repository.Gio.DBusObjectProxy, interface_proxy: ~gi.repository.Gio.DBusProxy, sender_name: str, signal_name: str, parameters: ~gi.repository.GLib.Variant) -> None The type of the None singleton. .. versionadded:: 2.30 :param object_proxy: The :obj:`~gi.repository.Gio.DBusObjectProxy` on which an interface is emitting a D-Bus signal. :param interface_proxy: The :obj:`~gi.repository.Gio.DBusProxy` that is emitting a D-Bus signal. :param sender_name: The sender of the signal or NULL if the connection is not a bus connection. :param signal_name: The signal name. :param parameters: A :obj:`~gi.repository.GLib.Variant` tuple with parameters for the signal. Virtual Methods --------------- .. rst-class:: interim-class .. class:: DBusObjectManagerClient :no-index: .. method:: do_interface_proxy_properties_changed(object_proxy: ~gi.repository.Gio.DBusObjectProxy, interface_proxy: ~gi.repository.Gio.DBusProxy, changed_properties: ~gi.repository.GLib.Variant, invalidated_properties: str) -> None The type of the None singleton. :param object_proxy: :param interface_proxy: :param changed_properties: :param invalidated_properties: .. method:: do_interface_proxy_signal(object_proxy: ~gi.repository.Gio.DBusObjectProxy, interface_proxy: ~gi.repository.Gio.DBusProxy, sender_name: str, signal_name: str, parameters: ~gi.repository.GLib.Variant) -> None The type of the None singleton. :param object_proxy: :param interface_proxy: :param sender_name: :param signal_name: :param parameters: Fields ------ .. rst-class:: interim-class .. class:: DBusObjectManagerClient :no-index: .. attribute:: parent_instance .. attribute:: priv