sync to spec 0.22.0

7 files changed, 303 insertions, 30 deletions

diff --git a/spec/Account_Interface_External_Password_Storage.xml b/spec/Account_Interface_External_Password_Storage.xml
index 71a542428..5bd1bfce0 100644
--- a/spec/Account_Interface_External_Password_Storage.xml
+++ b/spec/Account_Interface_External_Password_Storage.xml
@@ -27,24 +27,30 @@
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>An interface for Accounts whose passwords are stored externally and
-        SHOULD NOT be stored by either the <tp:dbus-ref
-          namespace="org.freedesktop.Telepathy">AccountManager</tp:dbus-ref> nor
-        any <tp:dbus-ref
-          namespace="org.freedesktop.Telepathy.Channel.Type">ServerAuthentication</tp:dbus-ref>
+        SHOULD NOT be stored by either the
+        <tp:dbus-ref namespace="ofdT">AccountManager</tp:dbus-ref> nor any
+        <tp:dbus-ref namespace="ofdT.Channel.Type">ServerAuthentication</tp:dbus-ref>
         handler.</p>
+
+      <p>This interface SHOULD only appear on accounts for which the
+        related Connection Manager implements
+        <tp:dbus-ref namespace="ofdT">ConnectionManager.Interface.AccountStorage.DRAFT</tp:dbus-ref>.</p>
     </tp:docstring>
 
     <method name="ForgetPassword" tp:name-for-bindings="Forget_Password">
       <tp:docstring>
-        <p>Clears any saved password associated with this account.</p>
+        Clears any saved password associated with this account.
       </tp:docstring>
     </method>
 
     <property name="PasswordSaved"
       tp:name-for-bindings="Password_Saved"
       type="b" access="read">
-      <tp:docstring>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Indicates whether the account has a saved password or not.</p>
+
+        <p>Change notification for this property is provided by the
+          standard D-Bus <code>PropertiesChanged</code> signal.</p>
       </tp:docstring>
     </property>
 
diff --git a/spec/Channel_Type_Server_TLS_Connection.xml b/spec/Channel_Type_Server_TLS_Connection.xml
index 1f3348e12..97efd1b36 100644
--- a/spec/Channel_Type_Server_TLS_Connection.xml
+++ b/spec/Channel_Type_Server_TLS_Connection.xml
@@ -44,23 +44,71 @@
     </tp:docstring>
 
     <property name="ServerCertificate" type="o" access="read"
-              tp:name-for-bindings="Server_Certificate">
+              tp:name-for-bindings="Server_Certificate"
+              tp:immutable='yeah'>
       <tp:docstring>
         <p>A <tp:dbus-ref
         namespace="org.freedesktop.Telepathy.Authentication">TLSCertificate</tp:dbus-ref>
         containing the certificate chain as sent by the server,
         and other relevant information.</p>
-        <p>This property is immutable.</p>
       </tp:docstring>
     </property>
 
     <property name="Hostname" type="s" access="read"
-              tp:name-for-bindings="Hostname">
+              tp:name-for-bindings="Hostname"
+              tp:immutable='sharks'>
       <tp:added version="0.19.12"/>
       <tp:docstring>
