[Telepathy] Proposed standard MC API

[Robert McQueen]

George Wright wrote:
> On Thursday 02 August 2007 12:15:28 Alberto Mardegan wrote:
>> Since Telepathy API allows setting and retrieving presence+message with
>> a single call, I think we'd better do the same in mission-control.
> 
> That would probably be sensible.

+1.

>> Small remark about naming: [Get|Set]Enabled, or [Enable|IsEnabled] seem
>> more consistent.
> 
> Seems reasonable. I think [Get|Set]Enabled is probably better in this case as 
> an Enable function would also be able to disable it.

+1, seems more consistent with the other [Get|Set] functions.

>> Is Decibel using components only for handling channels as Nokia MC does,
>> or do they something more?
> 
> I believe they only handle channels. Decibel's components currently only 
> expose a channel handling API, but you'll have to talk to Tobias Hunger about 
> that.

As far as I can tell they are basically equivalent to what NMC calls
channel handlers, but they have the interesting property that clients
are able to manipulate the component registry at run-time. For instance,
one client can set itself up to receive all text channels on a certain
protocol. This is pretty useful, and I think Decibel has a use case for
this already because of different modes of UI for different protocols; a
telephone UI for a CTI backend, but an IM/VOIP UI for an IM backend. I
think the Banter guys were also keen that when Banter is in use as the
UI for certain connections, all of the text/media channels for those
connections are only handled by Banter, and something like this might
help there too.

>> This has also some impact on the accounts API: AddAccount (which I would
>> rather call CreateAccount) needs to receive the profile in input. About
>> account creation, Nokia MC does not emit the "AccountCreated" signal
>> until the account is complete (i.e., all the required parameters are
>> set), because it's likely that clients listening to this signal would
>> respond to it trying to get some information on the newly created
>> account, or put it online.
>> Maybe we could split the API into two different parts:
>>
>> CreateAccount ( [s:profile?] ) -> o
>>
>> That creates the account object but doesn't return it in ListAccounts
>> and friends, and maybe emits an AccountCreated signal (but would it be
>> of any use?), and
>>
>> AddAccount ( o:account ) -> nothing
> 
> That sounds sensible. How would the profiles be referenced by the client? MC 
> should deal with the locating and indexing of which profiles are available, 
> not the client, in my opinion. Maybe string or integer handles assigned by MC 
> which can be obtained through a ListProfiles ( ) -> a(so) linking profile 
> handle to connection manager object path?

-1, I'd go for exposing Profile objects through the D-Bus API as their
own objects as discussed elsewhere. Inventing extra identifier spaces
makes life harder for bindings which do actually want to represent these
things as objects.

> Also, that seems to have the effect of not being able to create an account 
> without a profile. Are there any use cases for wanting to be able to create 
> an account with no profile set?

Accounts definitely need to be specific to a (manager, protocol) tuple,
because changing them between managers is wrong (consider the manager
that supports encryption, with a "require-encryption" option set to TRUE
by the user, and the manager that doesn't, and MC choosing to use the
other one... oops). NMC achieves this by using profiles, which specify
the implementation which should be used, but this is rapidly proving not
to be scalable because a generic UI like Empathy can't be expected to
have prior knowledge of all existing connection managers.

Currently I'm leaning to the idea that we should discard the UI-specific
elements from profiles (or at least make them optional), so that we can
either ship profiles with CMs, or according to some policy, make sure
that we create a dynamic profile for each protocol installed so that
it's usable without extra stuff.

>> that will register the account to the AccountManager and emits the
>> AccountAdded signal.
>> So, for creating an account one would call CreateAccount(), set all the
>> needed properties/parameters, and then call AddAccount().
> 
> If we were to do that I think AddAccount and CreateAccount are a bit too 
> similar. Perhaps if we were to rename AddAccount to ActivateAccount, that 
> would make more sense.
> 
> Alternatively, we could create accounts disabled by default and then when they 
> are enabled a signal is emitted such as AccountEnabled ( o: account ), and 
> AccountCreated is still emitted when an account is created, but it is 
> disabled by default.

I think splitting the creation and appearance is a bit odd, it means you
can leak these half-created account objects which have an object path
but are otherwise unusable. Are these persistent, do they disappear when
MC exits, how do you find them again if the client crashes at that
moment? I'd prefer to see a way of atomically creating them, so that you
give over all the stuff, and get back an object that's well-formed. This
might mean providing a profile and the parameters to the creation
function, and having default empty/disabled values for the other stuff
like display name, avatar and enabled.

>> In the ProtocolManager (or, probably better, in a separate Protocol
>> class) we need a method for retrieving the list of the valid protocol
>> parameters, with their type, default value and whether they are required.
> 
> Is it better to expose this over the D-Bus API instead of making clients parse 
> the .manager files?

Whichever API manages the profiles should represent all of the relevant
information which is derived from overlaying managers, profiles,
preferences and stuff. It should be in the D-Bus API because it's likely
that we want to be able to either create profiles on the fly, or have
them be mutable in some ways. It also helpfully resolves ambiguity about
when profiles are usable or not, or a client creating and referring to a
file which MC hasn't seen, etc.

Also I'd rather see the D-Bus API complete enough to allow MC to be used
fully, otherwise for each MC client library/binding, we force
reimplementations of XDG search paths, and key-value file parsing, etc,
and also we break any remote system use-cases before they've even appeared.

Regards,
Rob