dbus/doc dbus-tutorial.xml,1.12,1.13 TODO,1.83,1.84
Colin Walters
walters at freedesktop.org
Sun Jun 26 10:02:11 PDT 2005
- Previous message: dbus/dbus make-dbus-glib-error-enum.sh, 1.2, 1.3 dbus-glib.h, 1.14,
1.15
- Next message: dbus/glib make-dbus-glib-error-switch.sh, NONE, 1.1 dbus-gproxy.c,
1.30, 1.31 dbus-gparser.c, 1.14, 1.15 dbus-gobject.c, 1.33,
1.34 dbus-gmain.c, 1.42, 1.43 dbus-glib.c, 1.5,
1.6 Makefile.am, 1.21, 1.22 .cvsignore, 1.8, 1.9
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
Update of /cvs/dbus/dbus/doc
In directory gabe:/tmp/cvs-serv5612/doc
Modified Files:
dbus-tutorial.xml TODO
Log Message:
2005-06-26 Colin Walters <walters at 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.
Index: dbus-tutorial.xml
===================================================================
RCS file: /cvs/dbus/dbus/doc/dbus-tutorial.xml,v
retrieving revision 1.12
retrieving revision 1.13
diff -u -d -r1.12 -r1.13
--- dbus-tutorial.xml 21 Jun 2005 00:30:20 -0000 1.12
+++ dbus-tutorial.xml 26 Jun 2005 17:02:09 -0000 1.13
@@ -772,8 +772,13 @@
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 @@
<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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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));
Index: TODO
===================================================================
RCS file: /cvs/dbus/dbus/doc/TODO,v
retrieving revision 1.83
retrieving revision 1.84
diff -u -d -r1.83 -r1.84
--- TODO 17 Jun 2005 14:29:48 -0000 1.83
+++ TODO 26 Jun 2005 17:02:09 -0000 1.84
@@ -33,8 +33,6 @@
- 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
- Previous message: dbus/dbus make-dbus-glib-error-enum.sh, 1.2, 1.3 dbus-glib.h, 1.14,
1.15
- Next message: dbus/glib make-dbus-glib-error-switch.sh, NONE, 1.1 dbus-gproxy.c,
1.30, 1.31 dbus-gparser.c, 1.14, 1.15 dbus-gobject.c, 1.33,
1.34 dbus-gmain.c, 1.42, 1.43 dbus-glib.c, 1.5,
1.6 Makefile.am, 1.21, 1.22 .cvsignore, 1.8, 1.9
- Messages sorted by:
[ date ]
[ thread ]
[ subject ]
[ author ]
More information about the dbus-commit
mailing list