[Telepathy] Proposed standard MC API

[George Wright]

Hello all,

I am working for Collabora on a new Mission Control D-Bus
API specification which we can hopefully standardise on.

At the moment there seem to be two different implementations,
Nokia's mission-control project, and KDE/basysKom's Decibel
project.

The idea of this project is to allow clients to be written to
a standard API and not have them tied down to any one single
implementation of Mission Control.

So far I have made the following decisions:

- Use the org.freedesktop.Telepathy.MissionControl namespace
  for bus/interface names.

- Keep the naming scheme of the API consistent with that for
  Telepathy; that is, capitalise the first letter of each word
  in the function, ie. UpdateAccount not updateAccount.

- Split up the various methods/signals into different
  objects which expose different interfaces based on what they do. 
  That is, put all account specific methods in MissionControl.AccountManager
  etc.

- Do not specify any configuration system that Mission Control
  should use to store data. This should be left to the discretion
  of the implementation depending on environment.

Now for the draft specification. It's based heavily on Decibel's current API,
because in my opinion they've done it pretty well.

-------------------------------------------------------
org.freedesktop.Telepathy.MissionControl.AccountManager
-------------------------------------------------------

* Accounts are D-Bus objects which store information such as
  server address, username, login etc.

ListAccounts ( ) -> ao

  Returns an array of all known account objects in MC.

AddAccount ( ) -> o

  Add an account to MC.

  Returns the object path of the new account.

FindAccounts ( a{sv}: account_data ) -> ao

  Returns all accounts whose account data contains the search query.

  An empty array should return all possible accounts.

GetOnlineAccounts ( ) -> ao

  Returns the object paths of all the accounts which are 
  currently online.

ConnectAll ( ) -> nothing

  Requests all accounts go online with the default presence.

SetGlobalPresence ( u: presence_state, s: message ) -> nothing

  Set a global presence and message on all accounts, putting accounts
  online if necessary.

+ Signals

AccountCreated ( o: account )

  Emitted when an account is created.

AccountUpdated ( o: account )
 
  Emitted when an account is updated.

AccountDeleted ( o: account )
 
  Emitted when an account is deleted.

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.

------------------------------------------------
org.freedesktop.Telepathy.MissionControl.Account
------------------------------------------------

* Each account object should expose the following set of D-Bus
* methods in order to be manipulated.

SetParameters ( a{sv}: account_data ) -> nothing

  Set account parameter dictionary replacing current values.

  See org.freedesktop.Telepathy.ConnectionManager, method 
  RequestConnection for a description of the struct.

UpdateParameters ( a{sv}: account_data ) -> nothing

  Update the account parameter dictionary.

GetParameters ( ) -> a{sv}

  Gets the current parameters set on the account.

Delete ( ) -> nothing

  Delete the account.

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

  Requests a channel be opened for an account to a handle, putting the account
  online if necessary.

  type - s
    D-Bus interface name representing the channel type
  handle_type - i
    The type of the handle to create a channel to.
  handle - s
    Handle representing a contact, room, list etc.

SetPresence ( u: presence ) -> nothing

  Request that a presence be set on the account.

GetRequestedPresence ( ) -> u

  Gets the last requested presence for the account. 
  This is not necessarily the same as the actual presence.

GetCurrentPresence ( ) -> u

  Gets the current presence actually set on the account.

GetRequestedPresenceMessage ( ) -> s

  Gets the last requested presence message on the account referenced
  by account_handle.

GetCurrentPresenceMessage ( ) -> s

  Gets the current presence message actually set on the account.

SetPresenceMessage ( s: message ) -> nothing

  Set a presence message on an account.

GetConnectionStatus ( ) -> u

  Gets the status of the connection.

SetAvatar ( ay: avatar, s: mime_type ) -> nothing

  Takes an avatar as a byte array in the format specified
  by mime_type. If the mime type is unknown leave mime_type blank.

GetAvatar ( ) -> ay, s

  Gets the avatar as a byte array and the mime type of the avatar.

SetDisplayName ( s: display_name ) -> nothing
  
  Sets a display name on the account.

GetDisplayName ( ) -> s

  Gets the current display name set on the account.

GetNormalizedName ( ) -> s
 
  Gets the normalized name of the account (the result of inspecting the
  connection's self handle when the account is online).

GetConnection ( ) -> s, o

  Gets the bus name and the object path of the connection
  associated with the account if it's online. 

SetEnabled ( b: enabled ) -> nothing

  Sets whether the account is enabled or not.

IsEnabled ( ) -> b
 
  Gets whether the account is enabled or not.

+ Presence States (enumerated type):

0 Unset
1 Offline
2 Available
3 Away
4 Extended Away
5 Hidden
6 Do Not Disturb

--------------------------------------------------------
org.freedesktop.Telepathy.MissionControl.ProtocolManager
--------------------------------------------------------

ConnectionManagers ( ) -> ao

  Returns the object paths of all the connection managers known
  to Mission Control.

SupportedProtocols ( ) -> as
  
  Returns the protocols supported by the connection managers
  known to Mission Control.

ProtocolConnectionManagers ( s: protocol ) -> ao

  Returns the object paths of the connection managers which
  are able to handle the protocol specified.

TODO:

The following areas have not been taken into consideration and we
might want to look into them.

- Abstract plugins like Decibel's "Component" system. These are like
  Nokia Mission Control's channel handlers and filters. We need to come
  up with a standard API for these. 

- Accounts; enabled, normalised name, display name, etc - do we want to
  implement these as D-Bus properties or methods? 

- We need something like Nokia Mission Control's "Profiles" system 
  because changing a connection manager for a given protocol isn't
  necessarily going to work as there is no exhaustive standard
  for the configuration settings a given connection manager should
  take. Particularly, we need to decide on who provides the profiles; 
  Mission Control, the UI or somewhere else?

Many thanks,

George

-- 
George Wright, http://www.gwright.org.uk
KDE Developer - http://www.kde.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://lists.freedesktop.org/archives/telepathy/attachments/20070801/874f3204/attachment.pgp