-        The hostname of the server we expect <tp:member-ref>ServerCertificate</tp:member-ref>
-        to certify; clients SHOULD verify <tp:member-ref>ServerCertificate</tp:member-ref> against
-	this hostname when checking its validity.
+        <p>The hostname or domain that the user expects to connect to. Clients
+        SHOULD use the <tp:member-ref>ReferenceIdentities</tp:member-ref>
+        property to verify the identity of the certificate. Clients MAY display
+        this hostname to the user as the expected identity. Clients SHOULD use
+        this property to lookup pinned certificates or other user preferences
+        for the connection.</p>
+      </tp:docstring>
+    </property>
+
+    <property name="ReferenceIdentities" type="as" access="read"
+              tp:name-for-bindings="Reference_Identities"
+              tp:immutable='plz'>
+      <tp:added version="0.21.10">
+        If this property is not present, clients SHOULD use the
+        <tp:member-ref>Hostname</tp:member-ref> property as the reference
+        identity to validate server certificates against.
+      </tp:added>
+
+      <tp:docstring>
+        <p>The identities of the server we expect
+        <tp:member-ref>ServerCertificate</tp:member-ref> to certify; clients
+        SHOULD verify that <tp:member-ref>ServerCertificate</tp:member-ref>
+        matches one of these identities when checking its validity.</p>
+
+        <p>This property MUST NOT be the empty list; it MUST
+        contain the value of the <tp:member-ref>Hostname</tp:member-ref>
+        property. All other identities included in this property MUST be derived from
+        explicit user input or choices, such as <tp:dbus-ref
+        namespace='ofdT.Account'>Parameters</tp:dbus-ref> passed to
+        <tp:dbus-ref
+        namespace='ofdT.ConnectionManager'>RequestConnection</tp:dbus-ref>.</p>
+
+        <tp:rationale>
+          <p>The primary use for this property is for XMPP services hosted by
+            <a href='http://www.google.com/apps/intl/en/business/gmail.html'>Google
+            Apps</a>. When connecting to Google Talk using an
+            <tt>@gmail.com</tt> JID, the server correctly presents a
+            certificate for <tt>gmail.com</tt>; however, for domains hosted via
+            Google Apps, a certificate for <tt>talk.google.com</tt> is
+            offered, due to unresolved technical limitations.</p>
+
+          <p>If the user has explicitly chosen to create a <q>Google Talk</q>
+            account, then trusting a certificate for <tt>talk.google.com</tt>
+            is reasonable. To handle this case, the connection manager may add
+            the values of any or all of the <tt>server</tt>,
+            <tt>fallback-server</tt> and <tt>extra-identities</tt> parameters;
+            the Google Talk account creation user interface may set these
+            parameters appropriately, or the user may set them for accounts
+            with other services.</p>
+        </tp:rationale>
       </tp:docstring>
     </property>
 
diff --git a/spec/Connection.xml b/spec/Connection.xml
index 51ec1ab23..0ba095a9e 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -1033,6 +1033,12 @@ USA.</p>
             <dd>Debugging information on the change, corresponding to the
               message part of a D-Bus error message, which SHOULD NOT be
               displayed to users under normal circumstances</dd>
+
+            <dt>server-message (s)</dt>
+            <dd>A human-readable message from the server explaining what
+              happened. This may be in the user's native language, or in the
+              server operator's native language, or even in Lojban.</dd>
+
 	    <dt>user-requested (b), expected-hostname (s), certificate-hostname (s)</dt>
 	    <dd>The same details defined in <tp:type>TLS_Certificate_Rejection</tp:type>.</dd>
           </dl>
