Description
GDBusObjectManagerClient is used to create, monitor and delete object
proxies for remote objects exported by a GDBusObjectManagerServer (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
GDBusObjectProxy objects returned by
g_dbus_object_manager_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. g_dbus_object_manager_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
GDBusObjectManager. 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 GDBusProxy
instances. All signals (including the
org.freedesktop.DBus.Properties::PropertiesChanged signal)
delivered to GDBusProxy 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
GDBusObjectProxy and GDBusProxy 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
that the GDBusObjectManagerClient object was constructed
in. Additionally, the GDBusObjectProxy and GDBusProxy objects
originating from the GDBusObjectManagerClient object will be created in
the same context and, consequently, will deliver signals in the
same main loop.
Functions
GDBusProxyTypeFunc ()
GType
(*GDBusProxyTypeFunc) (GDBusObjectManagerClient *manager,
const gchar *object_path,
const gchar *interface_name,
gpointer user_data);
Function signature for a function used to determine the GType to
use for an interface proxy (if interface_name
is not NULL) or
object proxy (if interface_name
is NULL).
This function is called in the
thread-default main loop
that manager
was constructed in.
Since: 2.30
g_dbus_object_manager_client_new ()
void
g_dbus_object_manager_client_new (GDBusConnection *connection,
GDBusObjectManagerClientFlags flags,
const gchar *name,
const gchar *object_path,
GDBusProxyTypeFunc get_proxy_type_func,
gpointer get_proxy_type_user_data,
GDestroyNotify get_proxy_type_destroy_notify,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
Asynchronously creates a new GDBusObjectManagerClient object.
This is an asynchronous failable constructor. When the result is
ready, callback
will be invoked in the
thread-default main context
of the thread you are calling this method from. You can
then call g_dbus_object_manager_client_new_finish() to get the result. See
g_dbus_object_manager_client_new_sync() for the synchronous version.
Since: 2.30
g_dbus_object_manager_client_new_for_bus ()
void
g_dbus_object_manager_client_new_for_bus
(GBusType bus_type,
GDBusObjectManagerClientFlags flags,
const gchar *name,
const gchar *object_path,
GDBusProxyTypeFunc get_proxy_type_func,
gpointer get_proxy_type_user_data,
GDestroyNotify get_proxy_type_destroy_notify,
GCancellable *cancellable,
GAsyncReadyCallback callback,
gpointer user_data);
Like g_dbus_object_manager_client_new() but takes a GBusType instead of a
GDBusConnection.
This is an asynchronous failable constructor. When the result is
ready, callback
will be invoked in the
thread-default main loop
of the thread you are calling this method from. You can
then call g_dbus_object_manager_client_new_for_bus_finish() to get the result. See
g_dbus_object_manager_client_new_for_bus_sync() for the synchronous version.
Since: 2.30
g_dbus_object_manager_client_get_name ()
const gchar *
g_dbus_object_manager_client_get_name (GDBusObjectManagerClient *manager);
Gets the name that manager
is for, or NULL if not a message bus
connection.
Returns
A unique or well-known name. Do not free, the string
belongs to manager
.
Since: 2.30
g_dbus_object_manager_client_get_name_owner ()
gchar *
g_dbus_object_manager_client_get_name_owner
(GDBusObjectManagerClient *manager);
The unique name that owns the name that manager
is for or NULL if
no-one currently owns that name. You can connect to the
“notify” signal to track changes to the
“name-owner” property.
Returns
The name owner or NULL if no name owner
exists. Free with g_free().
[nullable]
Since: 2.30
Types and Values
GDBusObjectManagerClient
typedef struct _GDBusObjectManagerClient GDBusObjectManagerClient;
The GDBusObjectManagerClient structure contains private data and should
only be accessed using the provided API.
Since: 2.30
struct GDBusObjectManagerClientClass
struct GDBusObjectManagerClientClass {
GObjectClass parent_class;
/* signals */
void (*interface_proxy_signal) (GDBusObjectManagerClient *manager,
GDBusObjectProxy *object_proxy,
GDBusProxy *interface_proxy,
const gchar *sender_name,
const gchar *signal_name,
GVariant *parameters);
void (*interface_proxy_properties_changed) (GDBusObjectManagerClient *manager,
GDBusObjectProxy *object_proxy,
GDBusProxy *interface_proxy,
GVariant *changed_properties,
const gchar* const *invalidated_properties);
};
Class structure for GDBusObjectManagerClient.
Since: 2.30
Property Details
The “get-proxy-type-destroy-notify” property
“get-proxy-type-destroy-notify” gpointer
A GDestroyNotify for the gpointer user_data in “get-proxy-type-user-data”.
Owner: GDBusObjectManagerClient
Flags: Read / Write / Construct Only
Since: 2.30
The “get-proxy-type-func” property
“get-proxy-type-func” gpointer
The GDBusProxyTypeFunc to use when determining what GType to
use for interface proxies or NULL.
Owner: GDBusObjectManagerClient
Flags: Read / Write / Construct Only
Since: 2.30
The “get-proxy-type-user-data” property
“get-proxy-type-user-data” gpointer
The gpointer user_data to pass to “get-proxy-type-func”.
Owner: GDBusObjectManagerClient
Flags: Read / Write / Construct Only
Since: 2.30
The “name” property
“name” gchar *
The well-known name or unique name that the manager is for.
Owner: GDBusObjectManagerClient
Flags: Read / Write / Construct Only
Default value: NULL
Since: 2.30
The “name-owner” property
“name-owner” gchar *
The unique name that owns “name” or NULL if
no-one is currently owning the name. Connect to the
“notify” signal to track changes to this property.
Owner: GDBusObjectManagerClient
Flags: Read
Default value: NULL
Since: 2.30
The “object-path” property
“object-path” gchar *
The object path the manager is for.
Owner: GDBusObjectManagerClient
Flags: Read / Write / Construct Only
Default value: NULL
Since: 2.30
Signal Details
The “interface-proxy-properties-changed” signal
void
user_function (GDBusObjectManagerClient *manager,
GDBusObjectProxy *object_proxy,
GDBusProxy *interface_proxy,
GVariant *changed_properties,
GStrv invalidated_properties,
gpointer user_data)
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 NULL (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
that manager
was constructed in.
Flags: Run Last
Since: 2.30
The “interface-proxy-signal” signal
void
user_function (GDBusObjectManagerClient *manager,
GDBusObjectProxy *object_proxy,
GDBusProxy *interface_proxy,
gchar *sender_name,
gchar *signal_name,
GVariant *parameters,
gpointer user_data)
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
that manager
was constructed in.
Flags: Run Last
Since: 2.30