[Telepathy] Proposed standard MC API

Wed Aug 8 14:26:26 PDT 2007

One little comment in general:

If you have a SetFoo in your API you need a FooChanged signal. For
example there is no way actually to get notified when the display name
of an account is changed.

Btw, that's a bug I'm facing in NMC.

Xavier Claessens.

Le mercredi 01 août 2007 à 15:31 +0100, George Wright a écrit :
> 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
> 
> _______________________________________________
> Telepathy mailing list
> Telepathy at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/telepathy