Convert remaining examples to links

[platform/upstream/glib.git] / gio / gdbusauthobserver.c

diff --git a/gio/gdbusauthobserver.c b/gio/gdbusauthobserver.c
index a55e13d..cd463b0 100644 (file)
--- a/gio/gdbusauthobserver.c
+++ b/gio/gdbusauthobserver.c
@@ -13,9 +13,7 @@
  * Lesser General Public License for more details.
  *
  * You should have received a copy of the GNU Lesser General
- * Public License along with this library; if not, write to the
- * Free Software Foundation, Inc., 59 Temple Place, Suite 330,
- * Boston, MA 02111-1307, USA.
+ * Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  *
  * Author: David Zeuthen <davidz@redhat.com>
  */
@@ -41,10 +39,13 @@
  * signals you are interested in. Note that new signals may be added
  * in the future
  *
+ * ## Controlling Authentication # {#auth-observer}
+ *
  * For example, if you only want to allow D-Bus connections from
  * processes owned by the same uid as the server, you would use a
  * signal handler like the following:
- * <example id="auth-observer"><title>Controlling Authentication</title><programlisting>
+ * 
+ * |[
  * static gboolean
  * on_authorize_authenticated_peer (GDBusAuthObserver *observer,
  *                                  GIOStream         *stream,
@@ -65,7 +66,7 @@
  *
  *   return authorized;
  * }
- * </programlisting></example>
+ * ]|
  */
 
 typedef struct _GDBusAuthObserverClass GDBusAuthObserverClass;
@@ -89,6 +90,9 @@ struct _GDBusAuthObserverClass
   gboolean (*authorize_authenticated_peer) (GDBusAuthObserver  *observer,
                                             GIOStream          *stream,
                                             GCredentials       *credentials);
+
+  gboolean (*allow_mechanism) (GDBusAuthObserver  *observer,
+                               const gchar        *mechanism);
 };
 
 /**
@@ -107,6 +111,7 @@ struct _GDBusAuthObserver
 enum
 {
   AUTHORIZE_AUTHENTICATED_PEER_SIGNAL,
+  ALLOW_MECHANISM_SIGNAL,
   LAST_SIGNAL,
 };
 
@@ -130,6 +135,13 @@ g_dbus_auth_observer_authorize_authenticated_peer_real (GDBusAuthObserver  *obse
   return TRUE;
 }
 
+static gboolean
+g_dbus_auth_observer_allow_mechanism_real (GDBusAuthObserver  *observer,
+                                           const gchar        *mechanism)
+{
+  return TRUE;
+}
+
 static void
 g_dbus_auth_observer_class_init (GDBusAuthObserverClass *klass)
 {
@@ -138,6 +150,7 @@ g_dbus_auth_observer_class_init (GDBusAuthObserverClass *klass)
   gobject_class->finalize = g_dbus_auth_observer_finalize;
 
   klass->authorize_authenticated_peer = g_dbus_auth_observer_authorize_authenticated_peer_real;
+  klass->allow_mechanism = g_dbus_auth_observer_allow_mechanism_real;
 
   /**
    * GDBusAuthObserver::authorize-authenticated-peer:
@@ -164,6 +177,29 @@ g_dbus_auth_observer_class_init (GDBusAuthObserverClass *klass)
                   2,
                   G_TYPE_IO_STREAM,
                   G_TYPE_CREDENTIALS);
+
+  /**
+   * GDBusAuthObserver::allow-mechanism:
+   * @observer: The #GDBusAuthObserver emitting the signal.
+   * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
+   *
+   * Emitted to check if @mechanism is allowed to be used.
+   *
+   * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
+   *
+   * Since: 2.34
+   */
+  signals[ALLOW_MECHANISM_SIGNAL] =
+    g_signal_new ("allow-mechanism",
+                  G_TYPE_DBUS_AUTH_OBSERVER,
+                  G_SIGNAL_RUN_LAST,
+                  G_STRUCT_OFFSET (GDBusAuthObserverClass, allow_mechanism),
+                  _g_signal_accumulator_false_handled,
+                  NULL, /* accu_data */
+                  NULL,
+                  G_TYPE_BOOLEAN,
+                  1,
+                  G_TYPE_STRING);
 }
 
 static void
@@ -216,3 +252,30 @@ g_dbus_auth_observer_authorize_authenticated_peer (GDBusAuthObserver  *observer,
                  &denied);
   return denied;
 }
+
+/**
+ * g_dbus_auth_observer_allow_mechanism:
+ * @observer: A #GDBusAuthObserver.
+ * @mechanism: The name of the mechanism, e.g. `DBUS_COOKIE_SHA1`.
+ *
+ * Emits the #GDBusAuthObserver::allow-mechanism signal on @observer.
+ *
+ * Returns: %TRUE if @mechanism can be used to authenticate the other peer, %FALSE if not.
+ *
+ * Since: 2.34
+ */
+gboolean
+g_dbus_auth_observer_allow_mechanism (GDBusAuthObserver  *observer,
+                                      const gchar        *mechanism)
+{
+  gboolean ret;
+
+  ret = FALSE;
+  g_signal_emit (observer,
+                 signals[ALLOW_MECHANISM_SIGNAL],
+                 0,
+                 mechanism,
+                 &ret);
+  return ret;
+}
+