This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.

An Account object encapsulates the necessary details to make a Telepathy connection.

Accounts are uniquely identified by object path. The object path of an Account MUST take the form /org/freedesktop/Telepathy/Account/cm/proto/acct, where:

cm is the same Connection_Manager_Name that appears in the connection manager's well-known bus name and object path
proto is the Protocol name as seen in ConnectionManager.ListProtocols, but with "-" replaced with "_" (i.e. the same as in the object-path of a Connection)
acct is an arbitrary string of ASCII letters, digits and underscores, starting with a letter or underscore, which uniquely identifies this account
Clients SHOULD parse the object path to discover the connection manager and protocol
Clients MUST NOT attempt to parse acct
Clients MUST NOT assume that acct matches the connection-specific part of a Connection's object-path and bus name
The account manager SHOULD choose acct such that if an account is deleted, its object path will be re-used if and only if the new account is in some sense "the same" (incorporating the 'account' parameter in some way is recommended)

This API avoids specifying the "profiles" used in Mission Control 4.x or the "presets" that have been proposed to replace them. An optional interface will be provided for AM implementations that want to provide presets.

There is deliberately no functionality here for opening channels; we intend to provide that in the channel dispatcher.

Other missing features which would be better in their own interfaces:

dynamic parameter-providing (aka provisioning)
saved server capabilities
account conditions
account grouping

moved the Avatar property to a separate interface A list of the extra interfaces provided by this account. Delete the account.

This account has been removed. This is redundant with AccountRemoved, but it's still worth having, to avoid having to bind to AccountManager.AccountRemoved to tell you whether your Account is valid — ideally, an account-editing UI should only care about a single Account. The values of one or more properties on this interface (that do not specify that this signal does not apply to them) may have changed. This does not cover properties of other interfaces, which must provide their own change notification if appropriate. A map from property names in this namespace (e.g. Nickname) to values. Properties whose values have not changed SHOULD be omitted, but this need not be done. The user-visible name of this account. This SHOULD be chosen by the user at account creation time. The account creation user interface is responsible for setting a reasonable default value in the user's locale; something like "Jabber (bob@example.com)" would be sensible. This approximately corresponds to "display name" in NMC 4.x and Decibel. The name of an icon in the system's icon theme, such as "im-msn", or the empty string to not specify an icon. If the icon is set to an empty string, the account manager or any client MAY derive a default icon, for instance from the protocol. This approximately corresponds to mc_profile_get_icon_name (or possibly mc_profile_get_branding_icon_name) in NMC 4.x. It's accessed via the account rather than the profile because we no longer have profiles as a core concept. If true, this account is considered by the account manager to be complete and usable. If false, user action is required to make it usable, and it will never attempt to connect (for instance, this might be caused by the absence of a required parameter). For connection managers with a plugin architecture, like telepathy-haze, we have little or no control over the parameters offered; for platforms with package management, we have little or no control over the CMs offered. NMC 4.x would just pretend the account didn't exist in these circumstances, but silent data loss is bad, and UIs with CM-specific knowledge (or a user filling in newly-required parameters) might be able to rescue a broken account.

This property gives the users the possibility to prevent an account from being used. This flag does not change the validity of the account.

A disabled account can never be put online.

Use cases:

user has two or more accounts capable of calling contact X, but he doesn't want the UI to prompt him everytime about which one he wants to use for the call. He can then disable all the equivalent accounts but one.
There is some temporary server error and the user doesn't want to be be bother by error messages, or change the account configuration: temporarily disabling the account is quicker.

The AccountManager SHOULD allow this property to be set on invalid accounts, but MUST NOT attempt to put invalid accounts online even if they become Enabled.

There doesn't seem to be any good reason not to allow this.

The nickname to set on this account for display to other contacts, as set by the user. When the account becomes connected, the account manager SHOULD set this as the user's alias using SetAliases if appropriate. In a later specification revision, we plan to separate the concepts of a contact's nickname as set by themselves, and the local name for them in our contact list (a "handle" or "pet name" as described in XEP-0165 and its references). The terminology change from alias to nickname here is a step in that direction. This corresponds to NMC 4.x mc_account_get_alias.

A map from connection manager parameter names (as in the ConnectionManager interface) to their values. This property includes only those parameters that are stored for this account, and SHOULD only include those parameters that the user has explicitly set.

This property cannot be altered using Set() - use UpdateParameters instead.

This avoids NMC being tied to gconf as a matter of API.

Change the value of the Parameters property.

If any of the changed parameters' Conn_Mgr_Param_Flags include DBus_Property, the change will be applied to the corresponding D-Bus Property on the active Connection, if there is one. Changes to other parameters will not take effect until the next time the account is disconnected and reconnected.

