diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/TODO | 2 | ||||
| -rw-r--r-- | doc/dbus-tutorial.xml | 102 |
2 files changed, 68 insertions, 36 deletions
@@ -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, &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)); |