Update telepathy-spec to 0.17.21

28 files changed, 771 insertions, 353 deletions

diff --git a/spec/Account.xml b/spec/Account.xml
index 991dcbda0..9dc34ad1c 100644
--- a/spec/Account.xml
+++ b/spec/Account.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Account"
   xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
-  <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+  <tp:copyright>Copyright © 2008-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
@@ -427,7 +427,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
         The actual presence. If the connection is not online, this should be
         (Connection_Presence_Type_Offline, "", "").
         If the connection is online but does not support the <tp:dbus-ref
-        namespace="org.freedesktop.Telepathy.Connection.Interface">Presence</tp:dbus-ref>
+        namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
         interface, this should be (Connection_Presence_Type_Unset, "", "").
         The account manager is expected to set this by observing signals
         from the Connection.
diff --git a/spec/Account_Manager.xml b/spec/Account_Manager.xml
index 98fe00d9c..6fb9b088c 100644
--- a/spec/Account_Manager.xml
+++ b/spec/Account_Manager.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Account_Manager"
   xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright>Copyright (C) 2008-2009 Collabora Ltd.</tp:copyright>
-  <tp:copyright>Copyright (C) 2008-2009 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+  <tp:copyright>Copyright © 2008-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
diff --git a/spec/Channel.xml b/spec/Channel.xml
index 7b4a7ad8a..2937680bb 100644
--- a/spec/Channel.xml
+++ b/spec/Channel.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Channel" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
-  <tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
-  <tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
+  <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
+  <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2006 INdT</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
diff --git a/spec/Channel_Dispatch_Operation.xml b/spec/Channel_Dispatch_Operation.xml
index 7f61f6f35..6f728c354 100644
--- a/spec/Channel_Dispatch_Operation.xml
+++ b/spec/Channel_Dispatch_Operation.xml
@@ -161,7 +161,7 @@
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>The name of a D-Bus error indicating why the channel closed. If
             no better reason can be found,
-            <code>org.freedesktop.Telepathy.Errors.NotAvailable</code> MAY
+            <code>org.freedesktop.Telepathy.Error.NotAvailable</code> MAY
             be used as a fallback; this means that this error SHOULD NOT be
             given any more specific meaning.</p>
 
diff --git a/spec/Channel_Dispatcher.xml b/spec/Channel_Dispatcher.xml
index c77873db9..af671bdee 100644
--- a/spec/Channel_Dispatcher.xml
+++ b/spec/Channel_Dispatcher.xml
@@ -2,8 +2,8 @@
 <node name="/Channel_Dispatcher"
   xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
 
-  <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
-  <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+  <tp:copyright>Copyright © 2008-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
diff --git a/spec/Channel_Interface_Group.xml b/spec/Channel_Interface_Group.xml
index 490258fcc..9c7e25446 100644
--- a/spec/Channel_Interface_Group.xml
+++ b/spec/Channel_Interface_Group.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Interface_Group" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright>Copyright (C) 2005-2009 Collabora Limited</tp:copyright>
-  <tp:copyright>Copyright (C) 2005-2009 Nokia Corporation</tp:copyright>
-  <tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
+  <tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
+  <tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2006 INdT</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
@@ -241,6 +241,19 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           </tp:rationale>
         </tp:docstring>
       </tp:flag>
+      <tp:flag suffix="Message_Depart" value="8192">
+        <tp:added version="0.17.UNRELEASED"/>
+        <tp:docstring>
+          A message may be sent to the server when calling
+          <tp:member-ref>RemoveMembers</tp:member-ref> on
+          the <tp:member-ref>SelfHandle</tp:member-ref>.
+
+          <tp:rationale>
+            This would be set for XMPP Multi-User Chat or IRC channels,
+            but not for a typical implementation of streamed media calls.
+          </tp:rationale>
+        </tp:docstring>
+      </tp:flag>
     </tp:flags>
 
     <property name="GroupFlags" type="u" tp:type="Channel_Group_Flags"
@@ -950,16 +963,45 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           A string message, which can be blank if desired
         </tp:docstring>
       </arg>
-      <tp:docstring>
-        Requests the removal of contacts from a channel, reject their request
-        for channel membership on the pending local list, or rescind their
-        invitation on the pending remote list. A message may be provided along
-        with the request, which will be sent to the server if supported. See
-        the CHANNEL_GROUP_FLAG_MESSAGE_REMOVE,
-        CHANNEL_GROUP_FLAG_MESSAGE_REJECT and
-        CHANNEL_GROUP_FLAG_MESSAGE_RESCIND
-        <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this
-        message should be provided.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Requests the removal of contacts from a channel, reject their
+          request for channel membership on the pending local list, or
+          rescind their invitation on the pending remote list.</p>
+
+        <p>If the <tp:member-ref>SelfHandle</tp:member-ref> is in a Group,
+          it can be removed via this method, in order to leave the group
+          gracefully. This is the recommended way to leave a chatroom, close
+          or reject a <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Channel.Type">StreamedMedia</tp:dbus-ref>
+          call, and so on.</p>
+
+        <p>Accordingly, connection managers SHOULD support
+          doing this, regardless of the value of
+          <tp:member-ref>GroupFlags</tp:member-ref>.
+          If doing so fails with PermissionDenied, this is considered to a bug
+          in the connection manager, but clients MUST recover by falling back
+          to closing the channel with the <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+          method.</p>
+
+        <p>Removing any contact from the local pending list is always
+          allowed. Removing contacts other than the
+          <tp:member-ref>SelfHandle</tp:member-ref> from the channel's members
+          is allowed if and only if Channel_Group_Flag_Can_Remove is in the
+          <tp:member-ref>GroupFlags</tp:member-ref>,
+          while removing contacts other than the
+          <tp:member-ref>SelfHandle</tp:member-ref> from the remote pending list
+          is allowed if and only if Channel_Group_Flag_Can_Rescind is in the
+          <tp:member-ref>GroupFlags</tp:member-ref>.</p>
+
+        <p>A message may be provided along with the request, which will be
+          sent to the server if supported. See the
+          Channel_Group_Flag_Message_Remove,
+          Channel_Group_Flag_Message_Depart,
+          Channel_Group_Flag_Message_Reject and
+          Channel_Group_Flag_Message_Rescind
+          <tp:member-ref>GroupFlags</tp:member-ref> to see in which cases this
+          message should be provided.</p>
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml
index 82493316f..b69e5b352 100644
--- a/spec/Channel_Interface_Media_Signalling.xml
+++ b/spec/Channel_Interface_Media_Signalling.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Interface_Media_Signalling" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
-  <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
-  <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+  <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+  <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+  <tp:copyright> Copyright © 2006 INdT </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
@@ -120,6 +120,12 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <dt>gtalk-p2p</dt>
         <dd>Google Talk peer-to-peer connectivity establishment should be used,
         as implemented in libjingle 0.3.</dd>
+
+        <dt>ice-udp</dt>
+        <dd>
+          Interactive Connectivity Establishment should be used, as defined by
+          the IETF MMUSIC working group.
+        </dd>
       </dl>
       </tp:docstring>
     </tp:property>
diff --git a/spec/Channel_Interface_Media_Signalling_Future.xml b/spec/Channel_Interface_Media_Signalling_Future.xml
index e1d2d25fb..d908450be 100644
--- a/spec/Channel_Interface_Media_Signalling_Future.xml
+++ b/spec/Channel_Interface_Media_Signalling_Future.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Interface_Media_Signalling_Future"
   xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright> Copyright (C) 2009 Collabora Limited </tp:copyright>
-  <tp:copyright> Copyright (C) 2009 Nokia Corporation </tp:copyright>
+  <tp:copyright> Copyright © 2009 Collabora Limited </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
@@ -22,7 +22,7 @@
   <interface name="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling.FUTURE">
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
     <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.StreamedMedia"/>
