Mission Control

Mission Control Spec

(Unless state otherwise, MC refers to 'Mission Control')

What is Mission Control?

Mission Control, or MC, is a telepathy component providing a way for "end-user" applications to abstract some of the details of connection managers, to provide a simple way to manipulate a bunch of connection managers at once, and to remove the need to have in each program the account definitions and credentials.

There will exist more than one MC component (no 'blessed' implementation). It is probable that each desktop of importance will implement its own MC since its job is very tied to the working of the underlying desktop environment and look&feel.

Each MC should however implement some well-defined API's much like each connection manager respond to a set of well-defined telepathy API's.

The set of API's implemented by MCs will be split in several interfaces to ease progressive and adaptative implementation of each facet.

It is expected for any application to be able to use any implementation (providing the required interfaces). For example a gnome application should be able to use KDE's MC implementation and vice-versa (unless MC-specific calls are made..)

File Ecosystem

Beside the MC API, there are several other details that need to be standardised upon.

There are different types of files that the MC will use, and that are installed by the various connection managers package or third-party application needing to be hooked-in.

See FileFormats for details. Any MC should be able to handle all those file formats as expected (as explained in this document and the linked document)

Mission Control Tasks

Account Management

MC should be able to read and write the user's account information. This include the various parameters, the profile and any other useful information used for each defined connection.

It is also useful to use desktop-specific storage for certain parameters, like the passwords (example: kwallet, gnome-keyring).

When creating an account, the UI should present to the user a list of all available profiles, and remove or differentiate duplicate vanilla profiles (see FileFormats). This is a policy left to the implementor and requires no API.

MC should also cache the dbus service names for each managed connection to be able to recover gracefully in case of crash (hooking up into existing MC-created connection after the recovery: using ListNames on the bus and matching any existing dbus service against the cached name).

The accounts are not expected to be updated 'live' when some parameters are changed. It is preferable to have a 'changed' flag indicating that the account needs a reconnection to use the new settings, and let the account configuration UI, or any other component handle that flag in a meaningful way for the user. Then when the next reconnection occurs reset the flag.

Accounts are expected to be identified with a unique fixed string. A common way to generate this string is to concatenate the connection manager name, the protocol name, and a unique number, but there are no requirements.

Every defined account must have a toggle to enable/disable it. When an account is disabled it will never be used, it will never be returned in the (FIXME) Accounts API calls and will never appear in any UI (except the account configuration UI). When an account is disabled it is automatically disconnected. When an account is enabled it is automatically set to the existing presence state (connecting if needed, etc).

Every defined account must have a user-defined name (that the application can fill-in automaticallly if omitted). This name will be used for differentiation purpose along with the username of each account. That way it is possible to differentiate two jabber accounts:

Since each environnement will use different components to store and retreive these informations, there is no mission control API to handle the editing task, but it is expected that components involved in the account edition process talk through existing ways (for example gconf) or custom dbus API bits.

The mandatory API for this task is to allow listing existing accounts and retreiving enough information to be able to display to the user what is needed for example when adding a new contact (the user should be able to select in which account the contact will be added)

The API for this task will be defined under the (FIXME) Accounts interface.

Synchronising personal data, presence and connection statuses across accounts

MC try to keep syncable settings across all connections in a consistent state. Syncable settings are defined as:

When changing one of the syncable settings, the MC should do whatever is necessary to bring all accounts in the desired state (ie. connecting disconnected accounts, setting the desired presence, or disconnecting in case of going to offline presence, upload new avatar to all active connections, ..).

In case of an error in one of the connections, the MC should retry a number of times and finally if the error persist give up with that particular connection and signal the problem for further processing by UI's.

The MC can also receive hints from various desktop services to detect implicit syncable setting information (such as Screensaver activation, Power management information, Networking availability information) and set the syncable settings accordingly.

Policy for such events is not defined by telepathy, and is up to the implementor to match the global look&feel of the platform he is developping the MC for.

The API for this task is divided in several interfaces:

Requesting Channels

Applications will want channels of different types to be created for certain persons. For example the Email application can embed an Avatar of the person writing the email with a 'Chat' button when that person is online.