diff --git a/spec/Connection_Interface_Contact_Blocking.xml b/spec/Connection_Interface_Contact_Blocking.xml
new file mode 100644
index 000000000..756fd4db8
--- /dev/null
+++ b/spec/Connection_Interface_Contact_Blocking.xml
@@ -0,0 +1,207 @@
+<?xml version="1.0" ?>
+<node name="/Connection_Interface_Contact_Blocking" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
+  <tp:copyright>Copyright © 2009–2011 Collabora Ltd.</tp:copyright>
+  <tp:copyright>Copyright © 2009 Nokia Corporation</tp:copyright>
+  <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>
+  <interface name="org.freedesktop.Telepathy.Connection.Interface.ContactBlocking">
+    <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
+    <tp:requires interface="org.freedesktop.Telepathy.Connection.Interface.ContactList"/>
+    <tp:added version='0.21.13'>Changes from the draft:
+      methods and signals now return <tp:type>Handle_Identifier_Map</tp:type>
+      (<code>a{us}</code>) rather than bare lists of contact handles
+      (<code>au</code>)</tp:added>
+
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>An interface for connections where contacts can be blocked from
+        communicating with this user and receiving this user's presence.
+        Clients may retrieve a list of currently-blocked contacts using
+        <tp:member-ref>RequestBlockedContacts</tp:member-ref>, and listen for
+        <tp:member-ref>BlockedContactsChanged</tp:member-ref> to be notified
+        when contacts are blocked and unblocked. The
+        <tp:member-ref>BlockContacts</tp:member-ref> and
+        <tp:member-ref>UnblockContacts</tp:member-ref> methods do what they say
+        on the tin; depending on the value of the
+        <tp:member-ref>ContactBlockingCapabilities</tp:member-ref> property,
+        contacts may be reported for spam or other abuse when calling
+        <tp:member-ref>BlockContacts</tp:member-ref>.</p>
+
+      <p>This interface is intended for protocols where blocking contacts
+        persists on the server between connections; connection managers for
+        protocols with no server-side support for blocking contacts MAY choose
+        to implement this interface using an on-disk file of blocked
+        contacts or some other means to store blocked contacts between
+        connections.</p>
+
+      <p>This interface is intended to replace the
+        <tp:dbus-ref namespace="ofdT.Channel.Type">ContactList</tp:dbus-ref>
+        channel with <tp:dbus-ref
+        namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
+        <code>List</code> and <tp:dbus-ref
+        namespace='ofdT.Channel'>TargetID</tp:dbus-ref> <code>"deny"</code>
+        (along with the <tp:dbus-ref
+        namespace='ofdT.Connection.Interface'>ContactList</tp:dbus-ref> and
+        <tp:dbus-ref
+        namespace='ofdT.Connection.Interface'>ContactGroups</tp:dbus-ref>
+        interfaces replacing other channels with <tp:dbus-ref
+        namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
+        <code>List</code> and <tp:dbus-ref
+        namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
+        <code>Group</code>, respectively).</p>
+    </tp:docstring>
+
+    <method name="BlockContacts" tp:name-for-bindings="Block_Contacts">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Direct the server to block some contacts. The precise effect is
+          protocol-dependent, but SHOULD include ignoring all current and
+          subsequent communications from the given contacts, avoiding sending
+          presence to them in future, and if they were already receiving the
+          local user's presence, behaving as if the local user went
+          offline.</p>
+      </tp:docstring>
+
+      <arg name="Contacts" type="au" direction="in" tp:type="Contact_Handle[]">
+        <tp:docstring>Some contacts to block. If some of the contacts in this
+          list are already blocked, the connection manager MUST act as if they
+          were not specified in this list.</tp:docstring>
+      </arg>
+
+      <arg name="Report_Abusive" type="b" direction="in">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>In addition to blocking, report these contacts as abusive to the
+            server administrators.</p>
+
+          <p>Clients can determine whether this capability is available by
+            checking the
+            <tp:member-ref>ContactBlockingCapabilities</tp:member-ref>
+            property. If this argument is set to <code>True</code> by a client
+            despite <tp:member-ref>ContactBlockingCapabilities</tp:member-ref>
+            not containing the <code>Can_Report_Abusive</code> flag, the
+            connection manager SHOULD act as if it were <code>False</code> and
+            simply block the supplied contacts.</p>
+
+          <tp:rationale>
+            <p>A correct user interface shouldn't get this far without knowing
+              that reporting abusive contacts is not supported. If it does,
+              then the user has expressed their intention to block these
+              contacts. Returning an error would leave the UI with three
+              options:</p>
+
+            <ul>
+              <li>Ignore the error, leaving the contacts not actually blocked;</li>
+              <li>Display an error to the user;</li>
+              <li>Call this method again, passing <code>False</code> for this
+              argument.</li>
+            </ul>
+
+            <p>None of these seem preferable to the CM just ignoring this flag
+              if it doesn't support it: that way, the contacts will be blocked,
+              as the user requested, and UIs have fewer ways to mess up
+              entirely.</p>
+          </tp:rationale>
+        </tp:docstring>
+      </arg>
+    </method>
+
+    <method name="UnblockContacts" tp:name-for-bindings="Unblock_Contacts">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Direct the server to unblock some contacts.</p>
+      </tp:docstring>
+
+      <arg name="Contacts" type="au" direction="in" tp:type="Contact_Handle[]">
+        <tp:docstring>Some contacts to unblock. If some of the contacts in this
+          list are not currently blocked, the connection manager MUST act as if
+          they were not specified in this list.</tp:docstring>
+      </arg>
+    </method>
+
+    <method name="RequestBlockedContacts"
+      tp:name-for-bindings="Request_Blocked_Contacts">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>List the contacts that are blocked.</p>
+
+        <p>Clients SHOULD allow a relatively long timeout for calls to this
+          method, since on some protocols contact blocking is part of the
+          contact list, which can take a significant time to retrieve.</p>
+      </tp:docstring>
+
+      <arg name="Contacts" type="a{us}" direction="out"
+        tp:type="Handle_Identifier_Map">
+        <tp:docstring>The blocked contacts’ handles, together with their
+          identifiers.</tp:docstring>
+      </arg>
+    </method>
+
+    <signal name="BlockedContactsChanged"
+      tp:name-for-bindings="Blocked_Contacts_Changed">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Emitted when the list of blocked contacts is first retrieved
+          (before returning from any pending calls to
+          <tp:member-ref>RequestBlockedContacts</tp:member-ref>), and
+          whenever the list of blocked contacts subsequently changes.</p>
+      </tp:docstring>
+
+      <arg name="Blocked_Contacts" type="a{us}" tp:type="Handle_Identifier_Map">
+        <tp:docstring>Contacts added to the result of
+          <tp:member-ref>RequestBlockedContacts</tp:member-ref>.</tp:docstring>
+      </arg>
+
+      <arg name="Unblocked_Contacts" type="a{us}"
+           tp:type="Handle_Identifier_Map">
+        <tp:docstring>Contacts removed from the result of
+          <tp:member-ref>RequestBlockedContacts</tp:member-ref>.</tp:docstring>
+      </arg>
+    </signal>
+
+    <tp:contact-attribute name="blocked" type="b">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p><code>True</code> if the contact would be in the result of
+          <tp:member-ref>RequestBlockedContacts</tp:member-ref>;
+          <code>False</code> or omitted if the contact is not blocked, or if it
+          is unknown whether the contact is blocked.</p>
+      </tp:docstring>
+    </tp:contact-attribute>
+
+    <property name="ContactBlockingCapabilities"
+              tp:name-for-bindings="Contact_Blocking_Capabilities"
+              tp:type="Contact_Blocking_Capabilities" type="u" access="read"
+              tp:immutable="yes">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Additional capabilities for contact blocking; currently, this is
+          limited to whether contacts may be reported as abusive.</p>
+
+        <p>Note that there is no capability for supporting blocking itself:
+          the presence of this interface on a <tp:dbus-ref
+          namespace='ofdT'>Connection</tp:dbus-ref> indicates that blocking
+          contacts is supported.</p>
+      </tp:docstring>
+    </property>
+
+    <tp:flags name="Contact_Blocking_Capabilities" type="u"
+              value-prefix="Contact_Blocking_Capability">
+      <tp:flag suffix="Can_Report_Abusive" value="1">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          When calling <tp:member-ref>BlockContacts</tp:member-ref>, the
+          contacts may be reporting as abusive to the server administrators by
+          setting <var>Report_Abusive</var> to <code>True</code>.
+        </tp:docstring>
+      </tp:flag>
+    </tp:flags>
+
+  </interface>
+</node>
+<!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Manager_Interface_Account_Storage.xml b/spec/Connection_Manager_Interface_Account_Storage.xml
index 143d5de73..2f4f4bf78 100644
--- a/spec/Connection_Manager_Interface_Account_Storage.xml
+++ b/spec/Connection_Manager_Interface_Account_Storage.xml
@@ -29,18 +29,18 @@
       <p>An interface for connection managers that store account details
         internally.  At the moment this consists only of storing an account's
         credentials, but other functionality may be added in the future.</p>
