[Telepathy] Proposed standard MC API

[Tobias Hunger]

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

> -------------------------------------------------------
> org.freedesktop.Telepathy.MissionControl.AccountManager
> -------------------------------------------------------
>
> * Accounts are D-Bus objects which store information such as
>   server address, username, login etc.

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

> AddAccount ( ) -> o

Why not set the parameters here?

> FindAccounts ( a{sv}: account_data ) -> ao
>
>   Returns all accounts whose account data contains the search query.
>
>   An empty array should return all possible accounts.

The website claims this method returns "nothing", you might want to update 
that.

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

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

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

> + 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;-)

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

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

<...>

> RequestChannel ( o: account, s: type, i: handle_type, s: handle) -> nothing

The o is not required. That is already obvious with the object called. The 
website does not list that parameter, so this is probably just a cut and 
paste error

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

So this is necessary...

> GetRequestedPresenceMessage ( ) -> s
> GetCurrentPresenceMessage ( ) -> s

but I do not see the need for requested and current presence messages.

> GetConnectionStatus ( ) -> u

What is this for? If my current presence is != Offline, then I am online... 
otherwise I am not.

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

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

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

This is completely missing here.

Best Regards,
Tobias
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part.
Url : http://lists.freedesktop.org/archives/telepathy/attachments/20070802/6b061d55/attachment.pgp