GNOME Bugzilla – Bug 646425
GDBusServer docs should mention g_bus_own_name().
Last modified: 2011-04-27 03:21:23 UTC
I guess that the GDBusServer documentation http://library.gnome.org/devel/gio/unstable/GDBusServer.html#GDBusServer.description should mention g_bus_own_name(), which is apparently the correct way to provide a D-Bus service on a standard bus such as the session bus or the system bus. As far as I can tell, GDBusServer cannot be used to create a service on an existing bus, though its name makes people think that it's a starting point for creating services. Maybe it creates a new bus - if so, that might be worth mentioning. Maybe a "server" provides a "bus", while a "service" provides an "interface", but I think people can be forgiven for confusing them.
No, GDBusServer has nothing to do with message bus connections. It is only used for peer-to-peer connections. I think that's pretty clear, if not suggestions in git-format-patch(1) is more than welcome.
Created attachment 185086 [details] [review] 0001-GDBusServer-Documentation-Improvements.patch I think the confusion does exist, particularly to people who are new to D-Bus. However, please check that I've used all the correct terminology in this patch. It almost certainly contains confusion, but a correct version would be helpful to people.
Review of attachment 185086 [details] [review]: ::: gio/gdbusserver.c @@ +68,3 @@ + * will not have a bus by default, meaning that it will not provide standard + * org.freedesktop.DBus.* services such as name assignment and interface + * introspection This is fine, though I think this is better: "...own specialized communication. Note the server instance does not perform message routing or implement the org.freedesktop.DBus interface."
Hey Murray, Thanks for the patch. I agree it would be nice to add mode detail (In reply to comment #3) > Review of attachment 185086 [details] [review]: > > ::: gio/gdbusserver.c > @@ +68,3 @@ > + * will not have a bus by default, meaning that it will not provide standard > + * org.freedesktop.DBus.* services such as name assignment and interface > + * introspection > > This is fine, though I think this is better: > > "...own specialized communication. Note the server instance does not perform > message routing or implement the org.freedesktop.DBus interface." Looks good with Colin's suggested change. In particular, it's important to nuke the "will not have a bus by default" part since peer-to-peer connections are almost never associated with message bus connections. Also, introspection works just fine on peer to peer connections. Also instead of > [...] creates a new D-Bus server, allowing [...] I'd say "[...] creates a helper for accepting D-Bus connections, allowing [...]" since a GDBusServer isn't used for communication - it's just a helper for creating GDBusConnection instances. > + * To just export an object on a standard D-Bus bus such as the session or > + * system bus, you should instead use g_bus_own_name() or > + * g_bus_own_name_on_connection(). I'd say "To just export an object on a well-known name on a message bus, such as the session or system bus," and strip the g_bus_own_name_on_connection() bit.
Created attachment 185191 [details] [review] 0001-GDBusServer-Documentation-Improvements2.patch Here's an updated patch. I would just commit it but I had to resolve some contradictions in the resulting text. For instance, it can't be both a server and a helper to create a server, and I can't explain a real distinction between a "server" and something that accepts connections. So, please check one more time.
Committed with some further tweaks.