Note: If an application wants to create a channel and handle it itself, it shouldn't go through the MC since only the application is responsible for that channel. All channel requests going through the MC will be dispatched with the .chandler mechanism (see FileFormats)

There will be two ways of requesting channels to be created and handled by the MC.

The API details for this task will be defined under the (FIXME) Channels interface.

Activating the channel handlers

When an NewChannel event is fired in one of the managed connections, the MC should perform a lookup in the .chandler files and activate every matching channel handlers.

This task can be subject to environnement-specific configuration which we won't specify here. For example:

This task exposes no dbus API.

Proposed API

(FIXME) Accounts

GetAccounts() -> [(s:account_id, s:profile, s:name, s:account)]

Returns a list of all enabled accounts (whatever the connection status may be).

Where: 

CreateAccount() -> s:account_id

Creates a new account and returns the account_id for that account.

GetAccountProperties(s: account_id) -> a{sv}

Returns a dictionary of all the given accounts parameters

SetAccountProperties(s: account_id, a{sv}: properties)

Sets the parameters for the given existing account

SetEnabled(s:account_id, b:enabled) -> void

Enable or disable the given account

(FIXME) Presences

Using the status definition from the "org.freedesktop.Telepathy.Connection.Interface.Presence" interface: 

SetPresence(s:status, s:message) -> void

Set the presence for all online accounts handled by the mission control.

Where: 

GetPresence() -> s:status, s:message

Get the current presence used for all online accounts handled by mission control

Where:

Note: If a third party or an error occurs, the server-side presence setting of some accounts might not be in the advertised state. States are resynchronized upon change, but there exist a timeframe where they might not be all equal. 

signal PresenceChanged(s:status, s:message)

Fired after SetPresence is used.

(FIXME) SyncableSettings

signal SyncError(s:id, u:error, u:reason)

Fired when there was an error trying to synchronise accounts to the desired setting. Fired once per failed account.

Where:

(FIXME) Avatars

GetAvatar() -> ?

Get the currently used avatar

SetAvatar(?) -> void

Sets the avatar to be used by all accounts

(FIXME) PersonalInfos

GetPersonalInfo() -> ?

Get the currently used personal info

SetPersonalInfo(?) -> void

Set the personal info to be used by all accounts

(FIXME) Channels

RequestChannelWithConnection(s:conn_name, s:chan_type, u:handle_type, u:handle) -> void

Request the MC to create and dispatch a new channel on the given connection for the given handle

Where:

Note: This presumes that the application knows about the connection name and made a RequestHandle on it. 

RequestChannelWithAccount(s:chan_type, u:handle_type, s:name, s:account) -> void

Request the MC to create and dispatch a new channel on the given connection for the given name

Where:

Note: Calling this method will do a translation of account->connection name inside the MC, then RequestHandle is invoked with the given arguments, then the channel is created using the account's connection and the received handle.

This implies that clients have a way to determine on which account is a particular name stored.

If the account is currently disconnected, this method call will return an error.

More ?

The following tasks are not defined or clear enough to be attributed to the MC and are being discussed for inclusion in the spec, or rejection.

Unifying contacts

Mailing-list: It would be cool if there was some correlation between identical contacts. This could allow fallbacks to different CMs depending on the contact's availability. A simple use case, I want to message Beth, my priorities are: Jabber, MSN, SMS. This means that I will attempt to reach her in that order, depending on availability. The CM needs to magically unify all these contacts, and needs to give the user a way to alter the preferred methods of communication.

Raf: I think this is the role of galago to merge accounts under a 'Person' and then gather all capabilities that one has with that person, not the MC role

Widget library

Mailing-list: For desktop MCs it would be nice if they provided a shared library with a variety of useful widgets in their respected toolkit (QT/GTK+), that would allow any program to display account settings, list CMs and such with a unified look. It will use the API you guys proposed. A simple use case: A user expects to be able to edit his accounts settings in the roster window (which is not part of MC), the roster program (ie. Gossip), could simply display the same thing you would see in the MC's capplet.

Raf: A widget library is useful, but i'm not sure wether all apps should provide configuration for the accounts (rather than a link to the canonical configuration UI) In any case you need a widget when adding a contact to one of the account (to choose which account to add the contact to).