2005-06-26 Colin Walters <walters@verbum.org>

	* glib/dbus-glib.c (dbus_set_g_error): Delete.
	(dbus_g_error_set): New public function from its ashes; used by
	both service-side method implementation and GLib bindings
	internals.
	(dbus_g_error_has_name, dbus_g_error_get_name): New function.
	(_dbus_glib_test): Add some tests.

	* test/glib/test-dbus-glib.c (main): Test dbus_g_error_has_name.

	* test/glib/test-service-glib.c (my_object_throw_error): Use
	dbus_g_error_set.

	* glib/dbus-gobject.c (gerror_to_dbus_error_message): Handle
	errors thrown by dbus_g_error_set.

	* glib/dbus-gmain.c (dbus_g_bus_get): Change to dbus_g_error_set.

	* glib/dbus-gparser.c (validate_signature): Ditto.

	* glib/dbus-gproxy.c (dbus_g_proxy_new_for_name_owner)
	(dbus_g_proxy_end_call_internal): Ditto.

	* glib/Makefile.am: Generate dbus-glib-error-switch.h, which
	converts DBUS_ERROR_x to DBUS_GERROR_x.
	(libdbus_glib_1_la_SOURCES, BUILT_SOURCES, CLEANFILES): Add it.

	* doc/TODO: Remove error TODO.

	* doc/dbus-tutorial.xml: Update with documentation about error
	handling.

	* dbus/make-dbus-glib-error-enum.sh: Tighten up regexp to make
	sure we only change DBUS_ERROR to DBUS_GERROR, not all ERROR to
	GERROR.  Also add DBUS_GERROR_REMOTE_EXCEPTION.

2 files changed, 68 insertions, 36 deletions

diff --git a/doc/TODO b/doc/TODO
index 4b953bad..cfaae877 100644
--- a/doc/TODO
+++ b/doc/TODO
@@ -33,8 +33,6 @@ Important for 1.0 GLib Bindings
  - Fix TYPE_OBJECT_PATH marshalling; see:
    http://lists.freedesktop.org/archives/dbus/2005-June/002774.html
 
- - Fix errors - need to get specific error back, not UnmappedError crap
-
  - DBusGProxy doesn't emit "destroy" when it should
 
 Might as Well for 1.0
diff --git a/doc/dbus-tutorial.xml b/doc/dbus-tutorial.xml
index 304d0d70..bd6313c7 100644
--- a/doc/dbus-tutorial.xml
+++ b/doc/dbus-tutorial.xml
@@ -772,8 +772,13 @@ main (int argc, char **argv)
   if (!dbus_g_proxy_call (proxy, "ListNames", &error, G_TYPE_INVALID,
                           G_TYPE_STRV, &name_list, G_TYPE_INVALID))
     {
-      g_printerr ("Failed to complete ListNames call: %s\n",
-                  error->message);
+      /* Just do demonstrate remote exceptions versus regular GError */
+      if (error->domain == DBUS_GERROR && error->code == DBUS_GERROR_REMOTE_EXCEPTION)
+        g_printerr ("Caught remote method exception %s: %s",
+	            dbus_g_error_get_name (error),
+	            error->message);
+      else
+        g_printerr ("Error: %s\n", error->message);
       g_error_free (error);
       exit (1);
     }
@@ -830,10 +835,60 @@ main (int argc, char **argv)
       <para>
 	You may connect to signals using
 	<literal>dbus_g_proxy_add_signal</literal> and
