Methods
| Remove | () | → | nothing | |
| UpdateParameters | (a{sv}: Set, as: Unset) | → | as: Reconnect_Required | |
| Reconnect | () | → | nothing |
Signals
| Removed | () | |
| AccountPropertyChanged | (a{sv}: Properties) |
Properties
| Interfaces | as (DBus_Interface_List) | Read only | ||
| DisplayName | s | Read/Write | ||
| Icon | s | Read/Write | ||
| Usable | b | Read only | ||
| Enabled | b | Read/Write | ||
| Nickname | s | Read/Write | ||
| Service | s | Read/Write | ||
| Parameters | a{sv} | Read only | ||
| AutomaticPresence | (uss) (Presence) | Read/Write | ||
| ConnectAutomatically | b | Read/Write | ||
| Connection | o | Read only | ||
| ConnectionStatus | u (Connection_Status) | Read only | ||
| ConnectionStatusReason | u (Connection_Status_Reason) | Read only | ||
| ConnectionError | s (DBus_Error_Name) | Read only | ||
| ConnectionErrorDetails | a{sv} (String_Variant_Map) | Read only | ||
| CurrentPresence | (uss) (Presence) | Read only | ||
| RequestedPresence | (uss) (Presence) | Read/Write | ||
| ChangingPresence | b | Read only | ||
| NormalizedName | s | Read only | ||
| HasBeenOnline | b | Read only | ||
| Supersedes | ao | Read/Write |
Description
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
/im/telepathy1/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.Protocols, 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)
Rationale:
Methods
Remove () → nothing
Possible Errors
- Permission Denied
UpdateParameters (a{sv}: Set, as: Unset) → as: Reconnect_Required
Parameters
- Set — a{sv}
- Unset — as
Returns
- Reconnect_Required — as
If all of the updates could be applied to the active Connection (if any), the empty list, signifying that no reconnection is required for the new parameters to take effect. For example, if the only parameter updated is ...Cellular.MessageValidityPeriod, the new value can be applied immediately to the connection.
Otherwise, a list of the names of parameters with changes that
will not take effect until the account is reconnected. User
interfaces that require "instant apply" semantics MAY call
Reconnect in response to receiving a
non-empty list. For example, if the caller updates both
...Anonymity.AnonymityMandatory
and require-encryption, the former can be applied to the
current connection, but the latter needs a reconnect to take
effect, so this method should return
["require-encryption"].
Change the value of the Parameters property.
If any of the Set parameters’
Conn_Mgr_Param_Flags include
DBus_Property, the change will be applied immediately to
the corresponding D-Bus Property on the active
Connection, if there is one. If any of
the Unset parameters’
Conn_Mgr_Param_Flags include both
DBus_Property and Has_Default, the
corresponding D-Bus Property on the connection will be set to the
default value. Changes to other parameters will not take effect
until the next time the account is disconnected and reconnected. (If
parameters are explicitly set to their default value, or are unset
when previously set to their default value, the account manager MAY
decide that no reconnection is necessary to make the change take
effect.)
Rationale:
Possible Errors
- Permission Denied
- Invalid Argument
Reconnect () → nothing
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 Usable, 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.
Rationale:
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.
Rationale:
Signals
AccountPropertyChanged (a{sv}: Properties)
Parameters
- Properties — a{sv}
Properties
Interfaces — as (DBus_Interface_List)
DisplayName — s
Icon — s
Usable — b
Rationale:
Enabled — b
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.
Rationale:
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.
Rationale:
Nickname — s
Rationale:
Service — s
Some protocols, like XMPP and SIP, are used by various different user-recognised brands, such as Google Talk and Ovi by Nokia. On accounts for such services, this property SHOULD be set to a string describing the service, which MUST consist only of ASCII letters, numbers and underscores, and start with a letter (matching the requirements for Protocol_Name). For the jabber protocol, one of the following service names should be used if possible:
- google_talk (for Google's IM service)
- ovi_chat (for Ovi's IM service)
- facebook (for Facebook's IM service)
- lj_talk (for LiveJournal's IM service)
- windows_live (for Windows Live Messenger IM service)
For the IRC protocol, the network name (freenode, gimpnet, etc.) can be used if relevant.
The Icon property SHOULD be set to a corresponding brand-specific icon name, if possible. In the future, this property may be used as an index into additional service-specific customizations. If this property is the empty string (or missing), the service is determined by the protocol name (either because this is a single-service protocol like msn, or because this is just a generic jabber or sip account without specific branding).
This property MAY be set, if appropriate, when calling
CreateAccount. Updating this property will fail on
externally-stored accounts whose StorageRestrictions include
Cannot_Set_Service.
Parameters — a{sv}
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
org.freedesktop.DBus.Properties.Set(); use
UpdateParameters instead.
AutomaticPresence — (uss) (Presence)
The presence status that this account should have if it is brought online.
Rationale:
Setting this property MUST NOT actually change the account's status until the next time it is (re)connected for some reason.
The value of this property MUST be one that would be acceptable for RequestedPresence, with the additional restriction that the Connection_Presence_Type MUST NOT be Offline.
Rationale:
ConnectAutomatically — b
Connection — o
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 '.'.
Rationale:
ConnectionStatus — u (Connection_Status)
Rationale:
ConnectionStatusReason — u (Connection_Status_Reason)
Rationale:
ConnectionError — s (DBus_Error_Name)
If the last connection to this account failed with an error, the D-Bus error name of that error; otherwise, the empty string. The account manager is expected to set this by observing the Connection.ConnectionError and Connection.StatusChanged signals.
If ConnectionError is received before the connection disconnects, its first argument should be used to set this property; otherwise, the Reason argument of StatusChanged should be converted to a suitable D-Bus error name.
Whenever the Connection connects successfully, this property should be reset to the empty string.
Rationale:
ConnectionErrorDetails — a{sv} (String_Variant_Map)
If the last connection to this account failed with an error, a mapping representing any additional information about the last disconnection; otherwise, the empty map. The keys and values are the same as for the second argument of Connection.ConnectionError.
Whenever the Connection connects successfully, this property should be reset to the empty map.
Rationale:
CurrentPresence — (uss) (Presence)
RequestedPresence — (uss) (Presence)
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.
The Connection_Presence_Type in this property MUST NOT be Unset, Unknown or Error.
Rationale:
ChangingPresence — b
If true, a change to the presence of this account is in progress.
Whenever RequestedPresence is set on an account that could go online, or whenever an account with a non-offline RequestedPresence becomes able to go online (for instance because Enabled or Usable changes to True), ChangingPresence MUST change to True, and the two property changes MUST be emitted in the same AccountPropertyChanged signal, before the Set method returns.
When the account manager succeeds or fails in changing the presence, or the connection disconnects due to an error, ChangingPresence MUST change to False as part of the same AccountPropertyChanged signal.
Rationale:
NormalizedName — s
The normalized user ID of the local user on this account (i.e. the string returned when the InspectHandles method is called on the value of the SelfHandle property for an active connection).
It is unspecified whether this user ID is globally unique.
Rationale:
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.
Rationale:
HasBeenOnline — b
Rationale:
Supersedes — ao
A list of the object paths of formerly-used accounts which are superseded by this one.
Rationale:
If the Account Manager implementation performs an account migration automatically, it SHOULD set this property. If a client performs an account migration, it SHOULD set this property via via the Properties argument of CreateAccount when creating the migrated account. In either case, the value SHOULD include the old account's path, and every path from the old account's Supersedes property.