IDL language

[David Zeuthen]

On Fri, 2009-05-08 at 17:32 +0100, Simon McVittie wrote:
> 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.

Not sure exactly what you want me to do. It sounds more like this is
stuff that should go into a "IDL programming guide" as how people should
name their methods/properties/signals, no? I mean, binding generators
are free to do whatever they want.

(Otherwise, please clarify...)

> 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 :-)

Sure, we can change that. It was just meant as an easier way of
debugging things on the wire. But you are right insofar that it's not
strictly needed and it's actually just bloat. I'll remove it so a
dynamic_struct is to be marshalled as just a{sv}.

> >  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.

I will have to look into the GObject sources to check if there's really
an assertion going on here (I don't think there is (but ICBW) and if
there is... there should maybe be a way to allow other values with some
special API. I don't know.)

Either way, GLib-specifics aside, I think it's useful to describe the
intent that an enumeration is intended for flags and one is intended for
just.. values. Then again bindings can do whatever they want.

     David