From e847e6f5867f6a11103455dcae587cb463295758 Mon Sep 17 00:00:00 2001 From: Simon McVittie Date: Mon, 12 Apr 2010 15:39:52 +0100 Subject: [PATCH] fd.o #14540: Names interface draft --- spec/Connection_Interface_Aliasing.xml | 15 ++- spec/Connection_Interface_Names.xml | 360 ++++++++++++++++++++++++++++++++ spec/all.xml | 1 + 3 files changed, 374 insertions(+), 2 deletions(-) create mode 100644 spec/Connection_Interface_Names.xml diff --git a/spec/Connection_Interface_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml index 9675771..f3e79f7 100644 --- a/spec/Connection_Interface_Aliasing.xml +++ b/spec/Connection_Interface_Aliasing.xml @@ -24,8 +24,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. A dictionary whose keys are contact handles and whose values are aliases. - - + + + A contact. + + + + + + An alias for that contact. The precise semantics (including whether + the alias was chosen by the local user or by the contact) depend + on the context in which this map appears. + + diff --git a/spec/Connection_Interface_Names.xml b/spec/Connection_Interface_Names.xml new file mode 100644 index 0000000..0f17abf --- /dev/null +++ b/spec/Connection_Interface_Names.xml @@ -0,0 +1,360 @@ + + + Copyright © 2009-2010 Collabora Ltd. + Copyright © 2009 Nokia Corporation + + + + + +

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.

+ + + + + 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 + NicknamesUpdated + 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. + + + + + + The contacts whose nicknames should be returned or signalled. + + + + + + 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 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.

+ + + + + + The contact whose nickname should be returned. + + + + + + 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.). + + + + + + + + + + The requested contact does not allow the local user to see their + self-assigned nickname. + + + + + + + + Emitted when contacts' nicknames change or become known. + + + + + A map from contacts' handles to their new "nickname" attributes. + + + + + + +

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).

+ + + + + + +

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. +

+ + + + + + Emitted when a contact's local alias changes or becomes known. + + + + + A map from contacts' handles to their new "local-alias" attributes. + + + + + + +

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.

+ + + + + + +

Indicates the extent to which contacts' local aliases can be set and + are stored.

+ + + + + +

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.

+ + + + + + The contact. + + + + + + The new value for the contact's "local-alias" attribute, or the empty + string to remove the alias. + + + + + + + + + + It was not possible to perform the requested action, because + AliasStorage is + Contact_Metadata_Storage_Type_None. + + + + + + + +

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.

+ + + + + + + +

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.

+ + + diff --git a/spec/all.xml b/spec/all.xml index 72e4c49..7384167 100644 --- a/spec/all.xml +++ b/spec/all.xml @@ -84,6 +84,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + -- 1.7.8.3