-    <tp:requires interface="org.freedesktop.Telepathy.Channel.Type.MediaSignalling"/>
+    <tp:requires interface="org.freedesktop.Telepathy.Channel.Interface.MediaSignalling"/>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>This interface contains functionality which we intend to incorporate
diff --git a/spec/Channel_Interface_Messages.xml b/spec/Channel_Interface_Messages.xml
index 8cdee3c87..c012f2f65 100644
--- a/spec/Channel_Interface_Messages.xml
+++ b/spec/Channel_Interface_Messages.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Interface_Messages"
   xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright>Copyright (C) 2008-2009 Collabora Ltd.</tp:copyright>
-  <tp:copyright>Copyright (C) 2008-2009 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+  <tp:copyright>Copyright © 2008-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
diff --git a/spec/Channel_Interface_Password.xml b/spec/Channel_Interface_Password.xml
index 720849a86..76720a69c 100644
--- a/spec/Channel_Interface_Password.xml
+++ b/spec/Channel_Interface_Password.xml
@@ -1,9 +1,9 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Interface_Password" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   <tp:copyright>
-Copyright (C) 2005, 2006 Collabora Limited
-Copyright (C) 2005, 2006 Nokia Corporation
-Copyright (C) 2006 INdT
+Copyright © 2005-2009 Collabora Limited
+Copyright © 2005-2009 Nokia Corporation
+Copyright © 2006 INdT
   </tp:copyright>
   <tp:license>
     This library is free software; you can redistribute it and/or
diff --git a/spec/Channel_Interface_Tube.xml b/spec/Channel_Interface_Tube.xml
index b2d0f3181..8e6eb6514 100644
--- a/spec/Channel_Interface_Tube.xml
+++ b/spec/Channel_Interface_Tube.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Interface_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
-  <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
   <tp:license>
     This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
@@ -38,10 +38,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       HANDLE_TYPE_CONTACT (for 1-1 communication) or of type
       HANDLE_TYPE_ROOM (to communicate with others in the room
       simultaneously).</p>
+
+      <p>As an exception to the usual handling of capabilities, connection managers
+        for protocols with capability discovery, such as XMPP, SHOULD advertise the
+        capability representing each Tube type that they support
+       (<tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.DBusTube</tp:dbus-ref> and/or
+        <tp:dbus-ref namespace="org.freedesktop.Telepathy">Channel.Type.StreamTube</tp:dbus-ref>)
+        even if no client has indicated via
+        <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>
+        that such a tube is supported.</p>
+
+        <tp:rationale>
+          <p>To lower the barrier entry of new tube application, CM SHOULD accept to offer tubes of any
+            <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">Service</tp:dbus-ref> or
+            <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">ServiceName</tp:dbus-ref>
+            if the contact announced to support tubes.</p>
+        </tp:rationale>
     </tp:docstring>
 
     <property name="Parameters" type="a{sv}" tp:type="String_Variant_Map"
-              access="readwrite" tp:name-for-bindings="Parameters">
+              access="read" tp:name-for-bindings="Parameters">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
         <p>Each tube has a dictionary of arbitrary parameters. Parameters are
           commonly used to bootstrap legacy protocols where you can't
@@ -60,11 +79,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           <code>{'u': 'username', 'p': 'password', 'path': 'path'}</code></p>
         <p>When requesting a channel with
           <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.CreateChannel</tp:dbus-ref>,
