[Telepathy] Getting relay info from Telepathy to Farsight
Simon McVittie
simon.mcvittie at collabora.co.uk
Thu Feb 5 10:23:19 PST 2009
Here's my proposal for how we get relay and NAT traversal info for individual
media streams from Telepathy to Farsight. How does this look? Feedback
from Olivier and Youness about whether this is enough information would
be particularly useful!
Someone (maybe me) should have a go at implementing this in Gabble at
some point.
Cumulative diff is inline for convenience; git branch is in gitweb. This
is http://bugs.freedesktop.org/show_bug.cgi?id=17840
Regards,
Simon
http://git.collabora.co.uk/?p=user/smcv/telepathy-spec-smcv.git;a=shortlog;h=refs/heads/relayinfo
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.
diff --git a/spec/Media_Stream_Handler.xml b/spec/Media_Stream_Handler.xml
index cb7c793..1a68532 100644
--- a/spec/Media_Stream_Handler.xml
+++ b/spec/Media_Stream_Handler.xml
@@ -70,6 +70,113 @@ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.</
</tp:member>
</tp:struct>
+ <property name="STUNServer" tp:name-for-bindings="STUN_Server"
+ type="s" access="read">
+ <tp:added version="0.17.UNRELEASED"/>
+ <tp:docstring>
+ The IP address or hostname of the STUN server to use for NAT traversal.
+ <!-- Unresolved issue: should we mandate that this is an IP address? -->
+ </tp:docstring>
+ </property>
+
+ <property name="STUNPort" tp:name-for-bindings="STUN_Port"
+ type="u" access="read">
+ <tp:added version="0.17.UNRELEASED"/>
+ <tp:docstring>
+ The UDP port number to use on the
+ <tp:member-ref>STUNServer</tp:member-ref>.
+ </tp:docstring>
+ </property>
+
+ <property name="NATTraversal" tp:name-for-bindings="NAT_Traversal"
+ type="s" access="read">
+ <tp:added version="0.17.UNRELEASED"/>
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>The transport (NAT traversal technique) to be used for this
+ stream. Well-known values include:</p>
+
+ <dl>
+ <dt>none</dt>
+ <dd>Raw UDP with no attempt made at doing NAT traversal. The
+ stun-server property MUST be absent or empty.</dd>
+
+ <dt>stun</dt>
+ <dd>Raw UDP, but a STUN request should be made to the given server
+ to open a UDP port mapping and determine the external IP.
+ The <tp:member-ref>STUNServer</tp:member-ref> property MUST be
+ given and non-empty.</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:docstring>
+ </property>
+
+ <property name="RelayInfo" type="aa{ss}" access="read"
+ tp:type="String_String_Map[]" tp:name-for-bindings="Relay_Info">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of mappings containing information about how this stream
+ can be relayed, to be used with TURN or Google relay servers.
+ Map keys are:</p>
+
+ <dl>
+ <dt><code>ip</code></dt>
+ <dd>The IP address of the relay server as a dotted-quad IPv4
+ address literal or an RFC2373 IPv6 address literal</dd>
+ <!-- Open issue: should the CM or the streaming implementation
+ be responsible for resolving hostnames to IPs? Bear in mind that
+ this might be a SRV record... -->
+
+ <dt><code>type</code></dt>
+ <dd>Either <code>udp</code> for UDP (UDP MUST be assumed if this
+ key is omitted), <code>tcp</code> for TCP, or
+ <code>tls</code> for a fake SSL/TLS session over TCP as supported
+ by the Google relay server</dd>
+
+ <dt><code>port</code></dt>
+ <dd>The UDP or TCP port of the relay server as an ASCII unsigned
+ integer</dd>
+
+ <dt><code>username</code></dt>
+ <dd>The username to use</dd>
+
+ <dt><code>password</code></dt>
+ <dd>The password to use</dd>
+
+ <dt><code>component</code></dt>
+ <dd>The component number to use this relay server for, as an
+ ASCII unsigned integer; if not included, this relay server
+ may be used for any or all components.
+
+ <tp:rationale>
+ In ICE draft 6, as used by Google Talk, credentials are only
+ valid once, so each component needs relaying separately.
+ </tp:rationale>
+ </dd>
+ </dl>
+
+ <tp:rationale>
+ <p>An equivalent of the gtalk-p2p-relay-token property on
+ MediaSignalling channels is not included here. The connection
+ manager should be responsible for making the necessary HTTP
+ requests to turn the token into a username and password.</p>
+ </tp:rationale>
+
+ <p>The type of relay server that this represents depends on
+ the value of the <tp:member-ref>NATTraversal</tp:member-ref>
+ property. If NATTraversal is ice-udp, this is a TURN server;
+ if NATTraversal is gtalk-p2p, this is a Google relay server;
+ otherwise, the meaning of RelayInfo is undefined.</p>
+
+ <p>If relaying is not possible for this stream, the list is empty.</p>
+ </tp:docstring>
+ </property>
+
<signal name="AddRemoteCandidate"
tp:name-for-bindings="Add_Remote_Candidate">
<arg name="Candidate_ID" type="s">
diff --git a/spec/generic-types.xml b/spec/generic-types.xml
index fba6a9f..7614504 100644
--- a/spec/generic-types.xml
+++ b/spec/generic-types.xml
@@ -90,7 +90,7 @@
<tp:member type="v" name="Value"/>
</tp:mapping>
- <tp:mapping name="String_String_Map">
+ <tp:mapping name="String_String_Map" array-name="String_String_Map_List">
<tp:docstring>A mapping from strings to strings representing extra
key-value pairs.</tp:docstring>
<tp:member type="s" name="Key"/>
More information about the telepathy
mailing list