[Telepathy] Proposed standard MC API

[Robert McQueen]

Tobias Hunger wrote:
> On Wednesday 01 August 2007, George Wright wrote:
> 
>> Now for the draft specification. It's based heavily on Decibel's current
>> API, because in my opinion they've done it pretty well.
> 
> Plagiarism is the most sincere form of flattery ;-)

ITYM imitation. If it was plagarism, that paragraph wouldn't have been
there. ;-)

> Turning accounts into full D-Bus objects seems awfully heavy to me. I wanted 
> to avoid that overhead.

Having magic numbers (like Telepathy's handles, which although they
address the normalisation issue, should probably have been 'o') makes
things far more awkward for bindings into other languages, because
things which really /are/ conceptually objects end up disappearing into
a soup of methods on some other object, some of which act on these
identifiers, and some of which don't.

You end up having to wrap it and produce the objects anyway in order to
have an API that's easy to use, and then you lose any sense of the
"optimisation" of using the identifiers - both the client and the
service have the real objects internally anyway, but are forced to have
translation code which hides them in favour of identifiers.

It's far more natural for MC's account objects to be D-Bus objects which
the client can just call methods and listen to signals on. Uncle Havoc
discusses this issue in his blog at http://log.ometer.com/2007-05.html.

>> GetOnlineAccounts ( ) -> ao
>>
>>   Returns the object paths of all the accounts which are
>>   currently online.
> 
> This is redundant: FindAccounts can do that (at least with Decibel's lighter
> concept of accounts).

Uh... Decibel puts the presence into the dictionary as well? Does it put
the current presence, the desired presence, or both? Is that persistent?
That wasn't clear to any of us, even after George wrote the
documentation for it. As stated elsewhere, I think mixing these things
into the same dictionary as the CM's parameters is risky, and I'm not
sure I like the idea of mixing volatile with persistent information in a
way that's unclear to the client.

I'm happy to agree that we could do with a better way to search
accounts, because NMC has got API like mc_accounts_find_by_{foo,bar,baz}
which aren't represented in the current draft API.

>> ConnectAll ( ) -> nothing
>>
>>   Requests all accounts go online with the default presence.
> 
> This function is not required in Decibel: It brings up all accounts anyway (or 
> better: Those with requested status is != Offline).

Yeah, this function is redundant given the ability to set the presence
on accounts.

>> SetGlobalPresence ( u: presence_state, s: message ) -> nothing
>>
>>   Set a global presence and message on all accounts, putting accounts
>>   online if necessary.
> 
> I consider this method to be too dangerous: My phone should not disconnect 
> just because I want my IM accounts offline. This method encourages applet 
> developers, etc. to do the wrong thing.

Possibly yes, so maybe we need a way to effect presence which only
affects certain groups of accounts. If we had a filtering mechanism we
could provide a filtered version of this function, so that the applet
could merely set all IM accounts online if it was dealing with that
class of communication. We could introduce an account group concept, and
then set presence on groups?

>> + Signals
> 
>> AccountStatusChanged ( o: account, u: status, u: presence, u: reason )
>>
>>   Emitted when an account's connection status changes.
>>
>>   Connection states and Reason are both defined in Telepathy.
> 
> With your concept of Accounts-as-D-Bus-objects this should probably move to 
> the Account object... but that makes registering interest in this signal a 
> bit more annoying;-)

I'm willing to say we should move them there (perhaps after thinking a
little harder what we're actually trying to notify people about), it's
easy on a D-Bus level to bind to signals from any instance of a certain
interface.

>> ------------------------------------------------
>> org.freedesktop.Telepathy.MissionControl.Account
>> ------------------------------------------------
> 
> 
> What I do not like about this is that there is no unified way to query for 
> accounts. In Decibel there is findAccounts(asv) which can be used to query a 
> combination of every detail about an account. This interface suggested here 
> splits out some information from the parameters, which makes it hard to do 
> queries like "Get me all accounts that are online using the protocol X".

Well, the mixing of params and metadata worries me somewhat, but I agree
we need some better searching stuff. We could possibly represent the
metadata in a seperate dictionary for searching purposes, or devise some
other cunning thing... answers on a postcard. We could just do something
pretty simple like say that everything's representable in one
dictionary, but all of the CM params are prefixed with "param-".

> Apropos protocol: Where is the protocol used by the account stored?

In the profile, which as you have noted isn't yet addressed by this
spec. We wanted to get it out there for some discussion before moving on
to that bit.

>> SetPresence ( u: presence ) -> nothing
>> GetRequestedPresence ( ) -> u
>> GetCurrentPresence ( ) -> u
> 
> Decibel uses requested presence to manage online state: You request a 
> presence != Offline and Decibel connects the account and set it
> to Offline to disconnect again.
> 
> The current presence is what actually is seen on the server.

How do you mean? The client says "make this my presence", and then
nothing happens until MC has succeeded in making that happen? That makes
it very hard to tell that MC has applied a heuristic for you, like
setting Away because a certain protocol doesn't support Extended Away.

> So this is necessary...
> 
>> GetRequestedPresenceMessage ( ) -> s
>> GetCurrentPresenceMessage ( ) -> s
> 
> but I do not see the need for requested and current presence messages.

I think these will just be folded in to the Set/Get presence.

>> GetConnectionStatus ( ) -> u
> 
> What is this for? If my current presence is != Offline, then I am online... 
> otherwise I am not.

I think mostly to tell when it's connecting. However, it's redundant
because you can tell this is happening... current: offline, requested:
something else. No point in endlessly repeating the CM.

>> GetConnection ( ) -> s, o
> 
> What is this required for? Apps do not need to care about the connections, so 
> there is no need to export them at this point.

Au contraire, I think this is one of the most basic essential features
of MC. It's possible for a client to interact directly with a CM to get
information like aliases, presence, capabilities, or even request
channels and stuff directly (that's why suppress_handler exists, to make
MC leave the channel alone). Indeed, certain clients could interact
solely with connection objects, and never with any channels.

>> SetEnabled ( b: enabled ) -> nothing
>> IsEnabled ( ) -> b
> 
> What is the usecase for this?
> 
> I do not see the need for this. If I do not care about an account going online 
> then I don't set its status to != offline.

This is so MC can know which accounts you want to be affected by the
global presence manipulation functions. Maybe moving the account out of
your "IM" group could be equivalent (note that not all UIs need to
represent this - you can just make an "enabled" group and move accounts
in and out of it if that's your wish :D).

>> --------------------------------------------------------
>> org.freedesktop.Telepathy.MissionControl.ProtocolManager
>> --------------------------------------------------------
> 
>> ConnectionManagers ( ) -> ao
>> SupportedProtocols ( ) -> as
>> ProtocolConnectionManagers ( s: protocol ) -> ao
> 
> In Decibel the reason to have a ProtocolManager is configuration management. 
> Which CM should I use for which protocol? There will be several 
> implementations for protocols sooner or later... 

Yeah, there are already. Haze is now reasonably workable using libpurple
from Pidgin, which means we now have duplicated XMPP, MSN, etc. I think
we've had some ideas elsewhere about how to reach a compromise between
Decibel's dynamic protocol selection, and NMC's static profiles - we
should generate profiles for all of the available protocols, but also
parse profile files to supplement those with installed presets for
certain services (like a specific SIP provider).

> This is completely missing here.

Work in progress. :)

> Best Regards,
> Tobias

Regards,
Rob