DBusObjectManagerClient#
Added in version 2.30.
Superclasses: Object
Implemented Interfaces: 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 object_added
and
object_removed signals
and inspect the
DBusObjectProxy
objects returned by
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. get_objects
returns the empty list) and
the 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 notify
signal to watch for changes on the
name_owner
property. When the name
owner vanishes, the behavior is that
name_owner
is set to NULL
(this
includes emission of the notify
signal) and then
object_removed
signals are synthesized
for all currently existing object proxies. Since
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,
object_added
signals are synthesized
while name_owner
is still NULL
. Only
when all object proxies have been added, the
name_owner
is set to the new name
owner (this includes emission of the notify
signal).
Furthermore, you are guaranteed that
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
interface_added
,
interface_removed
,
g_properties_changed
and
g_signal
signals
are also emitted on the GDBusObjectManagerClient
instance managing these
objects. The signals emitted are
interface_added
,
interface_removed
,
interface_proxy_properties_changed
and
interface_proxy_signal
.
Note that all callbacks and signals are emitted in the
thread-default main context (see
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#
- class DBusObjectManagerClient
- classmethod new_finish(res: AsyncResult) DBusObjectManagerClient #
Finishes an operation started with
new()
.Added in version 2.30.
- Parameters:
res – A
AsyncResult
obtained from theAsyncReadyCallback
passed tonew()
.
- classmethod new_for_bus_finish(res: AsyncResult) DBusObjectManagerClient #
Finishes an operation started with
new_for_bus()
.Added in version 2.30.
- Parameters:
res – A
AsyncResult
obtained from theAsyncReadyCallback
passed tonew_for_bus()
.
- classmethod new_for_bus_sync(bus_type: BusType, flags: DBusObjectManagerClientFlags, name: str, object_path: str, get_proxy_type_func: Callable[[...], type] | None = None, cancellable: Cancellable | None = None, *get_proxy_type_user_data: Any) DBusObjectManagerClient #
Like
new_sync()
but takes aBusType
instead of aDBusConnection
.This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See
new_for_bus()
for the asynchronous version.Added in version 2.30.
- 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
DBusProxyTypeFunc
function orNone
to always constructDBusProxy
proxies.cancellable – A
Cancellable
orNone
get_proxy_type_user_data – User data to pass to
get_proxy_type_func
.
- classmethod new_sync(connection: DBusConnection, flags: DBusObjectManagerClientFlags, name: str | None, object_path: str, get_proxy_type_func: Callable[[...], type] | None = None, cancellable: Cancellable | None = None, *get_proxy_type_user_data: Any) DBusObjectManagerClient #
Creates a new
DBusObjectManagerClient
object.This is a synchronous failable constructor - the calling thread is blocked until a reply is received. See
new()
for the asynchronous version.Added in version 2.30.
- 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
DBusProxyTypeFunc
function orNone
to always constructDBusProxy
proxies.cancellable – A
Cancellable
orNone
get_proxy_type_user_data – User data to pass to
get_proxy_type_func
.
Methods#
- class DBusObjectManagerClient
- get_connection() DBusConnection #
Gets the
DBusConnection
used bymanager
.Added in version 2.30.
- get_flags() DBusObjectManagerClientFlags #
Gets the flags that
manager
was constructed with.Added in version 2.30.
- get_name() str #
Gets the name that
manager
is for, orNone
if not a message bus connection.Added in version 2.30.
- get_name_owner() str | None #
The unique name that owns the name that
manager
is for orNone
if no-one currently owns that name. You can connect to theObject
::notify signal to track changes to theDBusObjectManagerClient
:name-owner property.Added in version 2.30.
- new(connection: DBusConnection, flags: DBusObjectManagerClientFlags, name: str, object_path: str, get_proxy_type_func: Callable[[...], type] | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) 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][g-main-context-push-thread-default] of the thread you are calling this method from. You can then callnew_finish()
to get the result. Seenew_sync()
for the synchronous version.Added in version 2.30.
- 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
DBusProxyTypeFunc
function orNone
to always constructDBusProxy
proxies.cancellable – A
Cancellable
orNone
callback – A
AsyncReadyCallback
to call when the request is satisfied.user_data – The data to pass to
callback
.
- new_for_bus(bus_type: BusType, flags: DBusObjectManagerClientFlags, name: str, object_path: str, get_proxy_type_func: Callable[[...], type] | None = None, cancellable: Cancellable | None = None, callback: Callable[[...], None] | None = None, *user_data: Any) None #
Like
new()
but takes aBusType
instead of aDBusConnection
.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 callnew_for_bus_finish()
to get the result. Seenew_for_bus_sync()
for the synchronous version.Added in version 2.30.
- 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
DBusProxyTypeFunc
function orNone
to always constructDBusProxy
proxies.cancellable – A
Cancellable
orNone
callback – A
AsyncReadyCallback
to call when the request is satisfied.user_data – The data to pass to
callback
.
Properties#
- class DBusObjectManagerClient
-
- props.connection: DBusConnection#
The type of the None singleton.
Added in version 2.30.
- props.flags: DBusObjectManagerClientFlags#
The type of the None singleton.
Added in version 2.30.
Signals#
- class DBusObjectManagerClient.signals
- interface_proxy_properties_changed(object_proxy: DBusObjectProxy, interface_proxy: DBusProxy, changed_properties: Variant, invalidated_properties: Sequence[str]) None #
The type of the None singleton.
Added in version 2.30.
- Parameters:
object_proxy – The
DBusObjectProxy
on which an interface has properties that are changing.interface_proxy – The
DBusProxy
that has properties that are changing.changed_properties – A
Variant
containing the properties that changed (type:a{sv}
).invalidated_properties – A
None
terminated array of properties that were invalidated.
- interface_proxy_signal(object_proxy: DBusObjectProxy, interface_proxy: DBusProxy, sender_name: str, signal_name: str, parameters: Variant) None #
The type of the None singleton.
Added in version 2.30.
- Parameters:
object_proxy – The
DBusObjectProxy
on which an interface is emitting a D-Bus signal.interface_proxy – The
DBusProxy
that is emitting a D-Bus signal.sender_name – The sender of the signal or NULL if the connection is not a bus connection.
signal_name – The signal name.
parameters – A
Variant
tuple with parameters for the signal.
Virtual Methods#
- class DBusObjectManagerClient