From c3c49f90161d76a2f3c8454c49f6580fc60b220b Mon Sep 17 00:00:00 2001
From: Simon McVittie <simon.mcvittie@collabora.co.uk>
Date: Fri, 17 Dec 2010 10:52:58 +0000
Subject: Describe the (unusual!) expected channel class for ContactSearch
 channels

Reviewed-by: Will Thompson <will.thompson@collabora.co.uk>
---
 spec/Channel_Type_Contact_Search.xml   | 23 +++++++++++++++++++++--
 spec/Connection_Interface_Requests.xml |  5 ++++-
 2 files changed, 25 insertions(+), 3 deletions(-)

diff --git a/spec/Channel_Type_Contact_Search.xml b/spec/Channel_Type_Contact_Search.xml
index fefa77a2..98789ab4 100644
--- a/spec/Channel_Type_Contact_Search.xml
+++ b/spec/Channel_Type_Contact_Search.xml
@@ -31,12 +31,31 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
       <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. Channels of this type should have <tp:dbus-ref
+        found.</p>
+
+      <p>Connections that support contact search channels SHOULD have an entry
+        in <tp:dbus-ref namespace='ofdT.Connection.Interface.Requests'
+          >RequestableChannelClasses</tp:dbus-ref> with the <tp:dbus-ref
+          namespace='ofdT.Channel'>ChannelType</tp:dbus-ref> fixed to this
+        interface, and no other fixed properties. That requestable
+        channel class MAY also have the Server and Limit properties in its
+        list of allowed properties, depending on the protocol.</p>
+
+      <tp:rationale>
+        <p>The requestable channel class would normally also have <tp:dbus-ref
+            namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref> fixed to
+          <code>None</code>, but the initial implementation of ContactSearch
+          (in telepathy-gabble) didn't do this.</p>
+      </tp:rationale>
+
+      <p>All channels of this type should have <tp:dbus-ref
         namespace='ofdT.Channel'>TargetHandleType</tp:dbus-ref>
         <code>None</code> (and hence <tp:dbus-ref
         namespace='ofdT.Channel'>TargetHandle</tp:dbus-ref> <code>0</code> and
         <tp:dbus-ref namespace='ofdT.Channel'>TargetID</tp:dbus-ref>
-        <code>""</code>). Requests for channels of this type need only
+        <code>""</code>).</p>
+
+      <p>Requests for channels of this type need only
         optionally specify the <tp:member-ref>Server</tp:member-ref> property
         (if it is an allowed property in the connection's <tp:dbus-ref
         namespace='ofdT.Connection.Interface.Requests'>RequestableChannelClasses</tp:dbus-ref>).</p>
diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml
index 2f233fa5..c8dc3280 100644
--- a/spec/Connection_Interface_Requests.xml
+++ b/spec/Connection_Interface_Requests.xml
@@ -486,7 +486,10 @@
           <tp:dbus-ref>org.freedesktop.Telepathy.Channel.ChannelType</tp:dbus-ref>
           and
           <tp:dbus-ref>org.freedesktop.Telepathy.Channel.TargetHandleType</tp:dbus-ref>.
-          </p>
+          (One exception is that <tp:dbus-ref namespace="ofdT.Channel.Type"
+            >ContactSearch</tp:dbus-ref> channels do not have TargetHandleType
+          <code>None</code> in their requestable channel classes, for
+          historical reasons.)</p>
       </tp:docstring>
 
       <tp:member type="s" name="Key" tp:type="DBus_Qualified_Member">
-- 
cgit v1.2.3