diff options
| author | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2011-10-20 20:02:02 +0100 |
|---|---|---|
| committer | Simon McVittie <simon.mcvittie@collabora.co.uk> | 2011-10-21 15:46:58 +0100 |
| commit | 87b2c723f705a2976939a273df54580912103f9f (patch) | |
| tree | ff6e4b632cb4269427db522831f8a22380b2bd20 | |
| parent | 62d3e4f9af64b1a5e7c04da16ef1a6222fecd2f9 (diff) | |
GDBusConnection: document use while uninitialized as undefined behaviourglib-2-30
Bug: https://bugzilla.gnome.org/show_bug.cgi?id=661689
Bug: https://bugzilla.gnome.org/show_bug.cgi?id=662208
Signed-off-by: Simon McVittie <simon.mcvittie@collabora.co.uk>
Reviewed-by: David Zeuthen <davidz@redhat.com>
| -rw-r--r-- | gio/gdbusconnection.c | 16 |
1 files changed, 16 insertions, 0 deletions
diff --git a/gio/gdbusconnection.c b/gio/gdbusconnection.c index 608f5c854..dcba472e5 100644 --- a/gio/gdbusconnection.c +++ b/gio/gdbusconnection.c @@ -148,6 +148,22 @@ * an D-Bus client, it is often easier to use the g_bus_own_name(), * g_bus_watch_name() or g_dbus_proxy_new_for_bus() APIs. * + * Most of the ways to obtain a #GDBusConnection automatically initialize it + * (i.e. connect to D-Bus): for instance, g_dbus_connection_new() and + * g_bus_get(), and the synchronous versions of those methods, give you an + * initialized connection. Language bindings for GIO should use + * g_initable_new() or g_async_initable_new(), which also initialize the + * connection. + * + * If you construct an uninitialized #GDBusConnection, such as via + * g_object_new(), you must initialize it via g_initable_init() or + * g_async_initable_init() before using its methods or properties. Calling + * methods or accessing properties on a #GDBusConnection that has not completed + * initialization successfully is considered to be invalid, and leads to + * undefined behaviour. In particular, if initialization fails with a #GError, + * the only valid thing you can do with that #GDBusConnection is to free it + * with g_object_unref(). + * * <example id="gdbus-server"><title>D-Bus server example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-server.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> * * <example id="gdbus-subtree-server"><title>D-Bus subtree example</title><programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" parse="text" href="../../../../gio/tests/gdbus-example-subtree.c"><xi:fallback>FIXME: MISSING XINCLUDE CONTENT</xi:fallback></xi:include></programlisting></example> |