[Telepathy-commits] [telepathy-spec/master] MediaSignalling: deprecate nat-traversal, stun-server and stun-port in favour of per-stream ones

[Simon McVittie]

---
 spec/Channel_Interface_Media_Signalling.xml |   54 +++++++++++++++------------
 1 files changed, 30 insertions(+), 24 deletions(-)

diff --git a/spec/Channel_Interface_Media_Signalling.xml b/spec/Channel_Interface_Media_Signalling.xml
index 2a899ce..41419d2 100644
--- a/spec/Channel_Interface_Media_Signalling.xml
+++ b/spec/Channel_Interface_Media_Signalling.xml
@@ -103,43 +103,49 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
         within.
       </tp:docstring>
     </signal>
-    <tp:property name="nat-traversal" type="s">
-      <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
-      <p>A string indicating the NAT traversal techniques employed by the
-      streams within this channel. Can be protocol-specific values, but the
-      following values should be used if appropriate:</p>
-
-      <dl>
-        <dt>none</dt>
-        <dd>No attempt should be made at NAT traversal.</dd>
-
-        <dt>stun</dt>
-        <dd>If appropriate, a STUN request should be made to the given server
-        to open a UDP port mapping and determine the external IP.</dd>
 
-        <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:property name="nat-traversal" type="s">
+      <tp:deprecated version="0.17.UNRELEASED">Use the <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+        property on the Media.StreamHandler, if available; use this
+        as a fallback.</tp:deprecated>
+      <tp:docstring>
+        A string indicating the NAT traversal techniques employed by the
+        streams within this channel if they do not have a <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Media.StreamHandler">NATTraversal</tp:dbus-ref>
+        property. The possible values are the same as for the NATTraversal
+        property on the streams.
       </tp:docstring>
     </tp:property>
+
     <tp:property name="stun-server" type="s">
+      <tp:deprecated version="0.17.UNRELEASED">Use the <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServer</tp:dbus-ref>
+        property on the Media.StreamHandler, if available; use this
+        as a fallback.</tp:deprecated>
       <tp:docstring>
-      The IP address or hostname of the STUN server to use for NAT traversal.
+        The IP address or hostname of the STUN server to use for NAT traversal
+        if the individual streams do not specify one.
       </tp:docstring>
     </tp:property>
+
     <tp:property name="stun-port" type="q">
+      <tp:deprecated version="0.17.UNRELEASED">Use the <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Media.StreamHandler">STUNServer</tp:dbus-ref>
+        property on the Media.StreamHandler, if available; use this
+        as a fallback.</tp:deprecated>
       <tp:docstring>
       The UDP port number to use on the provided STUN server.
       </tp:docstring>
     </tp:property>
+
     <tp:property name="gtalk-p2p-relay-token" type="s">
+      <tp:deprecated version="0.17.UNRELEASED">XMPP connection managers
+        supporting the Google Talk relay server SHOULD make the necessary
+        HTTP requests to find a username and password, and use those
+        to populate the <tp:dbus-ref
+          namespace="org.freedesktop.Telepathy.Media.StreamHandler">RelayInfo</tp:dbus-ref>
+        property on the Media.StreamHandler.</tp:deprecated>
       <tp:docstring>
       The authentication token for use with the Google Talk peer-to-peer relay
       server.
-- 
1.5.6.5