-          this property MAY be included in the request. If it is not included in
-          the request, the connection manager MUST consider the property to be
-          empty. This property MAY be changed after the channel creation when
-          the tube is in the state Not_Offered. If the tube is in another
-          state, changing this property MUST fail without side effects.</p>
+          this property MUST NOT be included in the request. This property is undefined until the tube is offered
+          (using <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.StreamTube.DRAFT">OfferStreamTube</tp:dbus-ref>
+          or <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Type.DBusTube.DRAFT">OfferDBusTube</tp:dbus-ref>).
+          Once it has been offered, this property MUST NOT change.</p>
+        <p>When receiving an incoming tube, this property is immutable and so advertised in the
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection.Interface.Requests.NewChannels</tp:dbus-ref>
+          signal.</p>
       </tp:docstring>
     </property>
 
diff --git a/spec/Channel_Request.xml b/spec/Channel_Request.xml
index bf1bd38c2..3706bdb60 100644
--- a/spec/Channel_Request.xml
+++ b/spec/Channel_Request.xml
@@ -2,8 +2,8 @@
 <node name="/Channel_Request"
   xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
 
-  <tp:copyright>Copyright (C) 2008 Collabora Ltd.</tp:copyright>
-  <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Collabora Ltd.</tp:copyright>
+  <tp:copyright>Copyright © 2008-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
@@ -105,7 +105,7 @@
       </tp:docstring>
 
       <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Errors.NotAvailable">
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
           <tp:docstring>
             This method has already been called, so it is no longer
             available. Stop calling it.
@@ -144,7 +144,7 @@
 
         <p>If <tp:member-ref>Failed</tp:member-ref> is emitted in response to
           this method, the error SHOULD be
-          <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p>
+          <code>org.freedesktop.Telepathy.Error.Cancelled</code>.</p>
 
         <p>If the channel has already been dispatched to a handler, then
           it's too late to call this method, and the channel request will
diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml
index 0b166bb16..204ecf11d 100644
--- a/spec/Channel_Type_Contact_Search.xml
+++ b/spec/Channel_Type_Contact_Search.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Type_Contact_Search" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
-  <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
-  <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+  <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+  <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+  <tp:copyright> Copyright © 2006 INdT </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
@@ -18,135 +18,394 @@ Lesser General Public License for more details.</p>
 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.Channel.Type.ContactSearch"
-    tp:causes-havoc='not well-tested'>
+  <interface name="org.freedesktop.Telepathy.Channel.Type.ContactSearch.DRAFT"
+    tp:causes-havoc='experimental'>
     <tp:requires interface="org.freedesktop.Telepathy.Channel"/>
 
-    <tp:struct name="Search_Key_Info">
-      <tp:docstring>A struct representing details on search strings.</tp:docstring>
-      <tp:member type="b" name="Is_Mandatory">
-        <tp:docstring>Booleans indicating if the search key is mandatory.
-          </tp:docstring>
-      </tp:member>
-      <tp:member type="g" name="Type_Signature">
-        <tp:docstring>The type signature of the value for this search key.
-          </tp:docstring>
-      </tp:member>
-    </tp:struct>
+    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+      <p>A channel type for searching server-stored user directories. A new
+        channel should be requested by a client for each search attempt, and
+        closed when the search is completed or the required result has been
+        found in order to free unused handles.</p>
 
-    <tp:mapping name="Search_Key_Info_Map">
-      <tp:docstring>A dictionary mapping string search key names to its search details.
-        </tp:docstring>
-      <tp:member type="s" name="Term"/>
-      <tp:member type="(bg)" tp:type="Search_Key_Info" name="Details"/>
-    </tp:mapping>
+      <p>Before searching, the
+        <tp:member-ref>AvailableSearchKeys</tp:member-ref> property should be
+        inspected to determine the valid search keys which can be provided to
+        the <tp:member-ref>Search</tp:member-ref> method. A search request is
+        then started by providing some of these terms to the Search method, and
+        the <tp:member-ref>SearchState</tp:member-ref> will change from
+        <code>Not_Started</code> to <code>In_Progress</code>.  As results are
+        returned by the server, the
+        <tp:member-ref>SearchResultReceived</tp:member-ref> signal is emitted
+        for each contact found; when the search is complete, the search state
+        will be set to <code>Completed</code>. If the search fails after Search
+        has been called, the state will change to <code>Failed</code>.  A
+        running search can be cancelled by calling
+        <tp:member-ref>Stop</tp:member-ref>.</p>
+
+      <p>The client should call the channel's <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Channel">Close</tp:dbus-ref>
+        method when it is finished with the channel, so that any handles held
+        only by the channel can be released.</p>
+
+      <p>Each channel can only be used for a single search; a new channel
+        should be requested for each subsequent search. Connection managers
+        MUST support multiple ContactSearch channels being open at once (even
+        to the same server, if applicable).</p>
+
+      <p>It does not make sense to request this channel type using <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>;
+        clients SHOULD request channels of this type using
+        <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">CreateChannel</tp:dbus-ref>
+        instead.</p>
+
+      <tp:rationale>
+        <p>A contact search channel that is already in use for a different
+          search isn't useful.</p>
+      </tp:rationale>
+    </tp:docstring>
 
-    <method name="GetSearchKeys" tp:name-for-bindings="Get_Search_Keys">
-      <arg direction="out" type="s">
-        <tp:docstring>
-          A string with any instructions from the server
-        </tp:docstring>
-      </arg>
-      <arg direction="out" type="a{s(bg)}" tp:type="Search_Key_Info_Map">
-        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-          A dictionary mapping string search key names to its search details.
-        </tp:docstring>
-      </arg>
-      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>Returns any instructions from the server along with a dictionary of
-        search key names to their types, and a boolean indicating if the key is
-        mandatory. The following well-known search key names should be used
-        where appropriate:</p>
-        <dl>
-          <dt>s:first</dt><dd>The desired contact's given name</dd>
-          <dt>s:last</dt><dd>The desired contact's family name</dd>
-          <dt>s:nick</dt><dd>The desired contact's nickname</dd>
-          <dt>s:email</dt><dd>The e-mail address of the desired contact</dd>
-        </dl>
-      </tp:docstring>
-      <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.NotAvailable"/>
-      </tp:possible-errors>
-    </method>
     <tp:enum name="Channel_Contact_Search_State" type="u">
-      <tp:enumvalue suffix="Before" value="0">
+      <tp:enumvalue suffix="Not_Started" value="0">
         <tp:docstring>The search has not started</tp:docstring>
       </tp:enumvalue>
-      <tp:enumvalue suffix="During" value="1">
+      <tp:enumvalue suffix="In_Progress" value="1">
         <tp:docstring>The search is in progress</tp:docstring>
       </tp:enumvalue>
-      <tp:enumvalue suffix="After" value="2">
+      <tp:enumvalue suffix="Completed" value="2">
         <tp:docstring>The search has been completed</tp:docstring>
       </tp:enumvalue>
+      <tp:enumvalue suffix="Failed" value="3">
+        <tp:docstring>The search has failed</tp:docstring>
+      </tp:enumvalue>
     </tp:enum>
-    <method name="GetSearchState" tp:name-for-bindings="Get_Search_State">
-      <arg direction="out" type="u" tp:type="Channel_Contact_Search_State">
-        <tp:docstring>The search state represented as one of the values of
-          ChannelContactSearchState</tp:docstring>
+
+    <property name="SearchState" tp:name-for-bindings="Search_State"
+      access="read" type="u" tp:type="Channel_Contact_Search_State">
+      <tp:docstring>
+        The current state of this search channel object. Change notification
+        is via <tp:member-ref>SearchStateChanged</tp:member-ref>.
+      </tp:docstring>
+    </property>
+
+    <signal name="SearchStateChanged"
+      tp:name-for-bindings="Search_State_Changed">
+      <arg name="State" type="u" tp:type="Channel_Contact_Search_State">
+        <tp:docstring>The new search state</tp:docstring>
+      </arg>
+      <arg name="Error" type="s" tp:type="DBus_Error_Name">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          If the new state is <code>Failed</code>, the name of a D-Bus error
+          describing what went wrong. Otherwise, the empty string.
+        </tp:docstring>
+      </arg>
+      <arg name="Details" type="a{sv}" tp:type="String_Variant_Map">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>Additional information about the state transition, which may
+            include the following well-known keys:</p>
+
+          <dl>
+            <dt>debug-message (s)</dt>
+            <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>
+          </dl>
+
+          <tp:rationale>
+            <p>This argument allows for future extensions. For instance,
+              if moving to state <code>Failed</code> because the server
+              rejected one of our search terms, we could define a key
+              that indicates which terms were invalid.</p>
+          </tp:rationale>
+        </tp:docstring>
       </arg>
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Emitted when the <tp:member-ref>SearchState</tp:member-ref> property
+          changes. The implementation MUST NOT make transitions other than the
+          following:</p>
+
+        <ul>
+          <li><code>Not_Started</code> → <code>In_Progress</code></li>
+          <li><code>In_Progress</code> → <code>Completed</code></li>
+          <li><code>In_Progress</code> → <code>Failed</code></li>
+        </ul>
+      </tp:docstring>
+    </signal>
+
+    <tp:simple-type name="Contact_Search_Key" type="s">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Any of the following search keys, with the indicated result for
+          the search:</p>
+
+        <dl>
+          <dt>The empty string</dt>
+          <dd>Search for the search term in some implementation-dependent
+            set of fields, using an implementation-dependent algorithm
+            (e.g. searching for each word mentioned)
+            <tp:rationale>
+              The "one big search box" approach to searching, as is familiar
+              from Google. The Sametime plugin to Pidgin appears to search in
+              this way.
+            </tp:rationale>
+          </dd>
+
+          <dt>A <tp:type>VCard_Field</tp:type></dt>
+          <dd>Search for the search term in fields matching that name (for
+            instance, <code>nickname</code> would search nicknames, and
+            <code>tel</code> would search any available phone number,
+            regardless of its work/home/mobile/... status).</dd>
+
+          <dt>A <tp:type>VCard_Field</tp:type> followed by
+            "<code>;</code>" and a
+            <tp:type>VCard_Type_Parameter</tp:type> of the form
+            "<code>type=...</code>"</dt>
+          <dd>Search for the search term in fields of that name and type
+            only (for instance, <code>tel;type=mobile</code>).</dd>
+
+          <dt><code>x-telepathy-identifier</code></dt>
+          <dd>Search for contacts whose identifier in the IM protocol
+            matches the search term (e.g. contains it as a substring)
+            <tp:rationale>
+              Otherwise, starting a search by identifier would require the UI
+              to know the vCard field name corresponding to identifiers in
+              this protocol, which might be non-standard (like
+              <code>x-jabber</code>) or not exist at all.
+            </tp:rationale>
+          </dd>
+
+          <dt><code>x-gender</code></dt>
+          <dd>For the search term "male" or "female", search only for contacts
+            listed as male or female, respectively. The results for other
+            search terms are undefined; it is likely that contacts with
+            unspecified gender will only be matched if this search key
+            is omitted from the request.
+            <tp:rationale>
+              Examples in XEP-0055 suggest this usage, and at least Gadu-Gadu
+              also supports limiting search results by gender.
+            </tp:rationale>
+          </dd>
+
+          <dt><code>x-n-family</code></dt>
+          <dd>Search for the search term in contacts' family names
+            (the first component of the vCard field <code>n</code>).
+            <tp:rationale>
+              Gadu-Gadu and TOC seem to support this mode of searching.
+            </tp:rationale>
+          </dd>
+
+          <dt><code>x-n-given</code></dt>
+          <dd>Search for the search term in contacts' given names
+            (the second component of the vCard field <code>n</code>).
+            <tp:rationale>
+              As for <code>x-n-family</code>.
+            </tp:rationale>
+          </dd>
+
+          <dt><code>x-online</code></dt>
+          <dd>For the search term "yes", search only for contacts who are
+            currently online. The results for other search terms are undefined.
+            <tp:rationale>Gadu-Gadu appears to support this.</tp:rationale>
+          </dd>
+
+          <dt><code>x-adr-locality</code></dt>
+          <dd>Search for the search term as a locality or city (the fourth
+            component of the vCard field <code>adr</code>).
+            <tp:rationale>
+              Gadu-Gadu and TOC appear to support this.
+            </tp:rationale>
+          </dd>
+
+          <dt><code>x-search-offset</code></dt>
+          <dd>
+            <p>For protocols that support paging results, the offset from the
+              start of the results that should be returned, i.e. the number of
+              contacts from the beginning that should be omitted.</p>
+
+            <p>For example, if the search terms match 50 contacts, this key
+              is set to <code>"20"</code> and <code>x-search-limit</code>
+              is set to <code>"10"</code>, then the ten contacts from the 21st
+              to the 30th should be returned.</p>
+
+            <p>Connection managers for protocols which do not natively support
+              restricting the number of results returned MUST NOT support
+              either this term or <code>x-search-limit</code>: all results
+              should be signalled, and the client can provide its own paging as
+              desired.</p>
+          </dd>
+
+          <dt><code>x-search-limit</code></dt>
+          <dd>For protocols that support limiting results, the maximum number
+            of results that should be returned.  For example, if the search
+            terms match <i>Antonius</i>, <i>Bridget</i> and <i>Charles</i> and
+            this key is set to <code>"2"</code>, the search service SHOULD only
+            return <i>Antonius</i> and <i>Bridget</i>.</dd>
+        </dl>
+      </tp:docstring>
+    </tp:simple-type>
+
+    <property name="AvailableSearchKeys" type="as" access="read"
+      tp:name-for-bindings="Available_Search_Keys">
       <tp:docstring>
-        Returns the current state of this search channel object.
+        The set of search keys supported by this channel. Example values
+        include [""] (for protocols where several address fields are
+        implicitly searched) or ["x-n-given", "x-n-family", "nickname",
+        "email"] (for XMPP XEP-0055, without extensibility via Data Forms).
+        This property cannot change during the lifetime of a channel.
+
+        <tp:rationale>
+          It can be in the <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">NewChannels</tp:dbus-ref>
+          signal for round-trip reduction.
+        </tp:rationale>
       </tp:docstring>
-    </method>
-    <method name="Search">
-      <arg direction="in" name="Terms" type="a{sv}" tp:type="String_Variant_Map">
+    </property>
+
+    <tp:mapping name="Contact_Search_Map">
+      <tp:docstring>A map from search keys to search terms.</tp:docstring>
+      <tp:member name="Key" type="s" tp:type="Contact_Search_Key">
+        <tp:docstring>
+          The search key to match against
+        </tp:docstring>
+      </tp:member>
+
+      <tp:member name="Term" type="s">
+        <tp:docstring>
+          The term or terms to be searched for in the search key; depending on
+          the protocol and the server implementation, this may be matched by
+          exact or approximate equality, substring matching, word matching
+          or any other matching algorithm
+        </tp:docstring>
+      </tp:member>
+    </tp:mapping>
+
+    <method name="Search" tp:name-for-bindings="Search">
+      <arg direction="in" name="Terms"
+        type="a{ss}" tp:type="Contact_Search_Map">
         <tp:docstring>
           A dictionary mapping search key names to the desired values
         </tp:docstring>
       </arg>
       <tp:docstring>
-        Send a request to start a search for contacts on this connection. A
-        valid search request will cause the SearchStateChanged signal to be
-        emitted with the status CHANNEL_CONTACT_SEARCH_STATE_DURING.
+        Send a request to start a search for contacts on this connection. This
+        may only be called while the <tp:member-ref>SearchState</tp:member-ref>
+        is Not_Started; a valid search request will cause the
+        <tp:member-ref>SearchStateChanged</tp:member-ref> signal to be emitted
+        with the state In_Progress.
       </tp:docstring>
       <tp:possible-errors>
-        <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+            The <tp:member-ref>SearchState</tp:member-ref> is no longer
+            Not_Started, so this method is no longer available.
+          </tp:docstring>
+        </tp:error>
+        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument">
+          <tp:docstring>
+            The search terms included something this connection manager cannot
+            search for.
+          </tp:docstring>
+        </tp:error>
         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
-        <tp:error name="org.freedesktop.Telepathy.Error.InvalidArgument"/>
       </tp:possible-errors>
     </method>
+
+    <method name="Stop" tp:name-for-bindings="Stop">
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Stop the current search. This may not be called while the
+          <tp:member-ref>SearchState</tp:member-ref> is Not_Started. If called
+          while the SearchState is In_Progress,
+          <tp:member-ref>SearchStateChanged</tp:member-ref> will be emitted,
+          with the state Failed and the error
+          <code>org.freedesktop.Telepathy.Errors.Cancelled</code>.</p>
+
+        <p>Calling this method on a search in state Completed or Failed
+          succeeds, but has no effect.</p>
+
+        <tp:rationale>
+          <p>Specifying Stop to succeed when the search has finished means that
+            clients who call Stop just before receiving
+            <tp:member-ref>SearchStateChanged</tp:member-ref> don't have to
+            handle a useless error.</p>
+        </tp:rationale>
+
+        <p>Depending on the protocol, the connection manager may not be
+          able to prevent the server from sending further results after this
+          method returns; if this is the case, it MUST ignore any further
+          results.</p>
+      </tp:docstring>
+      <tp:possible-errors>
+        <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
+          <tp:docstring>
+            The <tp:member-ref>SearchState</tp:member-ref> is Not_Started, so
+            this method is not yet available.
+          </tp:docstring>
+        </tp:error>
+      </tp:possible-errors>
+    </method>
+
     <signal name="SearchResultReceived"
       tp:name-for-bindings="Search_Result_Received">
       <arg name="Contact" type="u" tp:type="Contact_Handle">
-        <tp:docstring>An integer handle for the contact</tp:docstring>
+        <tp:docstring>An integer handle for the contact, which will remain
+          valid at least until this Channel closes</tp:docstring>
       </arg>
-      <arg name="Values" type="a{sv}" tp:type="String_Variant_Map">
-        <tp:docstring>A dictionary mapping search key names to values for this contact</tp:docstring>
+      <arg name="Info" type="a(sasas)" tp:type="Contact_Info_Field[]">
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>An array of fields representing information about this
+            contact, in the same format used in the <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Connection.Interface">ContactInfo.DRAFT</tp:dbus-ref>
+            interface. It is possible that a separate call to <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Connection.Interface.ContactInfo.DRAFT">RequestContactInfo</tp:dbus-ref>
+            would return more information than this signal provides.</p>
+
+          <p>This array SHOULD include the <code>x-telepathy-identifier</code>
+            field, whose values matches the result of calling <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Connection">InspectHandles</tp:dbus-ref>
+            on the Contact handle.</p>
+
+          <tp:rationale>
+            <p>UIs will most likely want to show the identifier to the user;
+              while they could do this by inspecting the signalled handle,
+              including it in this signal is cheap and removes a roundtrip to
+              look it up.</p>
+          </tp:rationale>
+        </tp:docstring>
       </arg>
       <tp:docstring>
         Emitted when a search result is received from the server.
       </tp:docstring>
     </signal>
-    <signal name="SearchStateChanged"
-      tp:name-for-bindings="Search_State_Changed">
-      <arg name="State" type="u" tp:type="Channel_Contact_Search_State">
-        <tp:docstring>An integer representing the new search state</tp:docstring>
-      </arg>
+
+    <property name="Server" tp:name-for-bindings="Server"
+      type="s" access="read">
       <tp:docstring>
-        Emitted when the search state (as returned by the GetSearchState
-        method) changes.
+        <p>For protocols which support searching for contacts on multiple
+          servers with different DNS names (like XMPP), the DNS name of the
+          server being searched by this channel, e.g.
+          "characters.shakespeare.lit".  Otherwise, the empty string.</p>
+
+        <tp:rationale>
+          <p>XEP 0055 defines a mechanism for XMPP clients to search services
+            of their choice for contacts, such as users.jabber.org (the "Jabber
+            User Directory").</p>
+        </tp:rationale>
+
+        <p>This property cannot change during the lifetime of the channel.
+          This property SHOULD be in the Allowed_Properties of a
+          <tp:type>Requestable_Channel_Class</tp:type> if and only if the
+          protocol supports querying multiple different servers;
+          implementations SHOULD use a sensible default if possible if this
+          property is not specified in a channel request.</p>
+
+        <tp:rationale>
+          <p>This allows a client to perform searches on a protocol it knows
+            nothing about without requiring the user to guess a valid server's
+            hostname.</p>
+        </tp:rationale>
       </tp:docstring>
-    </signal>
-    <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-    <p>A channel type for searching server-stored user directories. A new channel
-    should be requested by a client for each search attempt, and it should be
-    closed when the search is completed or the required result has been found
-    in order to free unused handles. The search can be cancelled at any time
-    by calling the channel Close method, although depending upon the protocol
-    the connection manager may not be able to prevent the server from sending
-    further results.</p>
-
-    <p>Before searching, the GetSearchKeys method should be used to discover any
-    instructions sent by the server, and the valid search keys which can be
-    provided to the Search method. A search request is then started by
-    providing some of these terms to the Search method, and the search status
-    will be set to CHANNEL_CONTACT_SEARCH_STATE_DURING. When results are
-    returned by the server, the SearchResultReceived signal is emitted for each
-    contact found, and when the search is complete, the search status will be
-    set to CHANNEL_SEARCH_STATE_AFTER.</p>
-    </tp:docstring>
+    </property>
+
   </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Channel_Type_DBus_Tube.xml b/spec/Channel_Type_DBus_Tube.xml
index 2671a17ad..513d77caa 100644
--- a/spec/Channel_Type_DBus_Tube.xml
+++ b/spec/Channel_Type_DBus_Tube.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Type_DBus_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
-  <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
   <tp:license>
     This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
@@ -58,6 +58,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
       <tp:docstring>
         Offers a D-Bus tube providing the service specified.
       </tp:docstring>
+      <arg direction="in" name="parameters" type="a{sv}"
+        tp:type="String_Variant_Map">
+        <tp:docstring>
+          The dictionary of arbitrary
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref>
+          to send with the tube offer.
+        </tp:docstring>
+      </arg>
       <arg direction="out" name="address" type="s">
         <tp:docstring>
           The string describing the address of the private bus. The client
diff --git a/spec/Channel_Type_File_Transfer.xml b/spec/Channel_Type_File_Transfer.xml
index c88834c1d..7795f9df4 100644
--- a/spec/Channel_Type_File_Transfer.xml
+++ b/spec/Channel_Type_File_Transfer.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Type_File_Transfer" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   <tp:copyright>
-    Copyright (C) 2008 Collabora Limited
+    Copyright © 2008-2009 Collabora Limited
   </tp:copyright>
   <tp:license xmlns="http://www.w3.org/1999/xhtml">
     <p>This library is free software; you can redistribute it and/or
@@ -76,6 +76,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <p>The File channel type may be requested for handles of type
       HANDLE_TYPE_CONTACT. If the channel is requested for any other
       handle type then the behaviour is undefined.</p>
+
+      <p>Connection managers SHOULD NOT advertise support for file transfer to
+        other contacts unless it has been indicated by a call to
+        <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>.
+      </p>
+      <tp:rationale>
+        <p>People would send us files, and it would always fail. That would be silly.</p>
+      </tp:rationale>
     </tp:docstring>
 
     <property name="State" type="u" tp:type="File_Transfer_State"
diff --git a/spec/Channel_Type_Room_List.xml b/spec/Channel_Type_Room_List.xml
index 10ccac606..4170fce3a 100644
--- a/spec/Channel_Type_Room_List.xml
+++ b/spec/Channel_Type_Room_List.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Type_Room_List" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
-  <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
-  <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+  <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+  <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+  <tp:copyright> Copyright © 2006 INdT </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
diff --git a/spec/Channel_Type_Stream_Tube.xml b/spec/Channel_Type_Stream_Tube.xml
index b64f4a032..060cd0bb0 100644
--- a/spec/Channel_Type_Stream_Tube.xml
+++ b/spec/Channel_Type_Stream_Tube.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Type_Stream_Tube" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright>Copyright (C) 2008 Collabora Limited</tp:copyright>
-  <tp:copyright>Copyright (C) 2008 Nokia Corporation</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Collabora Limited</tp:copyright>
+  <tp:copyright>Copyright © 2008-2009 Nokia Corporation</tp:copyright>
   <tp:license>
     This library is free software; you can redistribute it and/or
 modify it under the terms of the GNU Lesser General Public
@@ -66,6 +66,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
           specified in the documentation for the Socket_Access_Control enum.
         </tp:docstring>
       </arg>
+      <arg direction="in" name="parameters" type="a{sv}"
+        tp:type="String_Variant_Map">
+        <tp:docstring>
+          The dictionary of arbitrary
+          <tp:dbus-ref namespace="org.freedesktop.Telepathy.Channel.Interface.Tube.DRAFT">Parameters</tp:dbus-ref>
+          to send with the tube offer.
+        </tp:docstring>
+      </arg>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.NetworkError"/>
         <tp:error name="org.freedesktop.Telepathy.Error.NotAvailable">
diff --git a/spec/Channel_Type_Streamed_Media.xml b/spec/Channel_Type_Streamed_Media.xml
index b89065b48..701c8a515 100644
--- a/spec/Channel_Type_Streamed_Media.xml
+++ b/spec/Channel_Type_Streamed_Media.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Type_Streamed_Media" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright> Copyright (C) 2005-2008 Collabora Limited </tp:copyright>
-  <tp:copyright> Copyright (C) 2005-2008 Nokia Corporation </tp:copyright>
-  <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+  <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+  <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+  <tp:copyright> Copyright © 2006 INdT </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
@@ -422,6 +422,13 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           connections (as implemented in libjingle 0.3) to traverse NATs.
         </tp:docstring>
       </tp:flag>
+      <tp:flag suffix="NAT_Traversal_ICE_UDP" value="16">
+        <tp:docstring>
+          The handle is capable of establishing ICE UDP peer-to-peer
+          connections (as defined by the IETF MMUSIC working group) to traverse
+          NATs.
+        </tp:docstring>
+      </tp:flag>
     </tp:flags>
 
   </interface>
diff --git a/spec/Channel_Type_Streamed_Media_Future.xml b/spec/Channel_Type_Streamed_Media_Future.xml
index 2421ed682..fa8a01530 100644
--- a/spec/Channel_Type_Streamed_Media_Future.xml
+++ b/spec/Channel_Type_Streamed_Media_Future.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Type_Streamed_Media_Future"
   xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright> Copyright (C) 2009 Collabora Limited </tp:copyright>
-  <tp:copyright> Copyright (C) 2009 Nokia Corporation </tp:copyright>
+  <tp:copyright> Copyright © 2009 Collabora Limited </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
diff --git a/spec/Channel_Type_Text.xml b/spec/Channel_Type_Text.xml
index 5c28dce8f..f5828a40b 100644
--- a/spec/Channel_Type_Text.xml
+++ b/spec/Channel_Type_Text.xml
@@ -1,8 +1,8 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Type_Text" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
-  <tp:copyright> Copyright (C) 2005, 2006 Collabora Limited </tp:copyright>
-  <tp:copyright> Copyright (C) 2005, 2006 Nokia Corporation </tp:copyright>
-  <tp:copyright> Copyright (C) 2006 INdT </tp:copyright>
+  <tp:copyright> Copyright © 2005-2009 Collabora Limited </tp:copyright>
+  <tp:copyright> Copyright © 2005-2009 Nokia Corporation </tp:copyright>
+  <tp:copyright> Copyright © 2006 INdT </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
diff --git a/spec/Channel_Type_Tubes.xml b/spec/Channel_Type_Tubes.xml
index f6829b5da..925ae1bed 100644
--- a/spec/Channel_Type_Tubes.xml
+++ b/spec/Channel_Type_Tubes.xml
@@ -1,7 +1,7 @@
 <?xml version="1.0" ?>
 <node name="/Channel_Type_Tubes" xmlns:tp="http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0">
   <tp:copyright>
-    Copyright (C) 2007-2008 Collabora Limited
+    Copyright © 2007-2009 Collabora Limited
   </tp:copyright>
   <tp:license>
     This library is free software; you can redistribute it and/or
diff --git a/spec/Client_Handler.xml b/spec/Client_Handler.xml
index 59c253b28..b29ffacdc 100644
--- a/spec/Client_Handler.xml
+++ b/spec/Client_Handler.xml
@@ -238,7 +238,7 @@
         <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
           <p>The name of the D-Bus error with which the request failed.</p>
 
-          <p>If this is <code>org.freedesktop.Telepathy.Errors.NotYours</code>,
+          <p>If this is <code>org.freedesktop.Telepathy.Error.NotYours</code>,
             this indicates that the request succeeded, but all the resulting
             channels were given to some other handler.</p>
         </tp:docstring>
diff --git a/spec/Connection.xml b/spec/Connection.xml
index 97a3c4c70..ec0cc2e4b 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -970,7 +970,8 @@ USA.</p>
 
     <p>As well as the methods and signatures below, arbitrary interfaces may be
     provided by the Connection object to represent extra connection-wide
-    functionality, such as the Connection.Interface.Presence for receiving and
+    functionality, such as the Connection.Interface.SimplePresence for
+    receiving and
     reporting presence information, and Connection.Interface.Aliasing for
     connections where contacts may set and change an alias for themselves.
     These interfaces can be discovered using the
diff --git a/spec/Connection_Interface_Avatars.xml b/spec/Connection_Interface_Avatars.xml
index 7ef26afd8..acc44de8c 100644
--- a/spec/Connection_Interface_Avatars.xml
+++ b/spec/Connection_Interface_Avatars.xml
@@ -179,6 +179,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           same order as the given array of contact handles
         </tp:docstring>
       </arg>
+      <tp:deprecated version="0.15.5">Use GetKnownAvatarTokens
+        instead.</tp:deprecated>
       <tp:docstring>
         Get the unique tokens for all of the given contacts' avatars.
 
@@ -244,6 +246,8 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         unknown
         </tp:docstring>
       </arg>
+      <tp:deprecated version="0.15.5">Use RequestAvatars
+        instead.</tp:deprecated>
       <tp:docstring>
         Request the avatar for a given contact. Using this method in new
         Telepathy clients is deprecated; use RequestAvatars instead.
diff --git a/spec/Connection_Interface_Contact_Info.xml b/spec/Connection_Interface_Contact_Info.xml
index e7b033bf1..a9d086a94 100644
--- a/spec/Connection_Interface_Contact_Info.xml
+++ b/spec/Connection_Interface_Contact_Info.xml
@@ -31,28 +31,48 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         </tp:docstring>
       </tp:member>
       <tp:member type="as" name="Parameters">
-        <tp:docstring>
-          A list of (lowercased) vCard type parameters applicable to this field.
-          For example, a contact's preferred home address would have parameters
-          'home' and 'pref'.
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>A list of vCard type parameters applicable to this field, with their
+            values. The type parameter names, and any values that are
+            case-insensitive in vCard, MUST be in lower case. For example, a
+            contact's preferred home address would have parameters
+            'type=home' and 'type=pref'.</p>
 
           <tp:rationale>
-            This is a list of strings rather than a bitwise OR of enum members
-            because vCard type parameters are essentially arbitrary strings.
+            The type parameter 'type' is likely to be the most common, but
+            there can be others, such as 'language=en'.
+          </tp:rationale>
+
+          <p>Characters which are required to be escaped in vCard type
+            parameters should not be escaped in this list. For instance,
+            a field "X-FOO;SEMICOLON=\;:bar" in a vCard would become
+            ('x-foo', ['semicolon=;'], ['bar']) in this interface.</p>
+
+          <tp:rationale>
+            This avoids Telepathy UIs having to understand the escaping and
+            unescaping rules for vCards. The type parameter name is not
+            allowed (by RFC 2425) to contain an '=' character, so no ambiguity
+            is introduced.
           </tp:rationale>
         </tp:docstring>
       </tp:member>
       <tp:member type="as" name="Field_Value">
-        <tp:docstring>
-          For unstructured vCard fields (such as 'fn', a formatted name
-          field), a single-element array containing the field's value; for
-          structured fields (such as 'adr', an address field), an array
-          corresponding to the semicolon-separated elements of the field (with
-          empty strings for empty elements).  A vCard field with multiple
-          comma-separated values should be represented by several
-          <tp:type>Contact_Info_Field</tp:type>s.  Characters which are
-          required to be escaped in vCard values, such as semi-colons, should
-          not be escaped in this list.
+        <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+          <p>For unstructured vCard fields (such as 'fn', a formatted name
+            field), a single-element array containing the field's value.</p>
+
+          <p>For structured fields (such as 'adr', an address field), an array
+            corresponding to the semicolon-separated elements of the field (with
+            empty strings for empty elements).</p>
+
+          <p>A vCard field with multiple comma-separated values, such as
+            'nickname', should be represented by several
+            <tp:type>Contact_Info_Field</tp:type>s.</p>
+
+          <p>Characters which are required to be escaped in vCard values, such as
+            semi-colons and newlines, should not be escaped in this list (e.g. if
+            a value contains a newline, the data passed over D-Bus should
+            contain a literal newline character).</p>
 
           <tp:rationale>
             An earlier draft of this interface split structured vCard fields
@@ -103,7 +123,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
    BEGIN:vCard
    VERSION:3.0
    FN:Wee Ninja
-   N:Ninja;Wee;;;-san
+   N;LANGUAGE=ja:Ninja;Wee;;;-san
    ORG:Collabora, Ltd.;Human Resources\; Company Policy Enforcement
    ADR;TYPE=WORK,POSTAL,PARCEL:;;11 Kings Parade;Cambridge;Cambridgeshire
     ;CB2 1SJ;UK
@@ -111,6 +131,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
    EMAIL;TYPE=INTERNET,PREF:wee.ninja@collabora.co.uk
    EMAIL;TYPE=INTERNET:wee.ninja@example.com
    URL:http://www.thinkgeek.com/geektoys/plush/8823/
+   NICKNAME:HR Ninja,Enforcement Ninja
    END:vCard</pre>
 
         <p>would be represented by (in Python-like syntax):</p>
@@ -118,15 +139,17 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <pre>
 [
   ('fn', [], ['Wee Ninja']),
-  ('n', [], ['Ninja', 'Wee', '', '', '-san']),
+  ('n', ['language=ja'], ['Ninja', 'Wee', '', '', '-san']),
   ('org', [], ['Collabora, Ltd.', 'Human Resources; Company Policy Enforcement']),
-  ('adr', ['work','postal','parcel'], ['','','11 Kings Parade','Cambridge',
-                                       'Cambridgeshire','CB2 1SJ','UK']),
-  ('tel', ['voice','work'], ['+44 1223 362967']),
-  ('tel', ['voice','work'], ['+44 7700 900753']),
-  ('email', ['internet','pref'], ['wee.ninja@collabora.co.uk']),
-  ('email', ['internet'], ['wee.ninja@example.com']),
+  ('adr', ['type=work','type=postal','type=parcel'],
+   ['','','11 Kings Parade','Cambridge', 'Cambridgeshire','CB2 1SJ','UK']),
+  ('tel', ['type=voice','type=work'], ['+44 1223 362967']),
+  ('tel', ['type=voice','type=work'], ['+44 7700 900753']),
+  ('email', ['type=internet','type=pref'], ['wee.ninja@collabora.co.uk']),
+  ('email', ['type=internet'], ['wee.ninja@example.com']),
   ('url', [], ['http://www.thinkgeek.com/geektoys/plush/8823/']),
+  ('nickname', [], ['HR Ninja']),
+  ('nickname', [], ['Enforcement Ninja'])
 ]</pre>
       </tp:docstring>
     </tp:struct>
@@ -267,11 +290,28 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       </tp:enumvalue>
     </tp:enum>
 
+    <tp:simple-type name="VCard_Field" type="s">
+      <tp:docstring>
+        A string naming a field in a vCard, such as "fn" or "adr". Although
+        these are case-insensitive in RFC 2425, in Telepathy they MUST be
+        normalized to lower case. In the terminology of RFC 2425 this is
+        called a "type name", and corresponds to the "name" production given
+        in the ABNF.
+      </tp:docstring>
+    </tp:simple-type>
+
+    <tp:simple-type name="VCard_Type_Parameter" type="s">
+      <tp:docstring>
+        A type parameter as defined by RFC 2426, such as "type=cell" or
+        "language=en".
+      </tp:docstring>
+    </tp:simple-type>
+
     <property name="ContactInfoFlags" type="u" access="read"
       tp:type="Contact_Info_Flag" tp:name-for-bindings="Contact_Info_Flags">
       <tp:docstring>
-        An integer representing the bitwise-OR of flags on this channel. This
-        property should be constant over the lifetime of a connection.
+        An integer representing the bitwise-OR of flags on this connection.
+        This property should be constant over the lifetime of a connection.
       </tp:docstring>
     </property>
 
@@ -280,11 +320,11 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         may be passed to <tp:member-ref>SetContactInfo</tp:member-ref> on this
         Connection.</tp:docstring>
 
-      <tp:member type="s" name="Name">
+      <tp:member type="s" name="Name" tp:type="VCard_Field">
         <tp:docstring>A vCard field name, such as 'tel'.</tp:docstring>
       </tp:member>
 
-      <tp:member type="as" name="Parameters">
+      <tp:member type="as" name="Parameters" tp:type="VCard_Type_Parameter[]">
         <tp:docstring>The set of vCard type parameters which may be set on this
           field. If this list is empty and the
           Contact_Info_Field_Flag_Parameters_Mandatory
diff --git a/spec/Connection_Interface_Presence.xml b/spec/Connection_Interface_Presence.xml
index 6d9b24a18..ecf96f868 100644
--- a/spec/Connection_Interface_Presence.xml
+++ b/spec/Connection_Interface_Presence.xml
@@ -27,7 +27,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
   <interface name="org.freedesktop.Telepathy.Connection.Interface.Presence">
     <tp:requires interface="org.freedesktop.Telepathy.Connection"/>
 
-    <!-- We hope to simplify these eventually -->
     <tp:mapping name="Multiple_Status_Map">
       <tp:docstring>Mapping used in
         <tp:type>Last_Activity_And_Statuses</tp:type> and passed to
@@ -249,17 +248,29 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
           map optional parameter names to their variant-boxed values
         </tp:docstring>
       </arg>
-      <tp:docstring>
-        Request that the user's presence be changed to the given statuses and
-        desired parameters. Changes will be reflected by
-        <tp:member-ref>PresenceUpdate</tp:member-ref>
-        signals being emitted. On certain protocols, this method may be
-        called on a newly-created connection which is still in the
-        DISCONNECTED state, and will sign on with the requested status.
-        If the requested status is not available after signing on,
-        NotAvailable will be returned and the connection will remain
-        offline, or if the protocol does not support signing on with
-        a certain status, Disconnected will be returned.
+      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+        <p>Request that the user's presence be changed to the given statuses
+          and desired parameters. Changes will be reflected by
+          <tp:member-ref>PresenceUpdate</tp:member-ref>
+          signals being emitted.</p>
+
+        <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type>
+          is Offline, Error or Unknown MUST NOT be passed to this
+          function. Connection managers SHOULD reject these statuses.</p>
+
+        <tp:rationale>
+          <p>The same rationale as for <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence.SetPresence</tp:dbus-ref>
+            applies.</p>
+        </tp:rationale>
+
+        <p>On certain protocols, this method may be
+          called on a newly-created connection which is still in the
+          DISCONNECTED state, and will sign on with the requested status.
+          If the requested status is not available after signing on,
+          NotAvailable will be returned and the connection will remain
+          offline, or if the protocol does not support signing on with
+          a certain status, Disconnected will be returned.</p>
       </tp:docstring>
       <tp:possible-errors>
         <tp:error name="org.freedesktop.Telepathy.Error.Disconnected"/>
@@ -269,12 +280,14 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         <tp:error name="org.freedesktop.Telepathy.Error.PermissionDenied"/>
       </tp:possible-errors>
     </method>
+
+    <tp:deprecated version="0.17.UNRELEASED">New client implementations
+      SHOULD use <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
+      instead. New connection managers SHOULD implement both Presence
+      and SimplePresence.</tp:deprecated>
+
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>This interface will become deprecated in future versions. New
-        client implementations MAY use <tp:dbus-ref
-          namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
-        instead; new connection managers SHOULD implement both Presence and
-        SimplePresence.</p>
 
       <p>This interface is for services which have a concept of presence which
         can be published for yourself and monitored on your contacts.
@@ -287,28 +300,15 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     per connection, and a list of them can be obtained with the
     <tp:member-ref>GetStatuses</tp:member-ref> method.</p>
 
+    <p>(The SimplePresence interface which replaces this one restricts
+      presences to one status per contact, with an optional message, which is
+      in practice all that was implemented on this interface.)</p>
+
     <p>Each status has an arbitrary string identifier which should have an agreed
     meaning between the connection manager and any client which is expected to
-    make use of it. The following well-known values (in common with those in
-    Galago) should be used where possible to allow clients to identify common
-    choices:</p>
-
-    <ul>
-      <li>available (corresponding to Connection_Presence_Type_Available)</li>
-      <li>away (corresponding to Connection_Presence_Type_Away)</li>
-      <li>brb (Be Right Back) (corresponding to
-        Connection_Presence_Type_Away, but more specific)</li>
-      <li>busy (corresponding to Connection_Presence_Type_Busy)</li>
-      <li>dnd (Do Not Disturb) (corresponding to
-        Connection_Presence_Type_Busy, but more specific)</li>
-      <li>xa (Extended Away) (corresponding to
-        Connection_Presence_Type_Extended_Away)</li>
-      <li>hidden (aka Invisible) (corresponding to
-        Connection_Presence_Type_Hidden)</li>
-      <li>offline (corresponding to Connection_Presence_Type_Offline)</li>
-      <li>unknown (corresponding to Connection_Presence_Type_Unknown)</li>
-      <li>error (corresponding to Connection_Presence_Type_Error)</li>
-    </ul>
+    make use of it. The well-known values defined by the <tp:dbus-ref
+        namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
+      interface SHOULD be used where possible</p>
 
     <p>As well as these well-known status identifiers, every status also has a
     numerical type value chosen from
@@ -339,125 +339,6 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
     intermittently to update any display of presence information.</p>
     </tp:docstring>
 
-    <tp:enum name="Connection_Presence_Type" type="u">
-      <tp:enumvalue suffix="Unset" value="0">
-        <tp:docstring>
-          An invalid presence type used as a null value. This value MUST NOT
-          appear in the result of <tp:member-ref>GetStatuses</tp:member-ref>,
-          or in the <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy.Connection.Interface.SimplePresence">Statuses</tp:dbus-ref>
-          property of the <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy.Connection.Interface">SimplePresence</tp:dbus-ref>
-          interface.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Offline" value="1">
-        <tp:docstring>
-          Offline
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Available" value="2">
-        <tp:docstring>
-          Available
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Away" value="3">
-        <tp:docstring>
-          Away
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Extended_Away" value="4">
-        <tp:docstring>
-          Away for an extended time
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Hidden" value="5">
-        <tp:docstring>
-          Hidden (invisible)
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Busy" value="6">
-        <tp:added version="0.17.0"/>
-        <tp:docstring>
-          Busy, Do Not Disturb.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Unknown" value="7">
-        <tp:added version="0.17.8"/>
-        <tp:docstring>
-          Unknown, unable to determine presence for this contact, for example
-          if the protocol only allows presence of subscribed contacts.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Error" value="8">
-        <tp:added version="0.17.8"/>
-        <tp:docstring>
-          Error, an error occurred while trying to determine presence.  The
-          message, if set, is an error from the server.
-        </tp:docstring>
-      </tp:enumvalue>
-    </tp:enum>
-
-    <tp:enum name="Rich_Presence_Access_Control_Type" type="u">
-      <tp:docstring>
-        A type of access control for Rich_Presence_Access_Control.
-        For most types, the exact access control is given by an associated
-        variant.
-
-        <tp:rationale>
-          These are the access control types from XMPP publish/subscribe
-          (XEP-0060).
-        </tp:rationale>
-      </tp:docstring>
-
-      <tp:enumvalue suffix="Whitelist" value="0">
-        <tp:docstring>
-          The associated variant is a list of contacts (signature 'au',
-          Contact_Handle[]) who can see the extended presence information.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Publish_List" value="1">
-        <tp:docstring>
-          All contacts in the user's 'publish' contact list can see the
-          extended presence information. The associated variant is ignored.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Group" value="2">
-        <tp:docstring>
-          The associated variant is a handle of type Group (signature 'u',
-          Group_Handle) representing a group of contacts who can see the
-          extended presence information.
-        </tp:docstring>
-      </tp:enumvalue>
-      <tp:enumvalue suffix="Open" value="3">
-        <tp:docstring>
-          Anyone with access to the service can see the extended presence
-          information.
-        </tp:docstring>
-      </tp:enumvalue>
-    </tp:enum>
-
-    <tp:struct name="Rich_Presence_Access_Control">
-      <tp:docstring>
-        An access control mode for extended presence items like geolocation.
-        This type isn't actually used by the core Presence interface, but
-        it's included here so it can be referenced by other specifications.
-      </tp:docstring>
-
-      <tp:member name="Type" type="u" tp:type="Rich_Presence_Access_Control_Type">
-        <tp:docstring>
-          The type of access control to apply.
-        </tp:docstring>
-      </tp:member>
-      <tp:member name="Detail" type="v">
-        <tp:docstring>
-          Any additional information required by the Type. The required
-          type and semantics are defined for each
-          Rich_Presence_Access_Control_Type.
-        </tp:docstring>
-      </tp:member>
-    </tp:struct>
-
   </interface>
 </node>
 <!-- vim:set sw=2 sts=2 et ft=xml: -->
diff --git a/spec/Connection_Interface_Simple_Presence.xml b/spec/Connection_Interface_Simple_Presence.xml
index 16f33865f..7acea32cc 100644
--- a/spec/Connection_Interface_Simple_Presence.xml
+++ b/spec/Connection_Interface_Simple_Presence.xml
@@ -151,6 +151,16 @@
               the choices would be appropriate, and incorrect information
               about the user would be conveyed.</p>
           </tp:rationale>
+
+          <p>Statuses whose <tp:type>Connection_Presence_Type</tp:type>
+            is Offline, Error or Unknown MUST NOT be passed to this
+            function. Connection managers SHOULD reject these statuses.</p>
+
+          <tp:rationale>
+            <p>To go offline, call <tp:dbus-ref
+                namespace="org.freedesktop.Telepathy.Connection">Disconnect</tp:dbus-ref>
+            instead. The "error" and "unknown" statuses make no sense.</p>
+          </tp:rationale>
         </tp:docstring>
       </arg>
       <arg direction="in" name="Status_Message" type="s">
@@ -232,9 +242,9 @@
     <property name="Statuses" tp:name-for-bindings="Statuses" access="read"
       type="a{s(ubb)}" tp:type="Simple_Status_Spec_Map">
       <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-        <p>A dictionary where the keys are the presence statuses that the user
-          can set on themselves for this connection, and the values are the
-          corresponding presence types.</p>
+        <p>A dictionary where the keys are the presence statuses that are
+          available on this connection, and the values are the corresponding
+          presence types.</p>
 
         <p>While the connection is in the DISCONNECTED state, it contains
           the set of presence statuses allowed to be set before connecting.
@@ -280,6 +290,127 @@
       </tp:docstring>
     </signal>
 
+    <tp:enum name="Connection_Presence_Type" type="u">
+      <tp:enumvalue suffix="Unset" value="0">
+        <tp:docstring>
+          An invalid presence type used as a null value. This value MUST NOT
+          appear in the <tp:member-ref>Statuses</tp:member-ref> property,
+          or in the result of <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Connection.Interface.Presence">GetStatuses</tp:dbus-ref>
+          on the deprecated <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Connection.Interface">Presence</tp:dbus-ref>
+          interface.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Offline" value="1">
+        <tp:docstring>
+          Offline
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Available" value="2">
+        <tp:docstring>
+          Available
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Away" value="3">
+        <tp:docstring>
+          Away
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Extended_Away" value="4">
+        <tp:docstring>
+          Away for an extended time
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Hidden" value="5">
+        <tp:docstring>
+          Hidden (invisible)
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Busy" value="6">
+        <tp:added version="0.17.0"/>
+        <tp:docstring>
+          Busy, Do Not Disturb.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Unknown" value="7">
+        <tp:added version="0.17.8"/>
+        <tp:docstring>
+          Unknown, unable to determine presence for this contact, for example
+          if the protocol only allows presence of subscribed contacts.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Error" value="8">
+        <tp:added version="0.17.8"/>
+        <tp:docstring>
+          Error, an error occurred while trying to determine presence.  The
+          message, if set, is an error from the server.
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
+    <tp:enum name="Rich_Presence_Access_Control_Type" type="u">
+      <tp:docstring>
+        A type of access control for Rich_Presence_Access_Control.
+        For most types, the exact access control is given by an associated
+        variant.
+
+        <tp:rationale>
+          These are the access control types from XMPP publish/subscribe
+          (XEP-0060).
+        </tp:rationale>
+      </tp:docstring>
+
+      <tp:enumvalue suffix="Whitelist" value="0">
+        <tp:docstring>
+          The associated variant is a list of contacts (signature 'au',
+          Contact_Handle[]) who can see the extended presence information.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Publish_List" value="1">
+        <tp:docstring>
+          All contacts in the user's 'publish' contact list can see the
+          extended presence information. The associated variant is ignored.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Group" value="2">
+        <tp:docstring>
+          The associated variant is a handle of type Group (signature 'u',
+          Group_Handle) representing a group of contacts who can see the
+          extended presence information.
+        </tp:docstring>
+      </tp:enumvalue>
+      <tp:enumvalue suffix="Open" value="3">
+        <tp:docstring>
+          Anyone with access to the service can see the extended presence
+          information.
+        </tp:docstring>
+      </tp:enumvalue>
+    </tp:enum>
+
+    <tp:struct name="Rich_Presence_Access_Control">
+      <tp:docstring>
+        An access control mode for extended presence items like geolocation.
+        This type isn't actually used by the SimplePresence interface, but
+        it's included here so it can be referenced by rich presence interfaces
+        such as <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Connection.Interface">Location.DRAFT</tp:dbus-ref>.
+      </tp:docstring>
+
+      <tp:member name="Type" type="u" tp:type="Rich_Presence_Access_Control_Type">
+        <tp:docstring>
+          The type of access control to apply.
+        </tp:docstring>
+      </tp:member>
+      <tp:member name="Detail" type="v">
+        <tp:docstring>
+          Any additional information required by the Type. The required
+          type and semantics are defined for each
+          <tp:type>Rich_Presence_Access_Control_Type</tp:type>.
+        </tp:docstring>
+      </tp:member>
+    </tp:struct>
+
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
       <p>This interface is for services which have a concept of presence which
         can be published for yourself and monitored on your contacts.</p>
diff --git a/spec/all.xml b/spec/all.xml
index 7745d549c..1c377dfb9 100644
--- a/spec/all.xml
+++ b/spec/all.xml
@@ -3,11 +3,11 @@
   xmlns:xi="http://www.w3.org/2001/XInclude">
 
 <tp:title>Telepathy D-Bus Interface Specification</tp:title>
-<tp:version>0.17.19</tp:version>
+<tp:version>0.17.21</tp:version>
 
-<tp:copyright>Copyright (C) 2005-2008 Collabora Limited</tp:copyright>
-<tp:copyright>Copyright (C) 2005-2008 Nokia Corporation</tp:copyright>
-<tp:copyright>Copyright (C) 2006 INdT</tp:copyright>
+<tp:copyright>Copyright © 2005-2009 Collabora Limited</tp:copyright>
+<tp:copyright>Copyright © 2005-2009 Nokia Corporation</tp:copyright>
+<tp:copyright>Copyright © 2006 INdT</tp:copyright>
 
 <tp:license xmlns="http://www.w3.org/1999/xhtml">
 <p>This library is free software; you can redistribute it and/or
@@ -52,6 +52,7 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
 <xi:include href="Channel_Type_Stream_Tube.xml"/>
 <xi:include href="Channel_Type_DBus_Tube.xml"/>
 <xi:include href="Channel_Type_File_Transfer.xml"/>
+<xi:include href="Channel_Type_Contact_Search.xml"/>
 
 <xi:include href="Channel_Interface_Call_Merging.xml"/>
 <xi:include href="Channel_Interface_Call_State.xml"/>