fd.o #14540: Names interface draftnames

3 files changed, 374 insertions, 2 deletions

diff --git a/spec/Connection_Interface_Aliasing.xml b/spec/Connection_Interface_Aliasing.xml
index 96757713..f3e79f76 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 00000000..0f17abfd
--- /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">
+      <p>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:</p>
+
+      <ul>
+        <li>a <em>nickname</em> which they can set at will, either when the
+          account is created or at any time</li>
+        <li>an alias (<em>local alias</em>) 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
+          (<em>pretty ID</em>)</li>
+      </ul>
+
+      <p>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.</p>
+
+      <p>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.</p>
+
+      <tp:rationale>
+        <p>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.</p>
+
+        <p>See <a href="https://bugs.freedesktop.org/show_bug.cgi?id=14540"
+            >freedesktop.org bug 14540</a> for more context.</p>
+      </tp:rationale>
+
+      <p>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.</p>
+    </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">
+        <p>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.</p>
+
+        <tp:rationale>
+          <p>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.</p>
+
+          <p>This method is also appropriate for detection of whether a
+            locally-configured nickname should be set on a server.</p>
+        </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">
+        <p>The local user's own nickname.</p>
+
+        <p>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 <em>this</em>
+          property next time the account is online (or immediately, if it
+          is already online).</p>
+
+        <p>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.</p>
+
+        <p>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>.</p>
+
+        <p>On protocols where nicknames persist between connections, the
+          connection manager SHOULD NOT support this parameter.</p>
+
+        <tp:rationale>
+          <p>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).</p>
+        </tp:rationale>
+      </tp:docstring>
+    </property>
+
+    <tp:contact-attribute name="nickname" type="s">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>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.
+        </p>
+      </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">
+        <p>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>).</p>
+
+        <p>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.</p>
+
+        <tp:rationale>
+          <p>This is a generalization of XEP-0165 to protocols other than
+            XMPP.</p>
+        </tp:rationale>
+
+        <p>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.</p>
+
+        <tp:rationale>
+          <p>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.</p>
+        </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>
+        <p>Indicates the extent to which contacts' local aliases can be set and
+          are stored.</p>
+      </tp:docstring>
+    </property>
+
+    <method name="SetLocalAlias" tp:name-for-bindings="Set_Local_Alias">
+      <tp:docstring>
+        <p>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.</p>
+
+        <tp:rationale>
+          <p>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.</p>
+        </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">
+        <p>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.</p>
+
+        <p>For instance, in protocols like XMPP where identifiers are of the
+          form <em>user</em>@<em>domain</em>, it would be appropriate to use
+          the <em>user</em> 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).</p>
+
+        <tp:rationale>
+          <p>The appropriate rules to construct such a thing are
+            protocol-specific.</p>
+        </tp:rationale>
+
+        <p>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.</p>
+
+        <tp:rationale>
+          <p>Clients have to be prepared to fall back to using the identifier
+            anyway, in protocols that don't have the Names interface at
+            all.</p>
+        </tp:rationale>
+      </tp:docstring>
+    </tp:contact-attribute>
+
+  </interface>
+
+  <tp:license xmlns="http://www.w3.org/1999/xhtml">
+    <p>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.</p>
+
+    <p>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.</p>
+
+    <p>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.</p>
+  </tp:license>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/all.xml b/spec/all.xml
index 72e4c491..73841677 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"/>