-	<literal>dbus_g_proxy_connect_signal</literal>.  At the
-	moment, <literal>dbus_g_proxy_add_signal</literal> requires
-	the D-BUS types of the remote object; this will likely be
-	changed later.
+	<literal>dbus_g_proxy_connect_signal</literal>.  You must
+	invoke <literal>dbus_g_proxy_add_signal</literal> to specify
+	the signature of your signal handlers; you may then invoke
+	<literal>dbus_g_proxy_connect_signal</literal> multiple times.
+      </para>
+      <para>
+	Note that it will often be the case that there is no builtin
+	marshaller for the type signature of a remote signal.  In that
+	case, you must generate a marshaller yourself by using
+	<application>glib-genmarshal</application>, and then register
+	it using <literal>dbus_g_object_register_marshaller</literal>.
+      </para>
+    </sect2>
+    <sect2 id="glib-error-handling">
+      <title>Error handling and remote exceptions</title>
+      <para>
+	All of the GLib binding methods such as
+	<literal>dbus_g_proxy_end_call</literal> return a
+	<literal>GError</literal>.  This <literal>GError</literal> can
+	represent two different things:
+      <itemizedlist>
+	<listitem>
+	  <para>
+	    An internal D-BUS error, such as an out-of-memory
+	    condition, an I/O error, or a network timeout.  Errors
+	    generated by the D-BUS library itself have the domain
+	    <literal>DBUS_GERROR</literal>, and a corresponding code
+	    such as <literal>DBUS_GERROR_NO_MEMORY</literal>.  It will
+	    not be typical for applications to handle these errors
+	    specifically.
+	  </para>
+	</listitem>
+	<listitem>
+	  <para>
+	    A remote D-BUS exception, thrown by the peer, bus, or
+	    service.  D-BUS remote exceptions have both a textual
+	    "name" and a "message".  The GLib bindings store this
+	    information in the <literal>GError</literal>, but some
+	    special rules apply.
+	  </para>
+	  <para>
+	    The set error will have the domain
+	    <literal>DBUS_GERROR</literal> as above, and will also
+	    have the code
+	    <literal>DBUS_GERROR_REMOTE_EXCEPTION</literal>.  In order
+	    to access the remote exception name, you must use a
+	    special accessor, such as
+	    <literal>dbus_g_error_has_name</literal> or
+	    <literal>dbus_g_error_get_name</literal>.  The remote
+	    exception detailed message is accessible via the regular
+	    GError <literal>message</literal> member.
+	  </para>
+	</listitem>
+      </itemizedlist>
       </para>
     </sect2>
     <sect2 id="glib-more-examples">
@@ -850,10 +905,7 @@ main (int argc, char **argv)
 			  G_TYPE_INVALID,
 			  DBUS_TYPE_G_UCHAR_ARRAY, &amp;arr, G_TYPE_INVALID))
     {
-      g_printerr ("Failed to complete Foobar: %s\n",
-                  error-&gt;message);
-      g_error_free (error);
-      exit (1);
+      /* Handle error */
     }
    g_assert (arr != NULL);
    printf ("got back %u values", arr->len);
@@ -875,10 +927,7 @@ main (int argc, char **argv)
                           DBUS_TYPE_G_STRING_STRING_HASH, hash, G_TYPE_INVALID,
 			  G_TYPE_UINT, &amp;ret, G_TYPE_INVALID))
     {
-      g_printerr ("Failed to complete HashSize: %s\n",
-                  error-&gt;message);
-      g_error_free (error);
-      exit (1);
+      /* Handle error */
     }
   g_assert (ret == 2);
   g_hash_table_destroy (hash);
@@ -899,10 +948,7 @@ main (int argc, char **argv)
                           G_TYPE_STRING, &amp;strret,
 			  G_TYPE_INVALID))
     {
-      g_printerr ("Failed to complete GetStuff: %s\n",
-                  error-&gt;message);
-      g_error_free (error);
-      exit (1);
+      /* Handle error */
     }
   printf ("%s %s", boolret ? "TRUE" : "FALSE", strret);
   g_free (strret);
@@ -933,10 +979,7 @@ main (int argc, char **argv)
 			  G_TYPE_INVALID,
 			  G_TYPE_INVALID))
     {
-      g_printerr ("Failed to complete TwoStrArrays: %s\n",
-                  error-&gt;message);
-      g_error_free (error);
-      exit (1);
+      /* Handle error */
     }
    g_strfreev (strs_dynamic);
 </programlisting>
@@ -958,10 +1001,7 @@ main (int argc, char **argv)
                           G_TYPE_STRV, &amp;strs,
 			  G_TYPE_INVALID))
     {
-      g_printerr ("Failed to complete GetStrs: %s\n",
-                  error-&gt;message);
-      g_error_free (error);
-      exit (1);
+      /* Handle error */
     }
    for (strs_p = strs; *strs_p; strs_p++)
      printf ("got string: \"%s\"", *strs_p);
@@ -983,10 +1023,7 @@ main (int argc, char **argv)
                           G_TYPE_VALUE, &amp;val, G_TYPE_INVALID,
 			  G_TYPE_INVALID))
     {
-      g_printerr ("Failed to complete SendVariant: %s\n",
-                  error-&gt;message);
-      g_error_free (error);
-      exit (1);
+      /* Handle error */
     }
   g_assert (ret == 2);
   g_value_unset (&amp;val);
@@ -1003,10 +1040,7 @@ main (int argc, char **argv)
   if (!dbus_g_proxy_call (proxy, "GetVariant", &amp;error, G_TYPE_INVALID,
                           G_TYPE_VALUE, &amp;val, G_TYPE_INVALID))
     {
-      g_printerr ("Failed to complete GetVariant: %s\n",
-                  error-&gt;message);
-      g_error_free (error);
-      exit (1);
+      /* Handle error */
     }
   if (G_VALUE_TYPE (&amp;val) == G_TYPE_STRING)
     printf ("%s\n", g_value_get_string (&amp;val));