From: Simon McVittie Date: Thu, 20 Oct 2011 19:02:02 +0000 (+0100) Subject: GDBusConnection: document use while uninitialized as undefined behaviour X-Git-Tag: 2.31.2~182 X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=3958a9fc1ef99b474373415d5d46d596293764f6;hp=a7ea94929420cafe5189b477f24da4903bec9e49;p=platform%2Fupstream%2Fglib.git GDBusConnection: document use while uninitialized as undefined behaviour 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 Reviewed-by: David Zeuthen --- diff --git a/gio/gdbusconnection.c b/gio/gdbusconnection.c index 3bf6048..0b80020 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(). + * * D-Bus server exampleFIXME: MISSING XINCLUDE CONTENT * * D-Bus subtree exampleFIXME: MISSING XINCLUDE CONTENT