Update glib introspection data

This is based on f61187428eaff51b5aae121df1615e02117ef44f.

1 files changed, 121 insertions, 3 deletions

diff --git a/gir/gio-2.0.c b/gir/gio-2.0.c
index badf8025..1631e112 100644
--- a/gir/gio-2.0.c
+++ b/gir/gio-2.0.c
@@ -6458,6 +6458,10 @@
  * default. Application code may connect to the #GObject::notify signal for it
  * to control other parts of its debug infrastructure as necessary.
  *
+ * If your application or service is using the default GLib log writer function,
+ * creating one of the built-in implementations of #GDebugController should be
+ * all that’s needed to dynamically enable or disable debug output.
+ *
  * Since: 2.72
  */
 
@@ -6476,6 +6480,105 @@
  * #GDebugControllerDBus:connection once it’s initialized. The 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
+ * output in this process. Remote processes calling
+ * `org.gtk.Debugging.SetDebugEnabled()` will affect the value of
+ * #GDebugController:debug-enabled and, by default, g_log_get_debug_enabled().
+ * default.
+ *
+ * By default, all processes will be able to call `SetDebugEnabled()`. If this
+ * process is privileged, or might expose sensitive information in its debug
+ * output, you may want to restrict the ability to enable debug output to
+ * privileged users or processes.
+ *
+ * One option is to install a D-Bus security policy which restricts access to
+ * `SetDebugEnabled()`, installing something like the following in
+ * `$datadir/dbus-1/system.d/`:
+ * |[<!-- language="XML" -->
+ * <?xml version="1.0"?> <!--*-nxml-*-->
+ * <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
+ *      "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
+ * <busconfig>
+ *   <policy user="root">
+ *     <allow send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/>
+ *   </policy>
+ *   <policy context="default">
+ *     <deny send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/>
+ *   </policy>
+ * </busconfig>
+ * ]|
+ *
+ * This will prevent the `SetDebugEnabled()` method from being called by all
+ * except root. It will not prevent the `DebugEnabled` property from being read,
+ * as it’s accessed through the `org.freedesktop.DBus.Properties` interface.
+ *
+ * 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,
+ * connect to the #GDebugControllerDBus::authorize signal and query polkit in
+ * it:
+ * |[<!-- language="C" -->
+ *   g_autoptr(GError) child_error = NULL;
+ *   g_autoptr(GDBusConnection) connection = g_bus_get_sync (G_BUS_TYPE_SYSTEM, NULL, NULL);
+ *   gulong debug_controller_authorize_id = 0;
+ *
+ *   // Set up the debug controller.
+ *   debug_controller = G_DEBUG_CONTROLLER (g_debug_controller_dbus_new (priv->connection, NULL, &child_error));
+ *   if (debug_controller == NULL)
+ *     {
+ *       g_error ("Could not register debug controller on bus: %s"),
+ *                child_error->message);
+ *     }
+ *
+ *   debug_controller_authorize_id = g_signal_connect (debug_controller,
+ *                                                     "authorize",
+ *                                                     G_CALLBACK (debug_controller_authorize_cb),
+ *                                                     self);
+ *
+ *   static gboolean
+ *   debug_controller_authorize_cb (GDebugControllerDBus  *debug_controller,
+ *                                  GDBusMethodInvocation *invocation,
+ *                                  gpointer               user_data)
+ *   {
+ *     g_autoptr(PolkitAuthority) authority = NULL;
+ *     g_autoptr(PolkitSubject) subject = NULL;
+ *     g_autoptr(PolkitAuthorizationResult) auth_result = NULL;
+ *     g_autoptr(GError) local_error = NULL;
+ *     GDBusMessage *message;
+ *     GDBusMessageFlags message_flags;
+ *     PolkitCheckAuthorizationFlags flags = POLKIT_CHECK_AUTHORIZATION_FLAGS_NONE;
+ *
+ *     message = g_dbus_method_invocation_get_message (invocation);
+ *     message_flags = g_dbus_message_get_flags (message);
+ *
+ *     authority = polkit_authority_get_sync (NULL, &local_error);
+ *     if (authority == NULL)
+ *       {
+ *         g_warning ("Failed to get polkit authority: %s", local_error->message);
+ *         return FALSE;
+ *       }
+ *
+ *     if (message_flags & G_DBUS_MESSAGE_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION)
+ *       flags |= POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION;
+ *
+ *     subject = polkit_system_bus_name_new (g_dbus_method_invocation_get_sender (invocation));
+ *
+ *     auth_result = polkit_authority_check_authorization_sync (authority,
+ *                                                              subject,
+ *                                                              "com.example.MyService.set-debug-enabled",
+ *                                                              NULL,
+ *                                                              flags,
+ *                                                              NULL,
+ *                                                              &local_error);
+ *     if (auth_result == NULL)
+ *       {
+ *         g_warning ("Failed to get check polkit authorization: %s", local_error->message);
+ *         return FALSE;
+ *       }
+ *
+ *     return polkit_authorization_result_get_is_authorized (auth_result);
+ *   }
+ * ]|
+ *
  * Since: 2.72
  */
 
@@ -20261,11 +20364,26 @@
 
 
 /**
- * g_debug_controller_dup_default:
+ * g_debug_controller_dbus_stop:
+ * @self: a #GDebugControllerDBus
+ *
+ * Stop the debug controller, unregistering its object from the bus.
+ *
+ * Any pending method calls to the object will complete successfully, but new
+ * ones will return an error. This method will block until all pending
+ * #GDebugControllerDBus::authorize signals have been handled. This is expected
+ * to not take long, as it will just be waiting for threads to join. If any
+ * #GDebugControllerDBus::authorize signal handlers are still executing in other
+ * threads, this will block until after they have returned.
+ *
+ * This method will be called automatically when the final reference to the
+ * #GDebugControllerDBus is dropped. You may want to call it explicitly to know
+ * when the controller has been fully removed from the bus, or to break
+ * reference count cycles.
  *
- * Gets a reference to the default #GDebugController for the system.
+ * Calling this method from within a #GDebugControllerDBus::authorize signal
+ * handler will cause a deadlock and must not be done.
  *
- * Returns: (not nullable) (transfer full): a new reference to the default #GDebugController
  * Since: 2.72
  */