[Telepathy] Account and AccountManager objects

[Simon McVittie]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

OK, here's an API sketch. Currently missing are:
* Account status! (next on my list)
* Server capabilities
* Change notification in presets (though we might not actually need that)
and I'm wondering whether "everything is a profile" might actually
simplify things, if we mandated that only MC would ever read .profile
files and everyone else would always ask MC.

org.freedesktop.Telepathy.AccountManager
========================================

The account manager MUST (attempt to) claim the bus name
org.freedesktop.Telepathy.AccountManager. Whichever process has that bus name
is the current account manager.

The account manager MUST export an object at
/org/freedesktop/Telepathy/AccountManager which has this interface.

D-Bus core Properties
- ---------------------

First connecting signals, then getting these with
org.freedesktop.DBus.Properties.GetAll, is recommended.

Interfaces: as (DBus_Interface[]), read-only
  A list of the interfaces provided by this account manager.
  The list MUST include any extra interfaces closely related to AccountManager,
  and SHOULD include any unrelated interfaces that are supported. It MAY
  include the AccountManager interface itself.

  This list SHOULD NOT change during runtime; there is no change notification.

ValidAccounts: ao (implementing o.fd.Telepathy.Account), read-only
  Get a list of the valid, active accounts. Change notification is via
  AccountValidityChanged.

InvalidAccounts: ao (implementing o.fd.Telepathy.Account), read-only
  Get a list of invalid and inactive accounts. Change notification is via
  AccountValidityChanged.

Signals
- -------

AccountValidityChanged (o: Account, b: valid)
  The validity of the given account has changed.

  New accounts are signalled by an account validity change on an account
  that did not previously exist.

AccountRemoved (o: Account)
  The given account has been removed altogether, and must not be used
  any more.

org.freedesktop.Telepathy.AccountManager.Interface.Conditions
=============================================================

Requires: org.freedesktop.Telepathy.AccountManager

This interface models the ability to connect to each account using a list of
conditions. If all the conditions for an account with the auto-connect option
set are satisfied, the account manager SHOULD connect that account.

If the conditions for an account become unsatisfied, the account manager
SHOULD NOT disconnect it immediately, but MAY disconnect it after a
reasonable delay.

Account manager implementations SHOULD have this interface.

Simple types
- ------------

Account_Condition: s
  A condition that might be required for an account to be available.
  These may be any UTF-8 string, but they SHOULD be short strings of ASCII
  letters, digits, hyphen/minus characters and dots, starting with a letter
  or digit.

  All conditions not containing a dot are reserved for the Telepathy
  specification. Third-party conditions SHOULD be namespaced by a reversed
  domain name, e.g. "com.example.vpn-enabled.head-office".

  The following well-known conditions are currently valid:

  ip-default-route
    Either ipv4-default-route or ipv6-default-route is satisfied
    (server-based connection managers which can use both IPv4 and IPv6 SHOULD
    require this)

  ipv4-default-route
    We have an IPv4 default route (i.e. are on a network, and possibly the
    Internet)
    (server-based connection managers which can only use IPv4 SHOULD
    require this)

  ipv6-default-route
    We have an IPv6 default route (i.e. are on a network, and possibly the
    Internet)
    (server-based connection managers which can only use IPv6, if such things
    ever exist, SHOULD require this)

Methods
- -------

GetAutomaticConditions () -> as (Account_Condition[]): Automatic
  Get a list of those account conditions that the Account Manager will
  automatically detect. Clients do not need to call UpdateAccountConditions
  for these, and the Account Manager MAY ignore attempts to update them.

UpdateAccountConditions (as (Account_Condition[]): Added,
                         as (Account_Condition[]): Removed)
  Tell the account manager that the account conditions in the set Added
  are now met (accounts with those requirements may now attempt to connect),
  and the account conditions in the set Removed are no longer met.

  If clients attempt to change automatic account conditions (as returned by
  GetAutomaticConditions), the Account Manager MUST NOT raise an error, and
  MUST change any non-automatic account conditions that are
  changed at the same time, but it MAY ignore the attempt to change the
  automatic account conditions.

