Attachment 56334 Details for Bug 14540 – proposed patch

[patch] proposed patch

0001-fd.o-14540-Names-interface-draft.patch (text/plain), 18.82 KB, created by Simon McVittie on 2012-01-30 08:40:59 UTC

(hide)

Description:

Filename:

MIME Type:

Creator: Simon McVittie

Created: 2012-01-30 08:40:59 UTC

Size: 18.82 KB

patch

obsolete

>From e847e6f5867f6a11103455dcae587cb463295758 Mon Sep 17 00:00:00 2001
>From: Simon McVittie <simon.mcvittie@collabora.co.uk>
>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.</
> <tp:mapping name="Alias_Map" array-name="">
> <tp:docstring>A dictionary whose keys are contact handles and whose
> values are aliases.</tp:docstring>
>- <tp:member type="u" tp:type="Contact_Handle" name="Handle"/>
>- <tp:member type="s" name="Alias"/>
>+ <tp:member type="u" tp:type="Contact_Handle" name="Handle">
>+ <tp:docstring>
>+ A contact.
>+ </tp:docstring>
>+ </tp:member>
>+
>+ <tp:member type="s" name="Alias">
>+ <tp:docstring>
>+ 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.
>+ </tp:docstring>
>+ </tp:member>
> </tp:mapping>
> 
> <tp:struct name="Alias_Pair" array-name="Alias_Pair_List">
>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 @@
>+<?xml version="1.0" ?>
>+<node name="/Connection_Interface_Names" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
>+ <tp:copyright>Copyright Â© 2009-2010 Collabora Ltd.</tp:copyright>
>+ <tp:copyright>Copyright Â© 2009 Nokia Corporation</tp:copyright>
>+
>+ <interface name="org.freedesktop.Telepathy.Connection.Interface.Names.DRAFT">
>+ <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
>+
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ 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:
>+
>+ <ul>
>+ <li>a nickname which they can set at will, either when the
>+ account is created or at any time</li>
>+ <li>an alias (local alias) assigned privately by the local
>+ user and stored in the local user's contact list</li>
>+ <li>an abbreviated/less-precise form of their unique identifier
>+ (pretty ID)</li>
>+ </ul>
>+
>+ 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
>+ <a href="http://www.xmpp.org/extensions/xep-0165.html"
>+ >XEP-0165 "Best Practices to Discourage JID Mimicking"</a> and
>+ <a href="http://www.skyhunter.com/marcs/petnames/IntroPetNames.html"
>+ >An Introduction to Petname Systems</a> for further discussion on
>+ this topic.
>+
>+ In Telepathy, the JID or equivalent unique identifier is the string
>+ form of a <tp:type>Contact_Handle</tp:type>, the nickname is
>+ available via this interface as the <code>nickname</code> attribute,
>+ and the "pet name", if stored on the server, is available
>+ via this interface as the <code>local-alias</code> 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.
>+
>+ <tp:rationale>
>+ 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 <a href="https://bugs.freedesktop.org/show_bug.cgi?id=14540"
>+ >freedesktop.org bug 14540</a> for more context.
>+ </tp:rationale>
>+
>+ 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.
>+ </tp:docstring>
>+
>+ <method name="GetNicknames" tp:name-for-bindings="Get_Nicknames">
>+ <tp:docstring>
>+ 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
>+ <tp:member-ref>NicknamesUpdated</tp:member-ref>
>+ signal will be emitted for them.
>+
>+ <tp:rationale>
>+ 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.
>+ </tp:rationale>
>+ </tp:docstring>
>+
>+ <arg direction="in" name="Contacts" type="au" tp:type="Contact_Handle[]">
>+ <tp:docstring>
>+ The contacts whose nicknames should be returned or signalled.
>+ </tp:docstring>
>+ </arg>
>+
>+ <arg direction="out" name="Nicknames" type="a{us}"
>+ tp:type="Alias_Map">
>+ <tp:docstring>
>+ The contacts' nicknames, if already known. Contacts whose nicknames
>+ are not already known, or who have no nickname set, are omitted from
>+ the mapping.
>+ </tp:docstring>
>+ </arg>
>+
>+ <tp:possible-errors>
>+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
>+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
>+ </tp:possible-errors>
>+ </method>
>+
>+ <method name="RequestNickname" tp:name-for-bindings="Request_Nickname">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ 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.
>+
>+ <tp:rationale>
>+ 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.
>+ </tp:rationale>
>+ </tp:docstring>
>+
>+ <arg direction="in" name="Contact" type="u" tp:type="Contact_Handle">
>+ <tp:docstring>
>+ The contact whose nickname should be returned.
>+ </tp:docstring>
>+ </arg>
>+
>+ <arg direction="out" name="Nickname" type="s">
>+ <tp:docstring>
>+ 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.).
>+ </tp:docstring>
>+ </arg>
>+
>+ <tp:possible-errors>
>+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
>+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
>+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
>+ <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied">
>+ <tp:docstring>
>+ The requested contact does not allow the local user to see their
>+ self-assigned nickname.
>+ </tp:docstring>
>+ </tp:error>
>+ </tp:possible-errors>
>+ </method>
>+
>+ <signal name="NicknamesUpdated" tp:name-for-bindings="Nicknames_Updated">
>+ <tp:docstring>
>+ Emitted when contacts' nicknames change or become known.
>+ </tp:docstring>
>+
>+ <arg name="Nicknames" type="a{us}" tp:type="Alias_Map">
>+ <tp:docstring>
>+ A map from contacts' handles to their new "nickname" attributes.
>+ </tp:docstring>
>+ </arg>
>+ </signal>
>+
>+ <property name="Nickname" tp:name-for-bindings="Nickname"
>+ access="readwrite" type="s">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ The local user's own nickname.
>+
>+ On connections managed by the <tp:dbus-ref
>+ namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref>,
>+ clients other than the account manager SHOULD set the <tp:dbus-ref
>+ namespace="org.freedesktop.Telepathy">Account.Nickname</tp:dbus-ref>
>+ 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 <code>local-xmpp</code>), the connection manager SHOULD
>+ support
>+ <code>org.freedesktop.Telepathy.Connection.Interface.Names.DRAFT.Nickname</code>
>+ as a parameter for <tp:dbus-ref
>+ namespace="org.freedesktop.Telepathy.ConnectionManager"
>+ >RequestConnection</tp:dbus-ref>,
>+ with <code>DBus_Property</code> in its
>+ <tp:type>Conn_Mgr_Param_Flags</tp:type>.
>+
>+ On protocols where nicknames persist between connections, the
>+ connection manager SHOULD NOT support this parameter.
>+
>+ <tp:rationale>
>+ 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).
>+ </tp:rationale>
>+ </tp:docstring>
>+ </property>
>+
>+ <tp:contact-attribute name="nickname" type="s">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ The same string that would be returned by
>+ <tp:member-ref>GetNicknames</tp:member-ref>.
>+ 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.
>+ 
>+ </tp:docstring>
>+ </tp:contact-attribute>
>+
>+ <signal name="LocalAliasesUpdated" tp:name-for-bindings="Local_Aliases_Updated">
>+ <tp:docstring>
>+ Emitted when a contact's local alias changes or becomes known.
>+ </tp:docstring>
>+
>+ <arg name="Aliases" type="a{us}" tp:type="Alias_Map">
>+ <tp:docstring>
>+ A map from contacts' handles to their new "local-alias" attributes.
>+ </tp:docstring>
>+ </arg>
>+ </signal>
>+
>+ <tp:contact-attribute name="local-alias" type="s">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ 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
>+ <a href="http://www.skyhunter.com/marcs/petnames/IntroPetNames.html"
>+ >Introduction to Petname Systems</a>, or a "handle" in the
>+ terminology of <a href="http://xmpp.org/extensions/xep-0165.html"
>+ >XEP-0165 "Best Practices to Discourage JID Mimicking"</a>).
>+
>+ 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.
>+
>+ <tp:rationale>
>+ This is a generalization of XEP-0165 to protocols other than
>+ XMPP.
>+ </tp:rationale>
>+
>+ 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.
>+
>+ <tp:rationale>
>+ 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.
>+ </tp:rationale>
>+ </tp:docstring>
>+ </tp:contact-attribute>
>+
>+ <property name="AliasStorage" tp:name-for-bindings="Alias_Storage"
>+ type="u" tp:type="Contact_Metadata_Storage_Type" access="read">
>+ <tp:docstring>
>+ Indicates the extent to which contacts' local aliases can be set and
>+ are stored.
>+ </tp:docstring>
>+ </property>
>+
>+ <method name="SetLocalAlias" tp:name-for-bindings="Set_Local_Alias">
>+ <tp:docstring>
>+ 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.
>+
>+ <tp:rationale>
>+ This is a generalization of
>+ <a href="http://xmpp.org/extensions/xep-0165.html"
>+ >XEP-0165 "Best Practices to Discourage JID Mimicking"</a>)
>+ to protocols other than XMPP.
>+ </tp:rationale>
>+ </tp:docstring>
>+
>+ <arg name="Contact" type="u" tp:type="Contact_Handle" direction="in">
>+ <tp:docstring>
>+ The contact.
>+ </tp:docstring>
>+ </arg>
>+
>+ <arg name="Alias" type="s" direction="in">
>+ <tp:docstring>
>+ The new value for the contact's "local-alias" attribute, or the empty
>+ string to remove the alias.
>+ </tp:docstring>
>+ </arg>
>+
>+ <tp:possible-errors>
>+ <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
>+ <tp:error name="org.freedesktop.Telepathy.Error.InvalidHandle"/>
>+ <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
>+ <tp:error name="org.freedesktop.Telepathy.Error.NotImplemented">
>+ <tp:docstring>
>+ It was not possible to perform the requested action, because
>+ <tp:member-ref>AliasStorage</tp:member-ref> is
>+ Contact_Metadata_Storage_Type_None.
>+ </tp:docstring>
>+ </tp:error>
>+ </tp:possible-errors>
>+ </method>
>+
>+ <tp:contact-attribute name="pretty-id" type="s">
>+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
>+ 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).
>+
>+ <tp:rationale>
>+ The appropriate rules to construct such a thing are
>+ protocol-specific.
>+ </tp:rationale>
>+
>+ 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.
>+
>+ <tp:rationale>
>+ Clients have to be prepared to fall back to using the identifier
>+ anyway, in protocols that don't have the Names interface at
>+ all.
>+ </tp:rationale>
>+ </tp:docstring>
>+ </tp:contact-attribute>
>+
>+ </interface>
>+
>+ <tp:license xmlns="http://www.w3.org/1999/xhtml">
>+ 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.
>+ </tp:license>
>+</node>
>+
>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.</
> <xi:include href="Connection_Interface_Contact_Capabilities.xml"/>
> <xi:include href="Connection_Interface_Contact_Info.xml"/>
> <xi:include href="Connection_Interface_Location.xml"/>
>+ <xi:include href="Connection_Interface_Names.xml"/>
> <xi:include href="Connection_Interface_Presence.xml"/>
> <xi:include href="Connection_Interface_Renaming.xml"/>
> <xi:include href="Connection_Interface_Resources.xml"/>
>-- 
>1.7.8.3
>

Actions: View | Splinter Review

Attachments on bug 14540: 56334 | 72519 | 72520

Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.