luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-01-11 23:16:14 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Move the GDBusObjectManagerClient SECTION

Browse Source 
Move it to the struct docs.

Signed-off-by: Philip Withnall <philip@tecnocode.co.uk>

Helps: #3037
This commit is contained in:
Philip Withnall 2023-10-25 13:10:10 +01:00
parent 264ebbbb2b
commit 99e25e74ef
2 changed files with 57 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
gio/gdbusobjectmanagerclient.c
View File

@ -43,85 +43,88 @@
#include "gmarshal-internal.h" #include "gmarshal-internal.h"
/** /**
* SECTION:gdbusobjectmanagerclient * GDBusObjectManagerClient:
* @short_description: Client-side object manager
* @include: gio/gio.h
* *
* #GDBusObjectManagerClient is used to create, monitor and delete object * `GDBusObjectManagerClient` is used to create, monitor and delete object
* proxies for remote objects exported by a #GDBusObjectManagerServer (or any * proxies for remote objects exported by a [class@Gio.DBusObjectManagerServer]
* code implementing the * (or any code implementing the
* [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager) * [org.freedesktop.DBus.ObjectManager](http://dbus.freedesktop.org/doc/dbus-specification.html#standard-interfaces-objectmanager)
* interface). * interface).
* *
* Once an instance of this type has been created, you can connect to * Once an instance of this type has been created, you can connect to
* the #GDBusObjectManager::object-added and * the [signal@Gio.DBusObjectManager::object-added] and
* #GDBusObjectManager::object-removed signals and inspect the * [signal@Gio.DBusObjectManager::object-removed signals] and inspect the
* #GDBusObjectProxy objects returned by * [class@Gio.DBusObjectProxy] objects returned by
* g_dbus_object_manager_get_objects(). * [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 * object construction time, the default behavior is to request the
* message bus to launch an owner for the name. This behavior can be * 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 * 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 * 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 * 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 * 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 * there will be no object proxies
* (e.g. g_dbus_object_manager_get_objects() returns the empty list) and * (e.g. [method@Gio.DBusObjectManager.get_objects] returns the empty list) and
* the #GDBusObjectManagerClient:name-owner property is %NULL. * the [property@Gio.DBusObjectManagerClient:name-owner] property is `NULL`.
* *
* The owner of the requested name can come and go (for example * The owner of the requested name can come and go (for example
* consider a system service being restarted) – #GDBusObjectManagerClient * consider a system service being restarted) – `GDBusObjectManagerClient`
* handles this case too; simply connect to the #GObject::notify * handles this case too; simply connect to the [signal@GObject.Object::notify]
* signal to watch for changes on the #GDBusObjectManagerClient:name-owner * signal to watch for changes on the
* property. When the name owner vanishes, the behavior is that * [property@Gio.DBusObjectManagerClient:name-owner] property. When the name
* #GDBusObjectManagerClient:name-owner is set to %NULL (this includes * owner vanishes, the behavior is that
* emission of the #GObject::notify signal) and then * [property@Gio.DBusObjectManagerClient:name-owner] is set to `NULL` (this
* #GDBusObjectManager::object-removed signals are synthesized * 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 * for all currently existing object proxies. Since
* #GDBusObjectManagerClient:name-owner is %NULL when this happens, you can * [property@Gio.DBusObjectManagerClient:name-owner] is `NULL` when this
* use this information to disambiguate a synthesized signal from a * happens, you can use this information to disambiguate a synthesized signal
* genuine signal caused by object removal on the remote * from a genuine signal caused by object removal on the remote
* #GDBusObjectManager. Similarly, when a new name owner appears, * [iface@Gio.DBusObjectManager]. Similarly, when a new name owner appears,
* #GDBusObjectManager::object-added signals are synthesized * [signal@Gio.DBusObjectManager::object-added] signals are synthesized
* while #GDBusObjectManagerClient:name-owner is still %NULL. Only when all * while [property@Gio.DBusObjectManagerClient:name-owner] is still `NULL`. Only
* object proxies have been added, the #GDBusObjectManagerClient:name-owner * when all object proxies have been added, the
* is set to the new name owner (this includes emission of the * [property@Gio.DBusObjectManagerClient:name-owner] is set to the new name
* #GObject::notify signal). Furthermore, you are guaranteed that * owner (this includes emission of the [signal@GObject.Object::notify] signal).
* #GDBusObjectManagerClient:name-owner will alternate between a name owner * Furthermore, you are guaranteed that
* (e.g. `:1.42`) and %NULL even in the case where * [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 * the name of interest is atomically replaced
* *
* Ultimately, #GDBusObjectManagerClient is used to obtain #GDBusProxy * Ultimately, `GDBusObjectManagerClient` is used to obtain
* instances. All signals (including the * [class@Gio.DBusProxy] instances. All signals (including the
* org.freedesktop.DBus.Properties::PropertiesChanged signal) * `org.freedesktop.DBus.Properties::PropertiesChanged` signal)
* delivered to #GDBusProxy instances are guaranteed to originate * delivered to [class@Gio.DBusProxy] instances are guaranteed to originate
* from the name owner. This guarantee along with the behavior * from the name owner. This guarantee along with the behavior
* described above, means that certain race conditions including the * described above, means that certain race conditions including the
* "half the proxy is from the old owner and the other half is from * “half the proxy is from the old owner and the other half is from
* the new owner" problem cannot happen. * the new owner” problem cannot happen.
* *
* To avoid having the application connect to signals on the returned * To avoid having the application connect to signals on the returned
* #GDBusObjectProxy and #GDBusProxy objects, the * [class@Gio.DBusObjectProxy] and [class@Gio.DBusProxy] objects, the
* #GDBusObject::interface-added, * [signal@Gio.DBusObject::interface-added],
* #GDBusObject::interface-removed, * [signal@Gio.DBusObject::interface-removed],
* #GDBusProxy::g-properties-changed and * [signal@Gio.DBusProxy::g-properties-changed] and
* #GDBusProxy::g-signal signals * [signal@Gio.DBusProxy::g-signal] signals
* are also emitted on the #GDBusObjectManagerClient instance managing these * are also emitted on the `GDBusObjectManagerClient` instance managing these
* objects. The signals emitted are * objects. The signals emitted are
* #GDBusObjectManager::interface-added, * [signal@Gio.DBusObjectManager::interface-added],
* #GDBusObjectManager::interface-removed, * [signal@Gio.DBusObjectManager::interface-removed],
* #GDBusObjectManagerClient::interface-proxy-properties-changed and * [signal@Gio.DBusObjectManagerClient::interface-proxy-properties-changed] and
* #GDBusObjectManagerClient::interface-proxy-signal. * [signal@Gio.DBusObjectManagerClient::interface-proxy-signal].
* *
* Note that all callbacks and signals are emitted in the * Note that all callbacks and signals are emitted in the
* [thread-default main context][g-main-context-push-thread-default] * thread-default main context (see
* that the #GDBusObjectManagerClient object was constructed * [method@GLib.MainContext.push_thread_default]) that the
* in. Additionally, the #GDBusObjectProxy and #GDBusProxy objects * `GDBusObjectManagerClient` object was constructed in. Additionally, the
* originating from the #GDBusObjectManagerClient object will be created in * [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 * the same context and, consequently, will deliver signals in the
* same main loop. * same main loop.
*
* Since: 2.30
*/ */
struct _GDBusObjectManagerClientPrivate struct _GDBusObjectManagerClientPrivate

8
gio/gdbusobjectmanagerclient.h
View File

@ -37,14 +37,6 @@ G_BEGIN_DECLS
typedef struct _GDBusObjectManagerClientClass GDBusObjectManagerClientClass; typedef struct _GDBusObjectManagerClientClass GDBusObjectManagerClientClass;
typedef struct _GDBusObjectManagerClientPrivate GDBusObjectManagerClientPrivate; 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 struct _GDBusObjectManagerClient
{ {
/*< private >*/ /*< private >*/