Missing arg names in introspection data

[Simon McVittie]

On Mon, 29 Jul 2019 at 14:23:38 +0200, David Henningsson wrote:
> While most services on D-Bus have decent argument names in introspection
> data, the D-Bus server itself seems to be missing these, like this:
> 
>      <signal name="NameOwnerChanged">
>        <arg type="s"/>
>        <arg type="s"/>
>        <arg type="s"/>
>      </signal>

Terminology: this layer is "the message bus" if you are talking about
implementations of the D-Bus specification in general, or "dbus-daemon"
if you are talking about the reference implementation of the message
bus. Message bus implementations other than dbus-daemon include the
independent project dbus-broker, the gdbus-daemon executable in GDBus,
and the "managed dbus-daemon" in ndesk-dbus. "D-Bus server" is a term
that is best avoided, because it sounds as though it ought to refer to
constructs like DBusServer in libdbus and GDBusServer in GDBus, and those
are considerably lower-level than a message bus.

In the reference implementation, the vtable describing dbus-daemon
methods does not actually have a concept of arguments: it only has an
"in" signature and an "out" signature, which can contain more than one
single complete type. AddServer() in the experimental Containers1 interface
is one of the more complex examples, with "in" signature "ssa{sv}a{sv}"
(4 arguments) and "out" signature "oays" (3 arguments).

It would be possible to add named arguments, but only with a
significant amount of code churn: every MessageHandler struct would need
modification, and so would bus_driver_generate_introspect_string() and
write_args_for_direction(). If this is important to you, please send a
merge request that implements it. This is not something that could happen
on the 1.12.x stable-branch, because it would break the desirable property
that our stable release updates are small enough that long-term-supported
Linux distributions are usually willing to take those releases as-is.

Signals are currently hard-coded rather than using a vtable, so it would
be relatively straightforward to add names for their arguments. Again,
please send a merge request if this is important to you.

> I auto-generate some code from introspection data

Alternatively, you could add argument names to a static copy of the
relevant introspection data included in your source package.

I would strongly recommend including a static copy of the introspection
data in your source package anyway, because if you rely on calling
`dbus-daemon --introspect` or Introspect() at build-time or at runtime,
the interface of your generated code will vary depending on the installed
version of dbus.  In particular, you will not be able to guarantee that
newer versions of your code have an interface that is backwards-compatible
with every older version.

Regards,
    smcv