luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-08-21 08:28:53 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: Move the GDebugControllerDBus 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-23 14:37:13 +01:00
parent 0647927a65
commit 7e15d56013
2 changed files with 21 additions and 28 deletions
Download Patch File Download Diff File Expand all files Collapse all files

42
gio/gdebugcontrollerdbus.c
View File

@@ -31,35 +31,34 @@
#include "gio/gmarshal-internal.h" #include "gio/gmarshal-internal.h"
/** /**
* SECTION:gdebugcontrollerdbus * GDebugControllerDBus:
* @title: GDebugControllerDBus
* @short_description: Debugging controller D-Bus implementation
* @include: gio/gio.h
* *
* #GDebugControllerDBus is an implementation of #GDebugController which exposes * `GDebugControllerDBus` is an implementation of [iface@Gio.DebugController]
* debug settings as a D-Bus object. * which exposes debug settings as a D-Bus object.
* *
* It is a #GInitable object, and will register an object at * It is a [iface@Gio.Initable] object, and will register an object at
* `/org/gtk/Debugging` on the bus given as * `/org/gtk/Debugging` on the bus given as
* #GDebugControllerDBus:connection once it’s initialized. The object will be * [property@Gio.DebugControllerDBus:connection] once it’s initialized. The
* unregistered when the last reference to the #GDebugControllerDBus is dropped. * object will be unregistered when the last reference to the
* `GDebugControllerDBus` is dropped.
* *
* This D-Bus object can be used by remote processes to enable or disable debug * This D-Bus object can be used by remote processes to enable or disable debug
* output in this process. Remote processes calling * output in this process. Remote processes calling
* `org.gtk.Debugging.SetDebugEnabled()` will affect the value of * `org.gtk.Debugging.SetDebugEnabled()` will affect the value of
* #GDebugController:debug-enabled and, by default, g_log_get_debug_enabled(). * [property@Gio.DebugController:debug-enabled] and, by default,
* default. * [func@GLib.log_get_debug_enabled].
* *
* By default, no processes are allowed to call `SetDebugEnabled()` unless a * By default, no processes are allowed to call `SetDebugEnabled()` unless a
* #GDebugControllerDBus::authorize signal handler is installed. This is because * [signal@Gio.DebugControllerDBus::authorize] signal handler is installed. This
* the process may be privileged, or might expose sensitive information in its * is because the process may be privileged, or might expose sensitive
* debug output. You may want to restrict the ability to enable debug output to * information in its debug output. You may want to restrict the ability to
* privileged users or processes. * enable debug output to privileged users or processes.
* *
* One option is to install a D-Bus security policy which restricts access to * One option is to install a D-Bus security policy which restricts access to
* `SetDebugEnabled()`, installing something like the following in * `SetDebugEnabled()`, installing something like the following in
* `$datadir/dbus-1/system.d/`: * `$datadir/dbus-1/system.d/`:
* |[<!-- language="XML" --> *
* ```xml
* <?xml version="1.0"?> <!--*-nxml-*--> * <?xml version="1.0"?> <!--*-nxml-*-->
* <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN" * <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
* "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd"> * "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
@@ -71,7 +70,7 @@
* <deny send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/> * <deny send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/>
* </policy> * </policy>
* </busconfig> * </busconfig>
* ]| * ```
* *
* This will prevent the `SetDebugEnabled()` method from being called by all * This will prevent the `SetDebugEnabled()` method from being called by all
* except root. It will not prevent the `DebugEnabled` property from being read, * except root. It will not prevent the `DebugEnabled` property from being read,
@@ -79,9 +78,10 @@
* *
* Another option is to use polkit to allow or deny requests on a case-by-case * Another option is to use polkit to allow or deny requests on a case-by-case
* basis, allowing for the possibility of dynamic authorisation. To do this, * basis, allowing for the possibility of dynamic authorisation. To do this,
* connect to the #GDebugControllerDBus::authorize signal and query polkit in * connect to the [signal@Gio.DebugControllerDBus::authorize] signal and query
* it: * polkit in it:
* |[<!-- language="C" --> *
* ```c
* g_autoptr(GError) child_error = NULL; * g_autoptr(GError) child_error = NULL;
* g_autoptr(GDBusConnection) connection = g_bus_get_sync (G_BUS_TYPE_SYSTEM, NULL, NULL); * g_autoptr(GDBusConnection) connection = g_bus_get_sync (G_BUS_TYPE_SYSTEM, NULL, NULL);
* gulong debug_controller_authorize_id = 0; * gulong debug_controller_authorize_id = 0;
@@ -142,7 +142,7 @@
* *
* return polkit_authorization_result_get_is_authorized (auth_result); * return polkit_authorization_result_get_is_authorized (auth_result);
* } * }
* ]| * ```
* *
* Since: 2.72 * Since: 2.72
*/ */

7
gio/gdebugcontrollerdbus.h
View File

@@ -28,13 +28,6 @@
G_BEGIN_DECLS G_BEGIN_DECLS
/**
* GDebugControllerDBus:
*
* #GDebugControllerDBus is an implementation of #GDebugController over D-Bus.
*
* Since: 2.72
*/
#define G_TYPE_DEBUG_CONTROLLER_DBUS (g_debug_controller_dbus_get_type ()) #define G_TYPE_DEBUG_CONTROLLER_DBUS (g_debug_controller_dbus_get_type ())
GIO_AVAILABLE_IN_2_72 GIO_AVAILABLE_IN_2_72
G_DECLARE_DERIVABLE_TYPE (GDebugControllerDBus, g_debug_controller_dbus, G, DEBUG_CONTROLLER_DBUS, GObject) G_DECLARE_DERIVABLE_TYPE (GDebugControllerDBus, g_debug_controller_dbus, G, DEBUG_CONTROLLER_DBUS, GObject)