[telepathy-spec/master] Add methods to set global credentials and get nat info
Sjoerd Simons
sjoerd.simons at collabora.co.uk
Tue Dec 1 09:46:20 PST 2009
---
spec/Call_Stream_Interface_Media.xml | 267 ++++++++++++++++++++++++++++++++++
1 files changed, 267 insertions(+), 0 deletions(-)
diff --git a/spec/Call_Stream_Interface_Media.xml b/spec/Call_Stream_Interface_Media.xml
index 6cc4cc5..78663a8 100644
--- a/spec/Call_Stream_Interface_Media.xml
+++ b/spec/Call_Stream_Interface_Media.xml
@@ -27,6 +27,273 @@
<tp:docstring xmlns="http://www.w3.org/1999/xhtml">
</tp:docstring>
+
+ <tp:method name="SetCredentials" tp:name-for-bindings="Set_Credentials">
+ <tp:docstring>
+ Used to set the username fragment and password for streams that have
+ global credentials
+ </tp:docstring>
+ <arg name="username" type="s" direction="in"/>
+ <arg name="password" type="s" direction="in" />
+ </tp:method>
+
+ <tp:mapping name="Candidate_Info">
+ <tp:member name="key" type="s"/>
+ <tp:member name="value" type="v"/>
+ <tp:docstring>
+ Extra information about the candidate. Allowed and Mandatory keys
+ depend on the transport protocol used. The following keys are commenly
+ used:
+ <dl>
+ <dt> Type (u)</dt>
+ <dd> type of candidate (host, srflx, prflx, relay)</dd>
+
+ <dt> Foundation (s)</dt>
+ <dd> the foundation of this candiate</dd>
+
+ <dt> Protocol (u) </dt>
+ <dd> Underlying protocol of the candidate (udp, tcp) </dd>
+
+ <dt> Priority (u) </dt>
+ <dd> Priority of the candidate </dd>
+
+ <dt> BaseIP (u) </dt>
+ <dd> Base IP of this candidate </dd>
+
+ <dt> Username (s) </dt>
+ <dd> Username of this candidate
+ (only if credentials are per candidate)</dd>
+
+ <dt> Password (s) </dt>
+ <dd> Password of this candidate
+ (only if credentials are per candidate)</dd>
+
+ </dl>
+ </tp:docstring>
+ </tp:mapping>
+
+ <tp:struct name="Candidate" array-name="Candidate_List">
+ <tp:docstring>A mushroom and a snake</tp:docstring>
+
+ <tp:member name="component" type="u" />
+ <tp:member name="ip" type="s" />
+ <tp:member name="port" type="q" />
+ <tp:member name="info" type="a{sv}" tp:type="Candidate_Info">
+ </tp:member>
+
+ </tp:struct>
+
+ <method name="AddCandidates" tp:name-for-bindings="Add_Candidates">
+ <arg name="candidates" direction="in"
+ type="a(usqa{sv})" tp:type="Candidate[]" />
+ </method>
+
+ <method name="CandidatesPrepared"
+ tp:name-for-bindings="Candidates_Prepared">
+ <tp:docstring>
+ This indicates to the CM that the initial batch of candidates has been
+ added.
+ </tp:docstring>
+ </method>
+
+ <method name="SetSelectedCandidate"
+ tp:name-for-bindings="Set_Selected_Candidate">
+ <arg name="candidate"
+ type="(usqa{sv})" tp:type="Candidate" direction="in">
+ <tp:docstring>
+ </tp:docstring>
+ </arg>
+ </method>
+
+ <tp:enum type="u" name="Stream_Transport_Type">
+ <tp:enumvalue suffix="Raw_UDP" value="0" />
+ <tp:enumvalue suffix="ICE" value="1" />
+ <tp:enumvalue suffix="GTALK_P2P" value="2" />
+ <tp:enumvalue suffix="MSN" value="3" />
+ <tp:enumvalue suffix="WLM2009" value="4" />
+ </tp:enum>
+
+ <property name="Transport" tp:name-for-bindings="Transport"
+ type="u" tp:type="Stream_Transport_Type" access="read">
+ </property>
+
+ <tp:mapping name="Handle_Candidate_Map">
+ <tp:member name="Contact" type="u" tp:type="Contact_Handle" />
+ <tp:member name="Candidates" type="a(usqa{sv})" tp:type="Candidate[]" />
+ </tp:mapping>
+
+ <property name="RemoteCandidates" tp:name-for-bindings="Remote_Candidates"
+ type="a(usqa{sv})" tp:type="Candidate[]" access="read">
+ </property>
+
+ <signal name="RemoteCandidatesAdded"
+ tp:name-for-bindings="Remote_Candidates_Added">
+ <arg name="Candidates"
+ type="a(usqa{sv})" tp:type="Candidate[]"/>
+ </signal>
+
+ <property name="RemoteCredentials"
+ tp:name-for-bindings="Remote_Credentials"
+ type="ss" access="read">
+ </property>
+
+ <signal name="RemoteCredentialsSet"
+ tp:name-for-bindings="Remote_Credentials_Set">
+ <arg name="username" type="s" />
+ <arg name="password" type="s" />
+ </signal>
+
+ <property name="LocalCandidates" tp:name-for-bindings="Local_Candidates"
+ type="a(usqa{sv})" tp:type="Candidate[]" access="read">
+ </property>
+
+ <signal name="LocalCandidatesAdded"
+ tp:name-for-bindings="Local_Candidates_Added">
+ <arg name="Candidates"
+ type="a(usqa{sv})" tp:type="Candidate[]"/>
+ </signal>
+
+ <property name="LocalCredentials" tp:name-for-bindings="Local_Credentials"
+ type="ss" access="read">
+ </property>
+
+ <signal name="LocalCredentialsSet"
+ tp:name-for-bindings="LocalCredentialsSet">
+ <arg name="username" type="s" />
+ <arg name="password" type="s" />
+ </signal>
+
+ <property name="SelectedCandidate"
+ tp:name-for-bindings="Selected_Candidate"
+ type="(usqa{sv})" tp:type="Candidate" access="read">
+ </property>
+
+ <signal name="CandidateSelected"
+ tp:name-for-bindings="Candidate_Selected">
+ <arg name="Candidate"
+ type="(usqa{sv})" tp:type="Candidate"/>
+ </signal>
+
+ <property name="StreamState" tp:name-for-bindings="Stream_State"
+ type="u" tp:type="Media_Stream_Type"
+ access="read">
+ </property>
+
+ <signal name="StreamStateChanged"
+ tp:name-for-bindings="Stream_State_Changed">
+ <arg name="state"
+ type="u" tp:type="Media_Stream_Type"/>
+ </signal>
+
+ <method name="SetStreamState"
+ tp:name-for-bindings="Set_Stream_State">
+ <arg name="state" type="u" tp:type="Media_Stream_Type"
+ direction="in" />
+ </method>
+
+ <signal name="STUNServersAdded"
+ tp:name-for-bindings="STUN_Servers_Added">
+ <arg name="servers"
+ type="a(sq)" tp:type="Socket_Address_IP[]"/>
+ </signal>
+
+ <property name="STUNServers" tp:name-for-bindings="STUN_Servers"
+ type="a(sq)" tp:type="Socket_Address_IP[]" access="read">
+ <tp:docstring>
+ The IP addresses of possible STUN servers to use for NAT traversal, as
+ dotted-quad IPv4 address literals or RFC2373 IPv6 address literals.
+ This property cannot change once the stream has been created, so there
+ is no change notification. The IP addresses MUST NOT be given as DNS
+ hostnames.
+
+ <tp:rationale>
+ High-quality connection managers already need an asynchronous
+ DNS resolver, so they might as well resolve this name to an IP
+ to make life easier for streaming implementations.
+ </tp:rationale>
+ </tp:docstring>
+ </property>
+
+ <signal name="RelayInfoAdded" tp:name-for-bindings="Relay_Info_Added">
+ <arg name="relay_info"
+ type="aa{sv}" tp:type="String_Variant_Map[]"/>
+ </signal>
+
+ <property name="RelayInfo" type="aa{sv}" access="read"
+ tp:type="String_Variant_Map[]" tp:name-for-bindings="Relay_Info">
+ <tp:docstring xmlns="http://www.w3.org/1999/xhtml">
+ <p>A list of mappings describing TURN or Google relay servers
+ available for the client to use in its candidate gathering, as
+ determined from the protocol. Map keys are:</p>
+
+ <dl>
+ <dt><code>ip</code> - s</dt>
+ <dd>The IP address of the relay server as a dotted-quad IPv4
+ address literal or an RFC2373 IPv6 address literal. This MUST NOT
+ be a DNS hostname.
+
+ <tp:rationale>
+ High-quality connection managers already need an asynchronous
+ DNS resolver, so they might as well resolve this name to an IP
+ and make life easier for streaming implementations.
+ </tp:rationale>
+ </dd>
+
+ <dt><code>type</code> - s</dt>
+ <dd>
+ <p>Either <code>udp</code> for UDP (UDP MUST be assumed if this
+ key is omitted), <code>tcp</code> for TCP, or
+ <code>tls</code>.</p>
+
+ <p>The precise meaning of this key depends on the
+ <tp:member-ref>Transport</tp:member-ref> property: if
+ Transport is <code>ice-udp</code>, <code>tls</code> means
+ TLS over TCP as referenced by ICE draft 19, and if
+ Transport is <code>gtalk-p2p</code>, <code>tls</code> means
+ a fake SSL session over TCP as implemented by libjingle.</p>
+ </dd>
+
+ <dt><code>port</code> - q</dt>
+ <dd>The UDP or TCP port of the relay server as an ASCII unsigned
+ integer</dd>
+
+ <dt><code>username</code> - s</dt>
+ <dd>The username to use</dd>
+
+ <dt><code>password</code> - s</dt>
+ <dd>The password to use</dd>
+
+ <dt><code>component</code> - u</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>Transport</tp:member-ref>
+ property. If Transport 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>
+
+
+
</interface>
</node>
<!-- vim:set sw=2 sts=2 et ft=xml: -->
--
1.5.6.5
More information about the telepathy-commits
mailing list