IDL language

[Simon McVittie]

If you're doing anything like this, please consider naming types and other new
constructs using Ugly_Case (camel case with underscores at word boundaries),
like Telepathy does. This makes it completely obvious how to generate all the
other naming conventions:

* javaStyle (methods in Qt/Java): lower-case until first underscore, then
  remove the underscores
* CamelCase (classes and types in most languages, methods in .NET?, D-Bus wire
  protocol): remove the underscores
* UPPER_CASE (constants in most languages): upper-case it, keep the underscores
* lower_case (methods in GObject/Python): lower-case it, keep the underscores

As a bonus, the conversion is easy to do in even the most limited text
processing languages (XSLT/XPath's translate() function is sufficient, as is
tr(1) on Unix).

The alternative is to discard information by not having explicit word
boundaries, then recover them from the case of letters using a complex
heuristic like dbus-glib does. In pratice this probably means that you'll
later have to choose between breaking ABI or remaining bug-for-bug compatible
when you find cases that your heuristic doesn't handle in the ideal way. For
instance, Telepathy's SendDTMF method comes out as send_dt_mf() in dbus-glib
(sad face!); there's a bug open about this, but changing the heuristic would
be an ABI break, so we just have to live with it.

The Telepathy spec format extensions now even require
methods/signals/properties to have a tp:name-for-bindings attribute in
Ugly_Case, specifically so we can deal with ambiguous cases like OfferDBusTube
(which we want to turn into offer_dbus_tube, using the same DBus/DBUS/dbus
convention as libdbus) and SendDTMF (which we want to turn into send_dtmf)
by spelling them out as Offer_DBus_Tube and Send_DTMF.

On Fri, 08 May 2009 at 09:36:57 -0400, David Zeuthen wrote:
>  o  There's a way to declare "dynamic structs". These are always encoded
>     as (sa{sv}) and, thus, allow you to dynamically add elements without
>     breaking the ABI on the wire. The first element of the struct MUST
>     be "dynamic_struct:org.project.NameOfDynamicStruct".

I don't see the benefit of wrapping the a{sv} in a struct to give it such a
tag. The meaning of the a{sv} passed to, for instance, Telepathy's
CreateChannel is obviously "an a{sv} with whatever keys and values are
accepted by CreateChannel" (what else could it be?).

The meanings of the keys and values should be, and indeed are, documented
alongside CreateChannel itself, ideally by reference to a named type - in this
case the a{sv} happens to be a DBus_Qualified_Property_Value_Map, a map from
namespaced property names to their values.

This requirement would also imply that this IDL cannot describe existing D-Bus
APIs like Telepathy, which seems a poor way for it to start off :-)

>  o  We allow simple annotations with a few well-known ones
> 
>       @Deprecated
>       @Deprecated("With a reason string")
>       @Version("1.2β")
>       @Since("1.2α")
>       @NoReply
>       @DocString("A documentation string")
>       @Flags (to hint that an enum is a flag enumeration cf. GEnum vs.
>               Flags)

Neither GEnum nor GFlags is actually suitable for D-Bus use, as far as I can
see, because the behaviour of these GTypes is that your process will assert
and fall over if you receive an out-of-range enum value or flag. The
specification for a particular D-Bus API should specify how out-of-range
values are to be treated (Telepathy does this explicitly for some of the newer
ones, although we haven't caught up for the whole spec yet).

(Example use case: a Telepathy connection manager follows a newer version of
telepathy-spec than your UI, and so knows about more Message_Types than you
do. You should still be able to treat the message like Message_Type_Normal
rather than crashing.)

You could interpret this as meaning that Telepathy's enums aren't "real" enums,
if you like, because we reserve the right to extend them (having said that, a
high-quality D-Bus client shouldn't be remotely crashable at all, even
by an actively malicious process on the same bus). I think they're just as
useful a concept as "real" enums, though.

    Simon