[glib: 4/7] GDBusAuthObserver: Document how to restrict authentication to EXTERNAL

[Philip Withnall <pwithnall src gnome org>]

commit 281a03d6034304948f5119730e4b94516ccec09f
Author: Simon McVittie <smcv collabora com>
Date:   Wed Jun 5 13:48:13 2019 +0100

    GDBusAuthObserver: Document how to restrict authentication to EXTERNAL
    
    This is simpler and more robust than DBUS_COOKIE_SHA1, which relies
    on assumptions about random numbers and a secure home directory.
    
    Signed-off-by: Simon McVittie <smcv collabora com>

 gio/gdbusauthobserver.c | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
---
diff --git a/gio/gdbusauthobserver.c b/gio/gdbusauthobserver.c
index 2cf995f0c..4590ffcae 100644
--- a/gio/gdbusauthobserver.c
+++ b/gio/gdbusauthobserver.c
@@ -39,6 +39,30 @@
  * signals you are interested in. Note that new signals may be added
  * in the future
  *
+ * ## Controlling Authentication Mechanisms
+ *
+ * By default, a #GDBusServer or server-side #GDBusConnection will allow
+ * any authentication mechanism to be used. If you only
+ * want to allow D-Bus connections with the `EXTERNAL` mechanism,
+ * which makes use of credentials passing and is the recommended
+ * mechanism for modern Unix platforms such as Linux and the BSD family,
+ * you would use a signal handler like this:
+ *
+ * |[<!-- language="C" -->
+ * static gboolean
+ * on_allow_mechanism (GDBusAuthObserver *observer,
+ *                     const gchar       *mechanism,
+ *                     gpointer           user_data)
+ * {
+ *   if (g_strcmp0 (mechanism, "EXTERNAL") == 0)
+ *     {
+ *       return TRUE;
+ *     }
+ *
+ *   return FALSE;
+ * }
+ * ]|
+ *
  * ## Controlling Authorization # {#auth-observer}
  *
  * By default, a #GDBusServer or server-side #GDBusConnection will accept