Interface org.freedesktop.Telepathy.Connection.Interface.Nicknames.DRAFT

Interface Index (Compact) | Summary | Description | Methods | Signals | Contact Attributes | Types

Methods

GetNicknames (au: Contacts) → a{us}: Nicknames
RequestNickname (u: Contact) → s: Nickname
SetNickname (s: Nickname) → nothing

Signals

NicknameUpdated (u: Contact, s: Nickname)

Contact Attributes

org.freedesktop.Telepathy.Connection.Interface.Nicknames.DRAFT/nickname s

Types

Nickname_Map Mapping a{us}
Objects implementing this interface must also implement:

Description

This interface represents connections where contacts have a nickname which they can set at will, either when the account is created or at any time.

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, and the "pet name" (if stored on the server at all) is available via the forthcoming Connection.ContactList interface. User interfaces MAY 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.

Methods

(Permalink)

GetNicknames (au: Contacts) → a{us}: Nicknames

Parameters

  • Contacts — au (Contact_Handle_List)
    • The contacts whose nicknames should be returned or signalled.

Returns

  • Nicknames — a{us} (Nickname_Map)
    • The contacts' nicknames, if already known. Contacts whose nicknames are not already known, or who have no nickname set, are omitted from the mapping.
Return the current nicknames of the given contacts, if they are already known. If any of the given contacts' nicknames are not known, request their current nicknames, but return immediately without waiting for a reply; if a reply is later received for those contacts, the NicknameUpdated signal will be emitted for them.
This method is appropriate for "lazy" queries, for instance displaying the nickname (if available) of everyone in your contact list. UIs SHOULD be prepared to fall back to displaying the unique identifier (JID, etc.) if no nickname is immediately available.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Invalid Handle
    • The handle specified is unknown on this channel or connection.
(Permalink)

RequestNickname (u: Contact) → s: Nickname

Parameters

  • Contact — u (Contact_Handle)
    • The contact whose nickname should be returned.

Returns

  • Nickname — s
    • The contact's nickname. It MAY be the empty string, indicating that no nickname was found; user interfaces SHOULD be prepared to cope with this, for instance by displaying the contact's identifier (JID, etc.).

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
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Network Error
    • Raised when there is an error reading from or writing to the network.
  • Invalid Handle
    • The handle specified is unknown on this channel or connection.
  • Permission Denied
    • The requested contact does not allow the local user to see their self-assigned nickname.
(Permalink)

SetNickname (s: Nickname) → nothing

Parameters

  • Nickname — s
    • The nickname to advertise.
Set the local user's own nickname.

Possible Errors

  • Disconnected
    • The connection is not currently connected and cannot be used. This error may also be raised when operations are performed on a Connection for which StatusChanged has signalled status Disconnected for reason None.
    The second usage corresponds to None in the Connection_Status_Reason enum; if a better reason is available, the corresponding error should be used instead.
  • Not Implemented
    • Raised when the requested method, channel, etc is not available on this connection.
  • Permission Denied
    • The user is not permitted to perform the requested operation.

Signals

(Permalink)

NicknameUpdated (u: Contact, s: Nickname)

Parameters

  • Contact — u (Contact_Handle)
    • The contact
  • Nickname — s
    • The contact's nickname, or an empty if the contact has no nickname.
Emitted when a contact's nickname changes or becomes known.

Contact Attributes

Attributes that a contact can have, accessed with the org.freedesktop.Telepathy.Connection.Interface.Contacts interface.
(Permalink)

org.freedesktop.Telepathy.Connection.Interface.Nicknames.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.

Types

Mapping (Permalink)

Nickname_Map — a{us}

A dictionary whose keys are contact handles and whose values are nicknames.