[Telepathy] Change proposal to Connection.Interface.Capabilities

[Robert McQueen]

Daniel d'Andrada Tenório de Carvalho wrote:
> Hi all,

Hi,

> I agree with you when it comes to ease of implementation. It's a pain to
> handle complex D-Bus signatures in C, for instance. What I'm trying to
> do with that change proposal is to make Telepathy a little more
> consistent, more coherent.

I agree, consistency is important[1], but I'm not sure it's more
important than ease of use.

> What are we standing for? Simple signatures compromising correctness to
> favor ease of implementation or the opposite instead? Because,
> currently, Telepathy stands for both of them (or none, depending on your
> point of view).

I don't think that the choice here is a trade off between correctness
and simplicity - the Capabilities interface is just as correct in terms
of the information it transmits. It's just a different representation
which is far easier to digest. After seeing implementations of the
Presence interface inflict pain on myself and others, I took the
opportunity to flatten the Capabilities interface before anyone started
using it. :D

In reality, having a complicated nested data structure for some slightly
specious perceived semantic superiority is a big waste of effort all
round, because it makes for more code and bigger messages. On both the
sending and the receiving side, you're going to have different data
structures which you want to read from and write to, and the more
complex the intermediate format, the more painful it is for everyone.

> Connection.Interface.Capabilities interface seems to be on the "ease of
> use" side. But let's take a look at, for instance, PresenceUpdate signal
> from Connection.Interface.Presence interface. It has this intimidating
> (or beautiful) signature:
> 
> a{u(ua{sa{sv}})}
> 
> This is clearly not easy to construct, handle or iterate over. If we
> were to favor the "ease of use" side, this signature should be
> simplified (following the Capabilities interface style) to:
> 
> a(uusa{sv})

As evidenced by my change to the capabilities stuff, I'd far prefer this
"flatter" structure. Although actually, for semantic equivalence it'd
need to be a(uua(sa{sv})), but it's the dicts that make it crappy to
deal with unless the keys are well-known, which they are in the case of
the arguments to a particular status.

If we were changing it I might also instead refer to each status with a
number, to require people to call GetStatuses so they didn't rely on
fragile/protocol-specific naming-stuff-by-string behaviour, which is
another confusion I've seen. You're meant to use the presence type
numbers to understand what an unknown presence means in broad terms
(away, here, invisible, not here), and you're meant to use the string
names *if you know what they mean* to set a more specific thing (out to
lunch, busy, knitting, whatever).

What else do people think about it, if we're pondering changing it? :)

> So, Connection.Interface.Capabilities is on the "ease of use" side and
> Connection.Interface.Presence is on the "correctness" side.
> 
> What side are we taking?

I don't think that it's a choice between correctness or not. Both
approaches are equivalent in their semantic meaning. If we accept that,
then it's just a choice about ease of use and consistency. I'd say in
the case of Capabilities, ease of use is more important than consistency
with the Presence interface, because the presence interface sucks.

But on that note, presence would be easier *and* more consistent if I
just changed it now to match the Capabilities-style thing. Certainly the
Presence interface has drawn the most questions, confusion & awkward
code[2] than any other part of the Telepathy spec, and that's a valid
reason alone to consider changing it. How many people on the list would
kill me if I just changed it in the next spec release? :D

> Hope you guys take some time to think over it.
> 
> Regards,
> Daniel d'Andrada T. de Carvalho - INdT

Regards,
Rob

[1]: Most embarrasingly we somehow managed to end up with two enums
which represent connectivity states, connection status goes 0-1-2 =
connected-connecting-disconnected, but media stream state goes in the
opposite direction. I'd rather change connection to the "right"
(increasing number => increasing connectivity) way round, but I fear
people would kill me. Would you? :D

[2]: And aggression...
static void
setstatuses_foreach (gpointer key, gpointer value, gpointer user_data)
{
  struct _i_hate_g_hash_table_foreach *data =
    (struct _i_hate_g_hash_table_foreach*) user_data;
... :D

-- 
Robert McQueen
Director, Collabora Ltd.