-      <p><tp:dbus-ref
-          namespace="org.freedesktop.Telepathy">Account</tp:dbus-ref> objects
+
+      <p><tp:dbus-ref namespace="ofdT">Account</tp:dbus-ref> objects
         representing accounts on a connection manager that implements this
-        interface should implement the <tp:dbus-ref
-          namespace="org.freedesktop.Telepathy.Account.Interface">ExternalPasswordStorage.DRAFT</tp:dbus-ref>
+        interface should implement the
+	<tp:dbus-ref namespace="ofdT.Account.Interface">ExternalPasswordStorage.DRAFT</tp:dbus-ref>
         interface.</p>
-
     </tp:docstring>
 
     <tp:flags name="Account_Flags" value-prefix="Account_Flag" type="u">
       <tp:docstring>
-        A set of flags representing the status of the Account stored in the Connection Manager.
+        A set of flags representing the status of the Account stored in the
+        Connection Manager.
       </tp:docstring>
 
       <tp:flag suffix="Credentials_Stored" value="1">
@@ -61,9 +61,12 @@
     <property name="Accounts"
       tp:name-for-bindings="Accounts"
       type="a{su}" tp:type="Account_Flags_Map" access="read">
-      <tp:docstring>
-        The set of Accounts stored in this connection manager, and flags
-        indicating their status.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>The set of Accounts stored in this Connection Manager, and flags
+          indicating their status.</p>
+
+        <p>Change notification for this property is provided by the standard
+          D-Bus <code>PropertiesChanged</code> signal.</p>
       </tp:docstring>
     </property>
 
