Methods
| GetNicknames | (au: Contacts) | → | a{us}: Nicknames | |
| RequestNickname | (u: Contact) | → | s: Nickname | |
| SetLocalAlias | (u: Contact, s: Alias) | → | nothing |
Signals
| NicknamesUpdated | (a{us}: Nicknames) | |
| LocalAliasesUpdated | (a{us}: Aliases) |
Properties
| Nickname | s | Read/Write | |
| AliasStorage | u (Contact_Metadata_Storage_Type) | Read only |
Contact Attributes
Description
This interface represents connections where contacts have some sort of human-readable name in addition to their unique identifier. There are several things this can mean, and many protocols support more than one:
- a nickname which they can set at will, either when the account is created or at any time
- an alias (local alias) assigned privately by the local user and stored in the local user's contact list
- an abbreviated/less-precise form of their unique identifier (pretty ID)
User interfaces SHOULD NOT display the nickname as a contact's only identification, since it is chosen by the contact and could be set to a misleading value, for instance by an attacker seeking to masquerade as someone known to the user. Displaying the contact's self-chosen unique identifier (e.g. JID) is helpful, but it is not a complete solution for this, due to the existence of homograph attacks. See XEP-0165 "Best Practices to Discourage JID Mimicking" and An Introduction to Petname Systems for further discussion on this topic.
In Telepathy, the JID or equivalent unique identifier is the string
form of a Contact_Handle, the nickname is
available via this interface as the nickname attribute,
and the "pet name", if stored on the server, is available
via this interface as the local-alias attribute.
User interfaces MAY also store a "pet name" locally; this is necessary
if they are to support protocols with no server-stored contact list,
like SIP.
The Aliasing interface mixes the concept of a name chosen by the contact with the concept of a name chosen by the local user. This means that compliance with XEP-0165 is impossible. In addition, if the locally-chosen alias takes precedence over the remotely-chosen nickname (as it usually should), it is impossible to see changes to the remotely-chosen nickname after a locally-chosen alias has been set.
See freedesktop.org bug 14540 for more context.
Similarly, the "pretty ID" is not necessarily enough information to identify a contact uniquely, but it can be useful as something to display in an address book or list of contacts if no local alias or nickname is available.
Methods
GetNicknames (au: Contacts) → a{us}: Nicknames
Parameters
- Contacts — au (Contact_Handle_List)
Returns
- Nicknames — a{us} (Alias_Map)
Possible Errors
- Disconnected
- Invalid Handle
RequestNickname (u: Contact) → s: Nickname
Parameters
- Contact — u (Contact_Handle)
Returns
- Nickname — s
Return the current nickname of the given contact. If necessary, make a request to the server for up-to-date information, and wait for a reply.
This method is appropriate for use in a "Contact Information..." dialog; it can be used to show progress information (while waiting for the method to return), and can distinguish between various error conditions.
This method is also appropriate for detection of whether a locally-configured nickname should be set on a server.
Possible Errors
- Disconnected
- Network Error
- Invalid Handle
- Permission Denied
SetLocalAlias (u: Contact, s: Alias) → nothing
Parameters
- Contact — u (Contact_Handle)
- Alias — s
Sets a user-defined alias for a contact. Clients SHOULD NOT call this method for names not assigned by the local user, since this would undermine the anti-spoofing benefits of storing a user-selected alias.
This is a generalization of XEP-0165 "Best Practices to Discourage JID Mimicking") to protocols other than XMPP.
Possible Errors
- Disconnected
- Invalid Handle
- Network Error
- Not Implemented
Signals
Properties
Nickname — s
The local user's own nickname.
On connections managed by the AccountManager, clients other than the account manager SHOULD set the Account.Nickname property instead, which will result in a change to this property next time the account is online (or immediately, if it is already online).
This property MAY be set on a newly-created connection while it is still in the Disconnected or Connecting state. If this is done, the Connection must store the given nickname temporarily, until connecting succeeds or fails, and apply it if the connection attempt is successful.
On protocols where nicknames do not persist between connections
(such as local-xmpp), the connection manager SHOULD
support
org.freedesktop.Telepathy.Connection.Interface.Names.DRAFT.Nickname
as a parameter for RequestConnection,
with DBus_Property in its
Conn_Mgr_Param_Flags.
On protocols where nicknames persist between connections, the connection manager SHOULD NOT support this parameter.
This allows the account manager to set the nickname as a side-effect of RequestConnection, if it would not otherwise persist, without overwriting any remote change to the user's nickname (perhaps with a different client).
AliasStorage — u (Contact_Metadata_Storage_Type)
Indicates the extent to which contacts' local aliases can be set and are stored.
Contact Attributes
org.freedesktop.Telepathy.Connection.Interface.Names.DRAFT/nickname — s
The same string that would be returned by GetNicknames. If omitted from the result of GetContactAttributes, this indicates that no nickname is known; user interfaces SHOULD be prepared to cope with this, for instance by displaying the contact's identifier instead.
org.freedesktop.Telepathy.Connection.Interface.Names.DRAFT/local-alias — s
If this attribute on a contact is present in the result of GetContactAttributes, its value is an name assigned to the contact by the local user (a "pet name" in the terminology of Introduction to Petname Systems, or a "handle" in the terminology of XEP-0165 "Best Practices to Discourage JID Mimicking").
Connection managers SHOULD NOT use the same storage for names not assigned by the local user, since this would undermine the anti-spoofing benefits of storing a user-selected alias.
This is a generalization of XEP-0165 to protocols other than XMPP.
For contacts with no stored aliases (including, but not limited to, contacts on protocols where there is no way to store an alias at all), this attribute is omitted from the result of GetContactAttributes or GetContactListAttributes. User interfaces MUST be able to display contacts who have no alias, for instance by falling back to their identifier.
JIDs on the XMPP roster are meant to have an alias, and in most clients they always do, but it is technically possible to add a contact to the roster without storing an alias for them.
org.freedesktop.Telepathy.Connection.Interface.Names.DRAFT/pretty-id — s
If this attribute on a contact is present in the result of GetContactAttributes, its value is a protocol-specific abbreviated or formatted version of their self-assigned unique identifier, which may be more appropriate to display in a user interface.
For instance, in protocols like XMPP where identifiers are of the form user@domain, it would be appropriate to use the user part of the identifier as the "pretty ID". In a protocol where usernames are OpenIDs, various heuristics would be possible (removing a leading http:// and a trailing / is an obvious one).
The appropriate rules to construct such a thing are protocol-specific.
If there is no obvious way to abbreviate or format identifiers in the protocol, this attribute SHOULD be omitted from signals and method results. Clients that would otherwise display it SHOULD fall back to using the full identifier.
Clients have to be prepared to fall back to using the identifier anyway, in protocols that don't have the Names interface at all.