diff --git a/gio/gdbusobjectmanagerclient.c b/gio/gdbusobjectmanagerclient.c index b6b3b212c..ea6ec9093 100644 --- a/gio/gdbusobjectmanagerclient.c +++ b/gio/gdbusobjectmanagerclient.c @@ -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 diff --git a/gio/gdbusobjectmanagerclient.h b/gio/gdbusobjectmanagerclient.h index 2ebeedc02..f02c69389 100644 --- a/gio/gdbusobjectmanagerclient.h +++ b/gio/gdbusobjectmanagerclient.h @@ -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 >*/