@@ -76,8 +79,8 @@
       <arg direction="in" name="Account_Id"
         type="s">
         <tp:docstring>
-          An account id as returned from <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy">Protocol.IdentifyAccount</tp:dbus-ref>.
+          An account id as returned from
+	  <tp:dbus-ref namespace="ofdT">Protocol.IdentifyAccount</tp:dbus-ref>.
         </tp:docstring>
       </arg>
 
@@ -99,8 +102,8 @@
       <arg direction="in" name="Account_Id"
         type="s">
         <tp:docstring>
-          An account id as returned from <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy">Protocol.IdentifyAccount</tp:dbus-ref>.
+          An account id as returned from
+	  <tp:dbus-ref namespace="ofdT">Protocol.IdentifyAccount</tp:dbus-ref>.
         </tp:docstring>
       </arg>
 
diff --git a/spec/Makefile.am b/spec/Makefile.am
index e8e3e0cc5..767780e59 100644
--- a/spec/Makefile.am
+++ b/spec/Makefile.am
@@ -75,6 +75,7 @@ EXTRA_DIST = \
     Connection_Interface_Cellular.xml \
     Connection_Interface_Client_Types.xml \
     Connection_Interface_Communication_Policy.xml \
+    Connection_Interface_Contact_Blocking.xml \
     Connection_Interface_Contact_Capabilities.xml \
     Connection_Interface_Contact_Groups.xml \
     Connection_Interface_Contact_Info.xml \
diff --git a/spec/all.xml b/spec/all.xml
index fccf75c95..a5644a90f 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,10 +3,10 @@
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
 <tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.21.12</tp:version>
+<tp:version>0.22.0</tp:version>
 
-<tp:copyright>Copyright © 2005-2010 Collabora Limited</tp:copyright>
-<tp:copyright>Copyright © 2005-2010 Nokia Corporation</tp:copyright>
+<tp:copyright>Copyright © 2005-2011 Collabora Limited</tp:copyright>
+<tp:copyright>Copyright © 2005-2011 Nokia Corporation</tp:copyright>
 <tp:copyright>Copyright © 2006 INdT</tp:copyright>
 
 <tp:license xmlns="http://www.w3.org/1999/xhtml">
@@ -56,13 +56,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
     <p>
      On protocols that support contact lists, these interface expose the user's
-     contact lists, along with presence subscription information and contact
-     list groups (if supported).
+     contact lists, along with presence subscription information, contact
+     list groups (if supported), and the ability to block and unblock contacts
+     (if supported).
     </p>
    </tp:docstring>
 
    <xi:include href="Connection_Interface_Contact_List.xml"/>
    <xi:include href="Connection_Interface_Contact_Groups.xml"/>
+   <xi:include href="Connection_Interface_Contact_Blocking.xml"/>
   </tp:section>
 
   <tp:section name="Contact metadata interfaces">