[Telepathy] Change proposal to Connection.Interface.Capabilities

[Daniel d'Andrada Tenório de Carvalho]

ext Robert McQueen wrote:
> I agree, consistency is important[1], but I'm not sure it's more
> important than ease of use.
>
>   
We can have both of them.
> 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
>
>   
"Correctness", in fact, isn't the right word. I chose it because I 
didn't find a better one at the time, but I think you guys got the idea.
> 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.
>
>   
Yeah, I vote for ease of use. I made that patch for the sake of 
coherence (or homogeneousness), not because I like it that way.

>> 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.
>
>   
I have flattened it even further to make it more like what was done with 
Capabilities, were even though a contact being able to advertise several 
channel types, the signature still maps one-to-one contact handle and 
channel type. The analogy that I made in PresenceUpdate was that even 
though a contact is able to hold several presence types at once (which 
isn't the usual case), we could still map one-to-one a contact handle 
with its presence, for the sake of simplicity (avoiding the nested array).

> 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? :)
>
>   
I'm not sure if I got the point. Are you proposing the following?

StatusNumber -> (StatusString, PresenceType)
e.g.:
1 -> ("feeling chatty", TYPE_AVAILABLE)
2 -> ("available", TYPE_AVAILABLE)
...
>> 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.

Yeah, let's make the other way around. Make Presence consistent with 
Capabilities.
>  How many people on the list would
> kill me if I just changed it in the next spec release? :D
>
>   
I would give you a hug (IRC style, of course). :-)
> [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
>
>   
Let's do it while the spec is still below a 1.0 version.
> [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
>
>   
I also hate g_hash_table_foreach. I even wrote a utility function in 
telepathy-inspector that transforms a GHashTable into a GArray. :-)

Regards,
Daniel d'Andrada T. de Carvalho - INdT