Add more docs for GDBusServer.

2 files changed, 87 insertions, 26 deletions

diff --git a/gdbus/example-peer.c b/gdbus/example-peer.c
index 3c02c4e..9640cfe 100644
--- a/gdbus/example-peer.c
+++ b/gdbus/example-peer.c
@@ -1,3 +1,72 @@
+/*
+
+Usage examples (modulo addresses / credentials).
+
+UNIX domain socket transport:
+
+ Server:
+   $ ./example-peer --server --address unix:abstract=myaddr
+   Server is listening at: unix:abstract=myaddr
+   Client connected.
+   Peer credentials: GCredentials:unix-user=500,unix-group=500,unix-process=13378
+   Negotiated capabilities: unix-fd-passing=1
+   Client said: Hey, it's 1273093080 already!
+
+ Client:
+   $ ./example-peer --address unix:abstract=myaddr
+   Connected.
+   Negotiated capabilities: unix-fd-passing=1
+   Server said: You said 'Hey, it's 1273093080 already!'. KTHXBYE!
+
+Nonce-secured TCP transport on the same host:
+
+ Server:
+   $ ./example-peer --server --address nonce-tcp:
+   Server is listening at: nonce-tcp:host=localhost,port=43077,noncefile=/tmp/gdbus-nonce-file-X1ZNCV
+   Client connected.
+   Peer credentials: (no credentials received)
+   Negotiated capabilities: unix-fd-passing=0
+   Client said: Hey, it's 1273093206 already!
+
+ Client:
+   $ ./example-peer -address nonce-tcp:host=localhost,port=43077,noncefile=/tmp/gdbus-nonce-file-X1ZNCV
+   Connected.
+   Negotiated capabilities: unix-fd-passing=0
+   Server said: You said 'Hey, it's 1273093206 already!'. KTHXBYE!
+
+TCP transport on two different hosts with a shared home directory:
+
+ Server:
+   host1 $ ./example-peer --server --address tcp:host=0.0.0.0
+   Server is listening at: tcp:host=0.0.0.0,port=46314
+   Client connected.
+   Peer credentials: (no credentials received)
+   Negotiated capabilities: unix-fd-passing=0
+   Client said: Hey, it's 1273093337 already!
+
+ Client:
+   host2 $ ./example-peer -a tcp:host=host1,port=46314
+   Connected.
+   Negotiated capabilities: unix-fd-passing=0
+   Server said: You said 'Hey, it's 1273093337 already!'. KTHXBYE!
+
+TCP transport on two different hosts without authentication:
+
+ Server:
+   host1 $ ./example-peer --server --address tcp:host=0.0.0.0 --allow-anonymous
+   Server is listening at: tcp:host=0.0.0.0,port=59556
+   Client connected.
+   Peer credentials: (no credentials received)
+   Negotiated capabilities: unix-fd-passing=0
+   Client said: Hey, it's 1273093652 already!
+
+ Client:
+   host2 $ ./example-peer -a tcp:host=host1,port=59556
+   Connected.
+   Negotiated capabilities: unix-fd-passing=0
+   Server said: You said 'Hey, it's 1273093652 already!'. KTHXBYE!
+
+ */
 
 #include <gdbus/gdbus.h>
 #include <stdlib.h>
@@ -14,7 +83,6 @@ static const gchar introspection_xml[] =
   "      <arg type='s' name='greeting' direction='in'/>"
   "      <arg type='s' name='response' direction='out'/>"
   "    </method>"
-  "    <method name='GimmeStdout'/>"
   "  </interface>"
   "</node>";
 
@@ -53,30 +121,6 @@ static const GDBusInterfaceVTable interface_vtable =
 
 /* ---------------------------------------------------------------------------------------------------- */
 
-static gchar *
-credentials_to_string (GCredentials *credentials)
-{
-  GString *s;
-  s = g_string_new (NULL);
-  if (g_credentials_has_unix_user (credentials))
-    {
-      g_string_append_printf (s, "unix_user=%d", (gint) g_credentials_get_unix_user (credentials));
-    }
-  if (g_credentials_has_unix_group (credentials))
-    {
-      if (s->len > 0)
-        g_string_append_c (s, ',');
-      g_string_append_printf (s, "unix_group=%d", (gint) g_credentials_get_unix_group (credentials));
-    }
-  if (g_credentials_has_unix_process (credentials))
-    {
-      if (s->len > 0)
-        g_string_append_c (s, ',');
-      g_string_append_printf (s, "unix_process=%d", (gint) g_credentials_get_unix_process (credentials));
-    }
-  return g_string_free (s, FALSE);
-}
-
 static void
 on_new_connection (GDBusServer *server,
                    GDBusConnection *connection,
@@ -90,7 +134,7 @@ on_new_connection (GDBusServer *server,
   if (credentials == NULL)
     s = g_strdup ("(no credentials received)");
   else
-    s = credentials_to_string (credentials);
+    s = g_credentials_to_string (credentials);
 
 
   g_print ("Client connected.\n"
diff --git a/gdbus/gdbusserver.c b/gdbus/gdbusserver.c
index 922e3c4..37b85c4 100644
--- a/gdbus/gdbusserver.c
+++ b/gdbus/gdbusserver.c
@@ -48,6 +48,8 @@
  *
  * #GDBusServer is a helper for listening to and accepting D-Bus
  * connections.
+ *
+ * <example id="gdbus-peer-to-peer"><title>D-Bus peer-to-peer example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gdbus/example-peer.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example>
  */
 
 struct _GDBusServerPrivate
@@ -389,6 +391,9 @@ on_run (GSocketService    *service,
  * The returned #GDBusServer isn't active - you have to start it with
  * g_dbus_server_start().
  *
+ * See <xref linkend="gdbus-peer-to-peer"/> for how #GDBusServer can
+ * be used.
+ *
  * This is a synchronous failable constructor. See
  * g_dbus_server_new() for the asynchronous version.
  *
@@ -492,6 +497,12 @@ g_dbus_server_is_active (GDBusServer *server)
   return server->priv->active;
 }
 
+/**
+ * g_dbus_server_start:
+ * @server: A #GDBusServer.
+ *
+ * Starts @server.
+ */
 void
 g_dbus_server_start (GDBusServer *server)
 {
@@ -505,6 +516,12 @@ g_dbus_server_start (GDBusServer *server)
   g_object_notify (G_OBJECT (server), "active");
 }
 
+/**
+ * g_dbus_server_stop:
+ * @server: A #GDBusServer.
+ *
+ * Stops @server.
+ */
 void
 g_dbus_server_stop (GDBusServer *server)
 {