[Telepathy-commits] [telepathy-spec/master] MediaSignalling: remove "lowering barrier to entry" wording, and specify that transports passed to EnsureChannel etc. are ignored

[Simon McVittie]

The "lowering barrier to entry" wording would allow installation of a
client A (that handles ICE only) to break an unrelated client B's support
for GTalkP2P, if B relied on this mechanism. As a result, nobody can
rely on this mechanism, so it's basically useless.

The ability to disable transports by parameters to EnsureChannel etc. is
only a partial solution, since channels requested by an address book
can't take advantage of this mechanism. A better solution (to be added
later) would be to introduce interactive transport negotiation, done by
the streaming implementation (e.g. before Ready).
---
 spec/Channel_Interface_Media_Signalling_Future.xml |   94 ++++++--------------
 1 files changed, 29 insertions(+), 65 deletions(-)

diff --git a/spec/Channel_Interface_Media_Signalling_Future.xml b/spec/Channel_Interface_Media_Signalling_Future.xml
index 79a0673..9c479bb 100644
--- a/spec/Channel_Interface_Media_Signalling_Future.xml
+++ b/spec/Channel_Interface_Media_Signalling_Future.xml
@@ -67,9 +67,31 @@
           properties list of the channel class that advertises a contact's
           ability to receive streamed media calls.</p>
 
-        <p>Clients that are able to receive calls with particular NAT
-          traversal mechanisms MAY include the following filters if
-          calling <tp:dbus-ref
+        <p>Clients SHOULD NOT pass ICETransportAvailable and similar
+          properties to <tp:dbus-ref
+            namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>
+          or similar functions. If they do, the connection manager MUST
+          accept and ignore any such property that is in the allowed properties
+          list.</p>
+
+        <tp:rationale>
+          <p>There is currently no way for clients to influence the choice
+            of transport: in general, a client making a call can't know the
+            capabilities of the streaming implementation, or even which
+            streaming implementation will be used (channels will often be
+            requested by an address book or similar application that will not
+            handle the channel itself).</p>
+
+          <p>If a mechanism for transport negotiation is added, it should be
+            something that happens after the request, but before calling
+            <tp:dbus-ref
+              namespace="org.freedesktop.Telepathy">Media.SessionHandler.Ready</tp:dbus-ref>,
+            so that it is the streaming implementation that chooses the
+            transport, rather than the requesting client.</p>
+        </tp:rationale>
+
+        <p>Clients that are able to receive calls with particular transports
+          MUST include the following filters if calling <tp:dbus-ref
             namespace="org.freedesktop.Telepathy.Connection.Interface.ContactCapabilities.DRAFT">SetSelfCapabilities</tp:dbus-ref>
           (clients of a <tp:dbus-ref
             namespace="org.freedesktop.Telepathy">ChannelDispatcher.DRAFT</tp:dbus-ref>
@@ -87,71 +109,13 @@
         </ul>
 
         <p>Connection managers MAY use this information to adjust the
-          transports for which they advertise support to other contacts.
-          If a client has indicated support for any particular transports,
-          the connection manager SHOULD advertise support for
-          each transport that is supported by any client, and also
-          supported by the CM itself.</p>
+          transports for which they advertise support to other contacts.</p>
 
         <tp:rationale>
-          <p>This minimizes the possibility that a call will be started that
-            cannot in fact succeed, because the intersection of the contacts'
-            available transports is empty.</p>
+          <p>In particular, in XMPP, the connection manager will not be
+            callable unless a client has told it to advertise support for
+            at least one transport.</p>
         </tp:rationale>
-
-        <p>If no client has mentioned any of the transports known to the
-          connection manager in a call to SetSelfCapabilities, the connection
-          manager SHOULD advertise support for every transport that it can
-          signal.</p>
-
-        <tp:rationale>
-          <p>This simplifies implementation on integrated platforms like Maemo,
-            where it can be assumed that client libraries will support all the
-            "standard" transports known to any connection manager, and
-            lowers the "barrier to entry" for new Telepathy clients.</p>
-        </tp:rationale>
-
-        <p>Clients making outgoing calls for which the same client that made
-          the request will handle the streaming MAY indicate their ability or
-          inability to handle particular transports by including
-          <code>ICETransportAvailable = true</code>,
-          <code>RawUDPTransportAvailable = false</code>, etc.
-          in the request properties parameter of their call to <tp:dbus-ref
-            namespace="org.freedesktop.Telepathy.Connection.Interface.Requests">EnsureChannel</tp:dbus-ref>
-          or similar functions. When they do so, the connection manager
-          SHOULD attempt to use a transport that the client has indicated
-          it is able to handle; if this is not possible, the connection
-          manager SHOULD raise an error instead of creating a channel.</p>
-
-        <tp:rationale>
-          <p>This enables such clients to restrict the CM to the subset of
-            transports supported by that particular client.</p>
-        </tp:rationale>
-
-        <p>Clients making outgoing calls for which they will not themselves
-          handle the streaming (e.g. an address book starting a call which
-          will be streamed by a separate call UI) SHOULD NOT include those
-          properties in the request.</p>
-
-        <tp:rationale>
-          <p>In general, such a client can't know the capabilities of the
-            streaming implementation, or even which streaming implementation
-            will be used.</p>
-        </tp:rationale>
-
-        <p>In the absence of any indication of supported transports from the
-          client, the connection manager SHOULD assume that the transports
-          indicated by calling SetSelfCapabilities are available. If
-          no transports were indicated as supported by calling
-          SetSelfCapabilities either, it SHOULD assume that any transport
-          that it can signal will be acceptable.</p>
-
-        <p>If this property, or any of the similar transport availability
-          properties, is passed to EnsureChannel (as opposed to CreateChannel),
-          the connection manager SHOULD ignore these properties when checking
-          whether it can return an existing channel as suitable; these
-          properties only become significant when the connection manager has
-          decided to create a new channel.</p>
       </tp:docstring>
     </property>
 
-- 
1.5.6.5