GetAccountConditions () -> as (Account_Condition[]): Satisfied
  Get a list of account conditions that are currently satisfied (accounts
  whose requirements are all contained in the returned list may attempt
  to connect).

Signals
- -------

AccountRequirementsUpdated (as: Provided, as: Not_Provided)
  The account requirements in the set Provided are now met; accounts with
  those requirements may now attempt to connect. The account requirements in
  the set Not_Provided are no longer provided.

org.freedesktop.Telepathy.AccountManager.Preset
===============================================

Presets encapsulate a set of defaults for an account. For instance, XMPP
connection managers' defaults are set up for a generic XMPP connection.
A preset for Google Talk could set the default server and port, and require
encryption (since it can reasonably be assumed that Google's servers will
continue to have a certificate from a well-known CA). UIs could also have
provider-specific code triggered by the preset; for instance, a generic
XMPP UI would prompt the user for a JID with an example like user at example.com,
while an account creation UI with Google Talk-specific knowledge could
give an example like example at googlemail.com.

Presets also allow a "branded" user interface; for instance, the Google Talk
preset makes it obvious which option the user should choose in the account
creation UI, even if they don't know that Google Talk is implemented with XMPP.

Objects implementing the Preset interface on the AccountManager MUST have a
path of the following form:

/org/freedesktop/Telepathy/AccountManager/Preset/xxx/yyy/zzz

where xxx is a Connection_Manager_Name as defined by the ConnectionManager
interface, yyy is a Protocol with any hyphen/minus replaced by an underscore,
and zzz is a Preset_Name (the same syntax as a connection manager name).

Clients MAY parse the object path.

(Rationale for having this on D-Bus: this interface makes localization
transparent, avoids an explicit choice of file format, allows the account
manager to synthesize presets automatically if required, and allows the
account manager to implement change-notification for presets in future.)

TODO
- ----

We could in fact move the API back to using Profiles, and have MC synthesize
a profile (called "_" or something, since they're namespaced by CM and
protocol anyway) for each CM/protocol pair that has no .profile files? If
everything switches to using MC rather than reading .profile files directly,
this would work...

It might in fact be useful to keep "vanilla profiles" as a hook for
localizable display names.

We should still ponder how .preset files will work - my thought is currently
gabble-jabber-google_talk.preset.

Capability pre-seeding? Other things that Profiles could have in the Nokia MC?

Change notification for properties, parameters?

Should MC support arbitrary (namespaced) key/value attributes, which it
doesn't understand but can just pass through?

Simple Types
- ------------

Preset_Name: s
  A non-empty string of ASCII letters, digits and underscores, starting with
  a letter. In particular, "_" is not a valid preset name.

  (FIXME: or we could explicitly allow "_", and reserve it for vanilla
  profiles)

Locale: s
  lang[_COUNTRY][.ENCODING][@MODIFIER], or ""/"C"/"POSIX" (all equivalent)

D-Bus core Properties
- ---------------------

Properties in this namespace:

Interfaces: as (DBus_Interface[]), read-only
  A list of the interfaces provided by this account manager.
  The list MUST include any extra interfaces closely related to AccountManager,
  and SHOULD include any unrelated interfaces that are supported. It MAY
  include the AccountManager interface itself.

  This list SHOULD NOT change during runtime; there is no change notification.

DisplayName (s, read-only)
  The displayed name for this preset; this is expected to be localizable.
  It MAY be used as a basis for the default display name for an account
  of this type.

Description (s, read-only)
  A one-line description for this preset; this is expected to be localizable.

Icon (s, read-only)
  Either the absolute path of an icon
  (e.g. "/usr/share/icons/hicolor/scalable/apps/im-msn.svg")
  or an icon name to look up in the icon theme (e.g. "im-msn").
  Presets SHOULD use an icon name whenever possible, to allow
  theming.

ParameterDefaults (a{sv}, read-only)
  Connection manager parameters for this preset, as would be passed
  to RequestConnection. These are used as defaults for accounts that use
  this preset, with the connection manager's own defaults used as a
  fallback.

