mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-01-11 23:16:14 +01:00
docs: Move the GDBusObjectManagerClient SECTION
Move it to the struct docs. Signed-off-by: Philip Withnall <philip@tecnocode.co.uk> Helps: #3037
This commit is contained in:
Philip Withnall
parent
264ebbbb2b
commit
99e25e74ef
@ -43,85 +43,88 @@
|
||||
#include "gmarshal-internal.h"
|
||||
|
||||
/**
|
||||
* SECTION:gdbusobjectmanagerclient
|
||||
* @short_description: Client-side object manager
|
||||
* @include: gio/gio.h
|
||||
* GDBusObjectManagerClient:
|
||||
*
|
||||
* #GDBusObjectManagerClient is used to create, monitor and delete object
|
||||
* proxies for remote objects exported by a #GDBusObjectManagerServer (or any
|
||||
* code implementing the
|
||||
* `GDBusObjectManagerClient` is used to create, monitor and delete object
|
||||
* proxies for remote objects exported by a [class@Gio.DBusObjectManagerServer]
|
||||
* (or any code implementing the
|
||||
* [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
|
||||
* interface).
|
||||
*
|
||||
* Once an instance of this type has been created, you can connect to
|
||||
* the #GDBusObjectManager::object-added and
|
||||
* #GDBusObjectManager::object-removed signals and inspect the
|
||||
* #GDBusObjectProxy objects returned by
|
||||
* g_dbus_object_manager_get_objects().
|
||||
* the [signal@Gio.DBusObjectManager::object-added] and
|
||||
* [signal@Gio.DBusObjectManager::object-removed signals] and inspect the
|
||||
* [class@Gio.DBusObjectProxy] objects returned by
|
||||
* [method@Gio.DBusObjectManager.get_objects].
|
||||
*
|
||||
* If the name for a #GDBusObjectManagerClient is not owned by anyone at
|
||||
* 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
|
||||
* 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
|
||||
* 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 #GDBusObjectManagerClient:name-owner property is %NULL.
|
||||
* (e.g. [method@Gio.DBusObjectManager.get_objects] returns the empty list) and
|
||||
* the [property@Gio.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::notify
|
||||
* signal to watch for changes on the #GDBusObjectManagerClient:name-owner
|
||||
* property. When the name owner vanishes, the behavior is that
|
||||
* #GDBusObjectManagerClient:name-owner is set to %NULL (this includes
|
||||
* emission of the #GObject::notify signal) and then
|
||||
* #GDBusObjectManager::object-removed signals are synthesized
|
||||
* consider a system service being restarted) – `GDBusObjectManagerClient`
|
||||
* handles this case too; simply connect to the [signal@GObject.Object::notify]
|
||||
* signal to watch for changes on the
|
||||
* [property@Gio.DBusObjectManagerClient:name-owner] property. When the name
|
||||
* owner vanishes, the behavior is that
|
||||
* [property@Gio.DBusObjectManagerClient:name-owner] is set to `NULL` (this
|
||||
* includes emission of the [signal@GObject.Object::notify] signal) and then
|
||||
* [signal@Gio.DBusObjectManager::object-removed] signals are synthesized
|
||||
* for all currently existing object proxies. Since
|
||||
* #GDBusObjectManagerClient: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,
|
||||
* #GDBusObjectManager::object-added signals are synthesized
|
||||
* while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all
|
||||
* object proxies have been added, the #GDBusObjectManagerClient:name-owner
|
||||
* is set to the new name owner (this includes emission of the
|
||||
* #GObject::notify signal). Furthermore, you are guaranteed that
|
||||
* #GDBusObjectManagerClient:name-owner will alternate between a name owner
|
||||
* (e.g. `:1.42`) and %NULL even in the case where
|
||||
* [property@Gio.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
|
||||
* [iface@Gio.DBusObjectManager]. Similarly, when a new name owner appears,
|
||||
* [signal@Gio.DBusObjectManager::object-added] signals are synthesized
|
||||
* while [property@Gio.DBusObjectManagerClient:name-owner] is still `NULL`. Only
|
||||
* when all object proxies have been added, the
|
||||
* [property@Gio.DBusObjectManagerClient:name-owner] is set to the new name
|
||||
* owner (this includes emission of the [signal@GObject.Object::notify] signal).
|
||||
* Furthermore, you are guaranteed that
|
||||
* [property@Gio.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 #GDBusProxy
|
||||
* instances. All signals (including the
|
||||
* org.freedesktop.DBus.Properties::PropertiesChanged signal)
|
||||
* delivered to #GDBusProxy instances are guaranteed to originate
|
||||
* Ultimately, `GDBusObjectManagerClient` is used to obtain
|
||||
* [class@Gio.DBusProxy] instances. All signals (including the
|
||||
* `org.freedesktop.DBus.Properties::PropertiesChanged` signal)
|
||||
* delivered to [class@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.
|
||||
* “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
|
||||
* #GDBusObject::interface-added,
|
||||
* #GDBusObject::interface-removed,
|
||||
* #GDBusProxy::g-properties-changed and
|
||||
* #GDBusProxy::g-signal signals
|
||||
* are also emitted on the #GDBusObjectManagerClient instance managing these
|
||||
* [class@Gio.DBusObjectProxy] and [class@Gio.DBusProxy] objects, the
|
||||
* [signal@Gio.DBusObject::interface-added],
|
||||
* [signal@Gio.DBusObject::interface-removed],
|
||||
* [signal@Gio.DBusProxy::g-properties-changed] and
|
||||
* [signal@Gio.DBusProxy::g-signal] signals
|
||||
* are also emitted on the `GDBusObjectManagerClient` instance managing these
|
||||
* objects. The signals emitted are
|
||||
* #GDBusObjectManager::interface-added,
|
||||
* #GDBusObjectManager::interface-removed,
|
||||
* #GDBusObjectManagerClient::interface-proxy-properties-changed and
|
||||
* #GDBusObjectManagerClient::interface-proxy-signal.
|
||||
* [signal@Gio.DBusObjectManager::interface-added],
|
||||
* [signal@Gio.DBusObjectManager::interface-removed],
|
||||
* [signal@Gio.DBusObjectManagerClient::interface-proxy-properties-changed] and
|
||||
* [signal@Gio.DBusObjectManagerClient::interface-proxy-signal].
|
||||
*
|
||||
* Note that all callbacks and signals are emitted in the
|
||||
* [thread-default main context][g-main-context-push-thread-default]
|
||||
* that the #GDBusObjectManagerClient object was constructed
|
||||
* in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects
|
||||
* originating from the #GDBusObjectManagerClient object will be created in
|
||||
* thread-default main context (see
|
||||
* [method@GLib.MainContext.push_thread_default]) that the
|
||||
* `GDBusObjectManagerClient` object was constructed in. Additionally, the
|
||||
* [class@Gio.DBusObjectProxy] and [class@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.
|
||||
*
|
||||
* Since: 2.30
|
||||
*/
|
||||
|
||||
struct _GDBusObjectManagerClientPrivate
|
||||
|
||||
@ -37,14 +37,6 @@ G_BEGIN_DECLS
|
||||
typedef struct _GDBusObjectManagerClientClass GDBusObjectManagerClientClass;
|
||||
typedef struct _GDBusObjectManagerClientPrivate GDBusObjectManagerClientPrivate;
|
||||
|
||||
/**
|
||||
* GDBusObjectManagerClient:
|
||||
*
|
||||
* The #GDBusObjectManagerClient structure contains private data and should
|
||||
* only be accessed using the provided API.
|
||||
*
|
||||
* Since: 2.30
|
||||
*/
|
||||
struct _GDBusObjectManagerClient
|
||||
{
|
||||
/*< private >*/
|
||||
|
||||
Loading…
Reference in New Issue
Block a user