diff options
author | Colin Walters <walters@verbum.org> | 2005-06-26 17:02:09 +0000 |
---|---|---|
committer | Colin Walters <walters@verbum.org> | 2005-06-26 17:02:09 +0000 |
commit | df901b528bc1e1edd96e9e91b94c9c9b795b8ffd (patch) | |
tree | f455e436a057d8525edb4d29067674eb781331da /doc/dbus-tutorial.xml | |
parent | c904e1e3a695f8f15f098d9316ead6f0db637780 (diff) |
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.
Diffstat (limited to 'doc/dbus-tutorial.xml')
-rw-r--r-- | doc/dbus-tutorial.xml | 102 |
1 files changed, 68 insertions, 34 deletions
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, &arr, G_TYPE_INVALID)) { - g_printerr ("Failed to complete Foobar: %s\n", - error->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, &ret, G_TYPE_INVALID)) { - g_printerr ("Failed to complete HashSize: %s\n", - error->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, &strret, G_TYPE_INVALID)) { - g_printerr ("Failed to complete GetStuff: %s\n", - error->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->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, &strs, G_TYPE_INVALID)) { - g_printerr ("Failed to complete GetStrs: %s\n", - error->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, &val, G_TYPE_INVALID, G_TYPE_INVALID)) { - g_printerr ("Failed to complete SendVariant: %s\n", - error->message); - g_error_free (error); - exit (1); + /* Handle error */ } g_assert (ret == 2); g_value_unset (&val); @@ -1003,10 +1040,7 @@ main (int argc, char **argv) if (!dbus_g_proxy_call (proxy, "GetVariant", &error, G_TYPE_INVALID, G_TYPE_VALUE, &val, G_TYPE_INVALID)) { - g_printerr ("Failed to complete GetVariant: %s\n", - error->message); - g_error_free (error); - exit (1); + /* Handle error */ } if (G_VALUE_TYPE (&val) == G_TYPE_STRING) printf ("%s\n", g_value_get_string (&val)); |