Interface AccountManager

Interface Index (Compact) | Summary | Description | Methods | Signals | Properties

Methods

CreateAccount (s: Connection_Manager, s: Protocol, s: Display_Name, a{sv}: Parameters, a{sv}: Properties) o: Account

Signals

AccountRemoved (o: Account)
AccountValidityChanged (o: Account, b: Valid)

Properties

Interfaces as (DBus_Interface_List) Read only
ValidAccounts ao Read only
InvalidAccounts ao Read only
SupportedAccountProperties as (DBus_Qualified_Member_List) Read only
Added in 0.17.2.

Description

The account manager is a central service used to store account details.

The current account manager is defined to be the process that owns the well-known bus name org.freedesktop.Telepathy.AccountManager on the session bus. This process must export an /org/freedesktop/Telepathy/AccountManager object with the AccountManager interface.

Until a mechanism exists for making a reasonable automatic choice of AccountManager implementation, implementations SHOULD NOT register as an activatable service for the AccountManager's well-known bus name. Instead, it is RECOMMENDED that some component of the user's session will select and activate a particular implementation, and that other Telepathy-enabled programs can detect whether Telepathy is in use by checking whether the AccountManager's well-known name is in use at runtime.

Methods

(Permalink)

CreateAccount (s: Connection_Manager, s: Protocol, s: Display_Name, a{sv}: Parameters, a{sv}: Properties) → o: Account

Changed in 0.17.24. added the Properties argument

Parameters

  • Connection_Manager — s (Connection_Manager_Name)
  • The name of the connection manager, e.g. "salut".
  • Protocol — s (Protocol)
  • The protocol, e.g. "local-xmpp".
  • Display_Name — s
  • The initial value of the new account's DisplayName property. The account manager SHOULD modify this to make it unique if an Account already exists with the same display name, for instance by appending a number or the 'account' parameter. Account manager implementations SHOULD accept an empty string, but account editing user interfaces should avoid passing an empty string for this parameter.
    Rationale:

    The account creation UI may ask the user for a name for the new account. If the author of the UI chooses not to do this, the account creation UI is better able to suggest a default display name because it has protocol-specific knowledge which the account manager does not.

    The account manager always knows the complete list of accounts so it can easily tell whether it should append something to the display name to avoid presenting two identically-named accounts to the user.

  • Parameters — a{sv}
  • Initial parameter values, as would be passed to RequestConnection.
  • Properties — a{sv} (Qualified_Property_Value_Map)
  • The values of any other properties to be set immediately on the new Account.

    Only the properties mentioned in SupportedAccountProperties are acceptable here. In particular, the DisplayName and Parameters properties are never allowed here, since they are set using the other arguments to this method.

    Account manager implementations SHOULD support creating accounts with an empty value for this argument.

Returns

Request the creation of a new Account. The account manager SHOULD NOT allow invalid accounts to be created.

Possible Errors

  • Not Implemented
  • The Connection_Manager is not installed or does not implement the given Protocol, or one of the properties in the Properties argument is unsupported.

  • Invalid Argument
  • The Parameters provided omit a required parameter or provide unsupported parameter, or the type of one of the Parameters or Properties is inappropriate.

Signals

(Permalink)

AccountRemoved (o: Account)

Parameters

  • Account — o
  • An Account, which must not be used any more.
The given account has been removed.
Rationale:
This is effectively change notification for the valid and invalid accounts lists. On emission of this signal, the Account indicated will no longer be present in either of the lists.
(Permalink)

AccountValidityChanged (o: Account, b: Valid)

Parameters

  • Account — o
  • An Account.
  • Valid — b
  • True if the account is now valid.
The validity of the given account has changed. New accounts are also indicated by this signal, as an account validity change (usually to True) on an account that did not previously exist.
Rationale:
This is effectively change notification for the valid and invalid accounts lists.

Properties

Accessed using the org.freedesktop.DBus.Properties interface.
(Permalink)

Interfaces — as (DBus_Interface_List)

Read only
A list of the interfaces provided by the account manager object.
(Permalink)

ValidAccounts — ao

Read only
A list of the valid (complete, usable) Accounts. Change notification is via AccountValidityChanged.
Rationale:
This split between valid and invalid accounts makes it easy to ignore the invalid ones. The only things that should be manipulating invalid accounts are account-editing UIs, which might be able to rescue them.
(Permalink)

InvalidAccounts — ao

Read only
A list of incomplete or otherwise unusable Accounts. Change notification is via AccountValidityChanged.
(Permalink)

SupportedAccountProperties — as (DBus_Qualified_Member_List)

Read only
Added in 0.17.24.

A list of the fully qualified names of properties that can be set via the Properties argument to CreateAccount when an account is created.

Rationale:

Examples of good properties to support here include Icon, Enabled, Nickname, AutomaticPresence, ConnectAutomatically, RequestedPresence and Avatar.

Examples of properties that would make no sense here include Valid, Connection, ConnectionStatus, ConnectionStatusReason, CurrentPresence and NormalizedName.

This property MUST NOT include include the DisplayName and Parameters properties, which are set using separate arguments.

This property MAY include the names of properties that, after account creation, will be read-only: this indicates that the property can be set at account creation but not changed later.

Rationale:

For example, an account manager might support migration tools that use this to preserve the HasBeenOnline property, even though that property is usually read-only.