After an evaluation, GNOME has moved from Bugzilla to GitLab. Learn more about GitLab.
No new issues can be reported in GNOME Bugzilla anymore.
To report an issue in a GNOME project, go to GNOME GitLab.
Do not go to GNOME Gitlab for: Bluefish, Doxygen, GnuCash, GStreamer, java-gnome, LDTP, NetworkManager, Tomboy.
Bug 646425 - GDBusServer docs should mention g_bus_own_name().
GDBusServer docs should mention g_bus_own_name().
Status: RESOLVED FIXED
Product: glib
Classification: Platform
Component: gdbus
2.28.x
Other Linux
: Normal normal
: ---
Assigned To: David Zeuthen (not reading bugmail)
gtkdev
Depends on:
Blocks:
 
 
Reported: 2011-04-01 10:14 UTC by Murray Cumming
Modified: 2011-04-27 03:21 UTC
See Also:
GNOME target: ---
GNOME version: ---


Attachments
0001-GDBusServer-Documentation-Improvements.patch (1.49 KB, patch)
2011-04-04 08:06 UTC, Murray Cumming
reviewed Details | Review
0001-GDBusServer-Documentation-Improvements2.patch (1.42 KB, patch)
2011-04-05 12:21 UTC, Murray Cumming
none Details | Review

Description Murray Cumming 2011-04-01 10:14:30 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.
Comment 1 David Zeuthen (not reading bugmail) 2011-04-01 14:07:19 UTC
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.
Comment 2 Murray Cumming 2011-04-04 08:06:45 UTC
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.
Comment 3 Colin Walters 2011-04-04 13:27:49 UTC
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."
Comment 4 David Zeuthen (not reading bugmail) 2011-04-04 14:24:34 UTC
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.
Comment 5 Murray Cumming 2011-04-05 12:21:14 UTC
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.
Comment 6 Matthias Clasen 2011-04-27 03:21:23 UTC
Committed with some further tweaks.