In general, reconnecting is a destructive operation that shouldn't happen as a side-effect. In particular, migration tools that twiddle the settings of all accounts shouldn't cause an automatic disconnect and reconnect.

parameters which are also D-Bus properties can and should be updated on existing Connections return an array of the parameters that won't change until the account is reconnected A mapping from parameter names to their values. These parameters should be stored for future use. A list of the names of parameters to be removed from the set of stored values, allowing the default values to be used. If the given parameters were not, in fact, stored, or even if they do not exist at all, the account manager MUST accept this without error. A list of the names of parameters with changes that will not take effect until the account is reconnected (this may be empty, e.g. if all the parameters are D-Bus properties or parameters for which the account manager has specific support). User interfaces that require "instant apply" semantics MAY call Reconnect in response to receiving a non-empty list.

The presence status that this account should have if it is brought online.

Setting this property MUST NOT actually change the account's status until the next time it is (re)connected for some reason.

The Connection_Presence_Type in the structure SHOULD NOT be Offline or Unset.

In ITOS2007 and ITOS2008 this is a global preference, not visible on D-Bus (the "default presence"). "Automatic presence" better describes when it is used. If true, the account manager SHOULD attempt to put this account online with the AutomaticPresence whenever possible (in the base Account interface this is deliberately left vague). If false, it MUST NOT put the account online automatically in response to, for instance, connectivity changes, but SHOULD still put the account online with the AutomaticPresence if requested by the user (for instance, if the user tries to start a conversation using this account). This approximately corresponds to NMC 4.x "enabled" and Decibel "autoreconnect".

Either the object path of the Connection to this account, or the special value '/' if there is no connection.

If this object path is not '/', the Connection's well-known bus name can be derived from this object path by removing the first '/' and replacing subsequent '/' characters with '.'.

Object paths aren't nullable, so we can't use an empty string. If the Connection property is non-empty, the status of that connection. If the Connection property is the empty string, this property may either be Disconnected (indicating that the account manager is not attempting to bring it online), or Connecting (indicating that the account manager is attempting to connect). The account manager is expected to set this by observing signals from the Connection. If the AM is doing some sort of backoff/delay on reconnection attempts, the account's status is conceptually "Connecting" even though there is no Connection. This vaguely corresponds to GetCurrentStatus in NMC 4.x. The reason for the last change to ConnectionStatus. The account manager is expected to set this by observing signals from the Connection. If you weren't watching the Connection at the time it failed, you can't tell why - unless the AM can tell you. This is part of GetCurrentStatus in NMC 4.x. The actual presence. If the connection is not online, this should be (Connection_Presence_Type_Offline, "", ""). If the connection is online but does not support the SimplePresence interface, this should be (Connection_Presence_Type_Unset, "", ""). The account manager is expected to set this by observing signals from the Connection. This corresponds to GetPresenceActual in NMC 4.x.

The requested presence for this account. When this is changed, the account manager should attempt to manipulate the connection manager to make CurrentPresence match RequestedPresence as closely as possible. It should not be saved to any sort of persistent storage.

When the account manager automatically connects an account, it must signal this by setting the RequestedPresence to the same thing as the AutomaticPresence.

This corresponds to e.g. GetPresence and GetPresenceMessage in NMC 4.x.

Re-connect this account. If the account is currently disconnected and the requested presence is offline, or if the account is not Enabled or not Valid, this does nothing.

If the account is disconnected and the requested presence is not offline, this forces an attempt to connect with the requested presence immediately.

If the account is connecting or connected, this is equivalent to remembering the current value of RequestedPresence, setting its value to (OFFLINE, "offline", ""), waiting for the change to take effect, then setting its value to the value that was previously remembered.

Clients desiring "instant apply" semantics for CM parameters MAY call this method to achieve that.

In particular, if the account's Connection is in the Connecting state, calling this method causes the attempt to connect to be aborted and re-tried.

This is necessary to ensure that the new parameters are picked up.

The normalized user ID of the local user on this account (i.e. the string returned when the InspectHandles method is called on the result of GetSelfHandle for an active connection).

It is unspecified whether this user ID is globally unique.

As currently implemented, IRC user IDs are only unique within the same IRCnet. On some saner protocols, the user ID includes a DNS name which provides global uniqueness.

If this value is not known yet (which will always be the case for accounts that have never been online), it will be an empty string.

It is possible that this value will change if the connection manager's normalization algorithm changes, although this SHOULD be avoided.

It's not always completely clear what normalization algorithm should be used; for instance, in Gabble, we currently use JIDs, but it would also have been reasonable to use xmpp URIs.

If true, this account has successfully been put online at some point in the past. UIs could apply a policy that the 'account' parameter can only be edited in accounts that have never been online, or that ConnectAutomatically cannot be set on such accounts. The account manager should not enforce such policies, but it can expose enough information to UIs that the UI can decide what to do.