[next] telepathy-spec: Do not list Requests in the Interfaces property

[Simon McVittie]

Module: telepathy-spec
Branch: next
Commit: a8fa5571f20081156d00e24095d3778b2b778f36
URL:    http://cgit.freedesktop.org/telepathy/telepathy-spec/commit/?id=a8fa5571f20081156d00e24095d3778b2b778f36

Author: Simon McVittie <simon.mcvittie at collabora.co.uk>
Date:   Wed Nov  6 19:04:27 2013 +0000

Do not list Requests in the Interfaces property

Bug: https://bugs.freedesktop.org/show_bug.cgi?id=50093
Reviewed-by: Guillaume Desmottes <guillaume.desmottes at collabora.co.uk>

---

 spec/Connection.xml                    |   11 +++++++++++
 spec/Connection_Interface_Requests.xml |   16 ++++++++++++----
 spec/Protocol.xml                      |    6 +++++-
 3 files changed, 28 insertions(+), 5 deletions(-)

diff --git a/spec/Connection.xml b/spec/Connection.xml
index 1af4786..606ce4f 100644
--- a/spec/Connection.xml
+++ b/spec/Connection.xml
@@ -67,6 +67,17 @@ USA.</p>
             to have evaluated the server's functionality and enabled any extra
             interfaces for the remainder of the Connection's lifetime.</p>
         </tp:rationale>
+
+        <p>As a special case, the mandatory <tp:dbus-ref
+            namespace="imt1.Connection.Interface">Requests</tp:dbus-ref>
+          interface SHOULD NOT be listed in this property.</p>
+
+        <tp:rationale>
+          <p>It has been mandatory since Telepathy 0.18 in 2009,
+            and contains essential functionality for this interface,
+            so there seems no point in wasting bytes on capability discovery
+            for it.</p>
+        </tp:rationale>
       </tp:docstring>
       <tp:added version="0.19.2"/>
     </property>
diff --git a/spec/Connection_Interface_Requests.xml b/spec/Connection_Interface_Requests.xml
index c08860f..c34b8c1 100644
--- a/spec/Connection_Interface_Requests.xml
+++ b/spec/Connection_Interface_Requests.xml
@@ -26,10 +26,18 @@
     <tp:added version="0.17.11">(as stable API)</tp:added>
 
     <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>An enhanced version of the Telepathy connection interface, which can
-        represent bundles of channels that should be dispatched together, and
-        does not assume any particular properties by which channels are
-        uniquely identifiable.</p>
+      <p>An interface for channel requests and channel lists. Under
+        normal circumstances, applications should deal with this
+        interface via the <tp:dbus-ref
+          namespace="imt1">ChannelDispatcher</tp:dbus-ref>,
+        but lower-level Telepathy applications (such as the
+        ChannelDispatcher itself) might need to use this interface
+        directly.</p>
+
+      <p>This interface is conceptually part of the core Connection
+        interface, but is kept separate so that its properties will
+        normally only need to be retrieved by the ChannelDispatcher,
+        and its signals will normally only wake up the ChannelDispatcher.</p>
     </tp:docstring>
 
     <tp:struct name="Channel_Details" array-name="Channel_Details_List">
diff --git a/spec/Protocol.xml b/spec/Protocol.xml
index 610ecfc..a729393 100644
--- a/spec/Protocol.xml
+++ b/spec/Protocol.xml
@@ -53,7 +53,7 @@ Interfaces=
 
 [Protocol example]
 Interfaces=
-ConnectionInterfaces=im.telepathy.v1.Connection.Interface.Requests;
+ConnectionInterfaces=im.telepathy.v1.Connection.Interface.Aliasing;
 param-account=s required
 param-password=s required secret
 RequestableChannelClasses=text;
@@ -137,6 +137,10 @@ allowed=im.telepathy.v1.Channel.TargetHandle;im.telepathy.v1.Channel.TargetID;
           <code>.manager</code> file, using the key
           <code>ConnectionInterfaces</code>. The corresponding value
           is a list of D-Bus interface names, each followed by a semicolon.</p>
+
+        <p>As a special case, the mandatory <tp:dbus-ref
+            namespace="imt1.Connection.Interface">Requests</tp:dbus-ref>
+          interface SHOULD NOT be listed in this property.</p>
       </tp:docstring>
     </property>