Conditions: (as (Account_Condition[]), read-only)
  Conditions that accounts using this preset should have by default.

Presets MAY have other interfaces with their own properties.

Methods
- -------

GetInterfaces () -> as
  Return any extra interfaces supported by this preset. The return MAY
  include the Preset interface itself.

GetLocaleProperties (as: Keys, s (Locale): LC_Messages) -> a{sv}
  Get the values corresponding to the given keys for the given LC_MESSAGES
  locale. Missing or unsupported properties are simply omitted from the
  return; clients MUST be able to cope with this.

  As a special case, if Keys is empty, return all known properties.

  Keys not containing a dot refer to D-Bus Properties on the Preset
  interface. Keys containing a dot refer to D-Bus Properties on some other
  interface.

  The keys of the returned dict MUST either not contain a dot, or be
  properties in some interface other than Preset.

  The results if LC_Messages is an empty string, "C" or "POSIX" SHOULD
  match the results of accessing the given keys using the D-Bus core
  Properties interface.

  (Rationale: this is a thin wrapper around .desktop-style localizable
  files, without actually mandating a particular on-disk format. Nokia
  developers want to use gettext for localization instead of/in addition to
  localized .desktop keys, and this API supports that usage.)

org.freedesktop.Telepathy.Account
=================================

Objects implementing the Account interface on the AccountManager MUST have a
path of the following form:

/org/freedesktop/Telepathy/AccountManager/Account/xxx/yyy/zzz/iii

where xxx is a Connection_Manager_Name as defined by the ConnectionManager
interface, yyy is a Protocol with any hyphen/minus replaced by an underscore,
zzz is either a preset name or "_" to indicate that no preset was used, and
iii is one or more implementation-specific components to indicate the
account.

Clients MAY parse the object path to find the connection manager name,
protocol and preset name.

TODO
- ----

Indicating current account status!

Server capabilities

Is the special case listed under desired-status on crack?

Should we let UIs store arbitrary misc?

D-Bus core Properties
- ---------------------

DisplayName: s, read/write
  The displayed name for this account. This is user-selectable; the account
  creation UI is responsible for picking a default value appropriate for the
  user's locale. For example, something like
  g_strdup_printf ("%s (%s)", _(preset_display_name), account) will often
  be reasonable.

Icon: s, read/write
  Same as the icon property of a Preset, except that it MAY also be set
  to an absolute path by the user.

AutoConnect: b, read/write
  If TRUE, when all this account's requirements are satisfied, put it online
  with DesiredStatus automatically.

DesiredStatus: (uss), read/write
  A struct (Connection_Presence_Type, CM-specific presence status, message)
  indicating what status we'll want if we put this account online.
  As a special case, hidden indicates "hidden if possible, else busy",
  while offline indicates "hidden if possible, else offline".

Nickname: s, read/write

Avatar: (ays), read/write

Parameters: a{sv}, read-only
  Connection manager parameters. These must be changed using
  UpdateParameters instead of SetProperty.

Conditions: as, read-only
  Account conditions. These must be changed using UpdateConditions
  instead of SetProperty.

Methods
- -------

GetInterfaces () -> as
  As per usual

GetConnection () -> o
  Return the Connection for this account, if any.

  Raises NotAvailable: if there is not currently a connection open to this
    account

UpdateParameters (a{sv}: add, as: remove)

UpdateConditions (as (Account_Condition[]): Added,
                  as (Account_Condition[]): Removed)

Signals
- -------

AccountPropertiesChanged (a{sv}: Delta)
  Properties from this interface have changed. Delta SHOULD contain only the
  properties from this interface that actually changed, but MAY contain
  properties that have not changed.
  (This signal is still emitted if parameters or conditions change)
-----BEGIN PGP SIGNATURE-----

iD8DBQFHny0bWSc8zVUw7HYRAi0fAJ0VAoo04EHMbSMBMPXk6oR+XaxqpQCeLtvD
G4oGeq8hDESdaDlvQb1OYys=
=iZ/a
-----END PGP SIGNATURE-----