moparisthebest
/
xeps
mirror of https://github.com/moparisthebest/xeps
1
0
Fork 0
Code Issues Releases Wiki Activity

0.14 

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2570 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2008-12-16 19:41:53 +00:00
parent 8655ef23f9
commit 4f184f67df
1 changed files with 95 additions and 104 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

199
xep-0177.xml
View File

@ -26,6 +26,18 @@
&scottlu;
&hildjj;
&seanegan;
<revision>
<version>0.14</version>
<date>2008-12-16</date>
<initials>psa</initials>
<remark>
<ul>
<li>Removed the &lt;trying/&gt; info message.</li>
<li>Specified that media must be sent but only after session acceptance.</li>
<li>Because the changes are most likely backwards-incompatible, modified protocol version number from 0 to 1 and changed namespace from urn:xmpp:jingle:transports:raw-udp:0 to urn:xmpp:jingle:transports:raw-udp:1.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.13</version>
<date>2008-12-07</date>
@ -112,10 +124,12 @@
<remark><p>Initial version (split from XEP-0166).</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>&xep0166; defines a framework for negotiating and managing out-of-band data sessions over XMPP. In order to provide a flexible framework, the base Jingle specification defines neither data transport methods nor application formats, leaving that up to separate specifications. The current document defines a transport method for establishing and managing data between XMPP entities using a raw User Datagram Protocol (UDP) "connection" (see &rfc0768;). This "raw-udp" method results in a datagram transport method suitable for use in media applications where some packet loss is tolerable (e.g., audio and video).</p>
<p>Note: The Raw UDP transport does not provide end-to-end traversal of Network Address Translators (NATs); if NAT traversal is needed, Jingle clients SHOULD use &ice; as described in &xep0176;. The Raw UDP transport method is defined only for the purpose of specifying the IP address and port that an entity considers "most likely to succeed" and is a "hit-or-miss" method that might work end-to-end in some circumstances (especially when the sending entity is a gateway or relay, for example when a back-to-back user agent or call manager sends an early media offer to the initiator on behalf of the responder, as described in &xep0167;).</p>
<p>&xep0166; defines a framework for negotiating and managing out-of-band data sessions over XMPP. In order to provide a flexible framework, the base Jingle specification defines neither data transport methods nor application formats, leaving that up to separate specifications. The current document defines a transport method for establishing and managing data between XMPP entities using a raw User Datagram Protocol (UDP) "association" (see &rfc0768;). This "raw-udp" method results in a datagram transport method suitable for use in media applications where some packet loss is tolerable (e.g., audio and video).</p>
<p>Note: The Raw UDP transport does not provide end-to-end traversal of Network Address Translators (NATs), or even basic connectivity checks; if NAT traversal is needed, Jingle clients SHOULD use &ice; as described in &xep0176;. The Raw UDP transport method is defined only for the purpose of specifying the IP address and port that an entity considers "most likely to succeed" and is a "hit-or-miss" method that might work end-to-end in some circumstances (especially when the sending entity is a gateway or relay, for example when a back-to-back user agent or call manager sends an early media offer to the initiator on behalf of the responder, as described in &xep0167;).</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>The Jingle transport method defined herein is designed to meet the following requirements:</p>
<ol>
@ -133,7 +147,9 @@
<li><p>If multiple components are to be communicated over the transport in the context of the Real-time Transport Protocol (RTP; see &rfc3550;), the component numbered "1" shall be associated with RTP and the component numbered "2" shall be associated with the Real Time Control Protocol (RTCP).</p></li>
</ol>
</section1>
<section1 topic='Protocol Description' anchor='protocol'>
<section2 topic='Flow' anchor='protocol-flow'>
<p>The overall protocol flow for negotiation of the Jingle Raw UDP Transport Method is as follows (note: many of these events happen simultaneously, not in sequence).</p>
<code><![CDATA[
@ -143,10 +159,6 @@ INITIATOR RESPONDER
|----------------------------------->|
| ack |
|<-----------------------------------|
| session-info: trying |
|<-----------------------------------|
| ack |
|----------------------------------->|
| transport-info: candidate |
|<-----------------------------------|
| ack |
@ -159,8 +171,9 @@ INITIATOR RESPONDER
| |
]]></code>
</section2>
<section2 topic='Transport Initiation' anchor='initiate'>
<p>In order for the initiator in a Jingle exchange to start the negotiation, it MUST send a Jingle "session-initiate" stanza as described in <cite>XEP-0166</cite>. This stanza MUST include at least one content type. If the initiator wishes to negotiate the Raw UDP transport for a given content type, it MUST include a &TRANSPORT; child element qualified by the 'urn:xmpp:jingle:transports:raw-udp:0' namespace &VNOTE;, which MUST <note>This is required to avoid a round trip and help expedite the negotiation.</note> include the initiator's Raw UDP candidate via the 'ip', 'port', 'generation', and 'id' attributes of the &CANDIDATE; element. The &TRANSPORT; element MAY include more than one &CANDIDATE; element (typically one for RTP and another for RTCP).</p>
<p>In order for the initiator in a Jingle exchange to start the negotiation, it MUST send a Jingle "session-initiate" stanza as described in <cite>XEP-0166</cite>. This stanza MUST include at least one content type. If the initiator wishes to negotiate the Raw UDP transport for a given content type, it MUST include a &TRANSPORT; child element qualified by the 'urn:xmpp:jingle:transports:raw-udp:1' namespace &VNOTE;, which MUST <note>This is required to avoid a round trip and help expedite the negotiation.</note> include the initiator's Raw UDP candidate via the 'ip', 'port', 'generation', and 'id' attributes of the &CANDIDATE; element. The &TRANSPORT; element MAY include more than one &CANDIDATE; element (typically one for RTP and another for RTCP).</p>
<example caption="Initiation"><![CDATA[
<iq from='romeo@montague.net/orchard'
id='jingle1'
@ -170,11 +183,11 @@ INITIATOR RESPONDER
action='session-initiate'
initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content'>
<content creator='initiator' name='voice'>
<description xmlns='urn:xmpp:jingle:apps:rtp:0' media='audio'>
<payload-type id='18' name='G729'/>
</description>
<transport xmlns='urn:xmpp:jingle:transports:raw-udp:0'>
<transport xmlns='urn:xmpp:jingle:transports:raw-udp:1'>
<candidate component='1'
generation='0'
id='a9j3mnbtu1'
@ -206,6 +219,7 @@ INITIATOR RESPONDER
</tr>
</table>
</section2>
<section2 topic='Responder Response' anchor='response'>
<p>As described in <cite>XEP-0166</cite>, to acknowledge the session initiation request, the responder returns an IQ-result:</p>
<example caption="Responder acknowledges the session-initiate request"><![CDATA[
@ -214,42 +228,8 @@ INITIATOR RESPONDER
to='romeo@montague.net/orchard'
type='result'/>
]]></example>
<p>Once the responder acknowledges the session initiation request, it:</p>
<ol>
<li>MUST attempt to send media data via UDP to the IP and port specified in the initiator's Raw UDP candidate.</li>
<li>MUST send an informational message of &lt;trying/&gt;.</li>
<li>SHOULD send its own Raw UDP candidate to the initiator via a Jingle "transport-info" message.</li>
</ol>
<p>These are done simultaneously in order to ensure that a connection can be made, since the initiator's Raw UDP candidate might not result in success.</p>
<section3 topic='Sending Media' anchor='response-send'>
<p>The responder MUST immediately attempt to send data to the IP and port specified in the initiation request. If all goes well, the data will be received by the initiator and media will flow.</p>
</section3>
<section3 topic='Sending a Trying Message' anchor='response-trying'>
<p>When it attempts to send data to a Raw UDP candidate, a party MUST send an informational message of &lt;trying/&gt;, including the candidate ID for tracking purposes.</p>
<example caption="Responder sends trying message"><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='trying1'
to='romeo@montague.net/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='session-info'
initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'>
<trying xmlns='urn:xmpp:jingle:transports:raw-udp:info:0'
id='a9j3mnbtu1'/>
</jingle>
</iq>
]]></example>
<example caption="Initiator acknowledges trying message"><![CDATA[
<iq from='romeo@montague.lit/orchard'
id='trying1'
to='juliet@capulet.lit/balcony'
type='result'/>
]]></example>
</section3>
<section3 topic='Sending a Candidate' anchor='response-candidate'>
<p>As noted, the responder SHOULD send its own Raw UDP candidate to the initiator by sending a transport-info message to the initiator, as shown in the following example (notice that this example includes two &CANDIDATE; elements, one for RTP and the other for RTCP).</p>
<example caption="Responder sends its Raw UDP candidate"><![CDATA[
<p>Once the responder acknowledges the session initiation request, it SHOULD send its own Raw UDP candidate to the initiator via a Jingle "transport-info" message. It does this by sending a transport-info message to the initiator, as shown in the following example (notice that this example includes two &CANDIDATE; elements, one for RTP and the other for RTCP).</p>
<example caption="Responder sends its Raw UDP candidate"><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='jingle2'
to='romeo@montague.net/orchard'
@ -258,8 +238,8 @@ INITIATOR RESPONDER
action='transport-info'
initiator='romeo@montague.net/orchard'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='this-is-the-audio-content'>
<transport xmlns='urn:xmpp:jingle:transports:raw-udp:0'>
<content creator='initiator' name='voice'>
<transport xmlns='urn:xmpp:jingle:transports:raw-udp:1'>
<candidate component='1'
generation='0'
id='z7sdjb01hf'
@ -274,36 +254,73 @@ INITIATOR RESPONDER
</content>
</jingle>
</iq>
]]></example>
<p>The initiator MUST then acknowledge receipt by returning an IQ result (or a standard XMPP error).</p>
<example caption="Initiator acknowledges receipt of candidate"><![CDATA[
]]></example>
<p>The initiator MUST then acknowledge receipt by returning an IQ result (or a standard XMPP error).</p>
<example caption="Initiator acknowledges receipt of candidate"><![CDATA[
<iq from='romeo@montague.net/orchard'
id='jingle2'
to='juliet@capulet.com/balcony'
type='result'/>
]]></example>
<p>Naturally, the initiator SHOULD also attempt to send media to the responder as specified above. This media, too, might or might not get through.</p>
</section3>
]]></example>
<p>It is then the responsibility of the responder to send accept the session offer.</p>
<example caption="Responder definitively accepts the session"><![CDATA[
<iq from='juliet@capulet.com/balcony'
id='accept1'
to='romeo@montague.net/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='session-accept'
initiator='romeo@montague.net/orchard'
responder='juliet@capulet.com/balcony'
sid='a73sjjvkla37jfea'>
<content creator='initiator' name='voice'>
<description xmlns='urn:xmpp:jingle:apps:rtp:0' media='audio'>
<payload-type id='18' name='G729'/>
</description>
<transport xmlns='urn:xmpp:jingle:transports:raw-udp:1'>
<candidate component='1'
generation='0'
id='a9j3mnbtu1'
ip='10.1.1.104'
port='13540'/>
</transport>
</content>
</jingle>
</iq>
]]></example>
<p>And the initiator acknowledges the session acceptance.</p>
<example caption="Initiator acknowledges session acceptance"><![CDATA[
<iq from='romeo@montague.net/orchard'
id='accept1'
to='juliet@capulet.com/balcony'
type='result'/>
]]></example>
</section2>
<section2 topic='Informational Messages' anchor='protocol-info'>
<p>Informational messages are sent within the context of the Raw UDP transport to communicate whether the party has attempted to send media. The informational message MUST be an IQ-set containing a &JINGLE; element of type "session-info", where the informational message is a payload element qualified by the 'urn:xmpp:jingle:transports:raw-udp:info:0' namespace &VNOTE;. Only the following payload element is defined:</p>
<table caption='Information Payload Elements'>
<tr>
<th>Element</th>
<th>Meaning</th>
</tr>
<tr>
<td>&lt;trying/&gt;</td>
<td>The party is trying to send media.</td>
</tr>
</table>
<p>Note: Because the informational message is sent in an IQ-set, the receiving party MUST return either an IQ-result or an IQ-error (normally only an IQ-result to acknowledge receipt; no error flows are defined or envisioned at this time).</p>
<section2 topic='Sending Media' anchor='media'>
<p>Upon sending the session-accept action, the responder MUST immediately send media to the initiator. Upon receiving the session-accept action, the initiator MUST immediately send media to the responder.</p>
<p>An implementation SHOULD enforce a timeout on receipt of media, such that if no media is received from the other party within a reasonable period of time, the implementation will consider the session to have failed and therefore send to the other party a Jingle "session-terminate" action with a reason code of &lt;timeout/&gt;.</p>
<example caption="Responder terminates the session"><![CDATA[
<iq from='juliet@capulet.lit/balcony'
id='term1'
to='romeo@montague.lit/orchard'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='session-terminate'
initiator='romeo@montague.lit/orchard'
sid='a73sjjvkla37jfea'>
<reason>
<timeout/>
</reason>
</jingle>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Determining Support' anchor='support'>
<p>If an entity supports the Jingle Raw UDP transport, it MUST return a feature of "urn:xmpp:jingle:transports:raw-udp:0" &VNOTE; in response to &xep0030; information requests.</p>
<p>If an entity supports the Jingle Raw UDP transport, it MUST return a feature of "urn:xmpp:jingle:transports:raw-udp:1" &VNOTE; in response to &xep0030; information requests.</p>
<example caption="Service discovery information request"><![CDATA[
<iq from='romeo@montague.net/orchard'
id='disco1'
@ -318,9 +335,7 @@ INITIATOR RESPONDER
to='romeo@montague.net/orchard'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='urn:xmpp:jingle:transports:raw-udp:0'/>
...
<feature var='urn:xmpp:jingle:transports:raw-udp:1'/>
</query>
</iq>
]]></example>
@ -328,7 +343,7 @@ INITIATOR RESPONDER
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>In order to secure the data stream that is negotiated via the Jingle ICE-UDP transport, implementations SHOULD use encryption methods appropriate to the transport method and media being exchanged (for details regarding RTP sessions, refer to <cite>XEP-0167</cite>).</p>
<p>In order to secure the data stream that is negotiated via the Jingle Raw UDP transport, implementations SHOULD use encryption methods appropriate to the transport method and media being exchanged (for details regarding RTP sessions, refer to <cite>XEP-0167</cite>).</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
@ -337,12 +352,11 @@ INITIATOR RESPONDER
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>This specification defines the following XML namespaces:</p>
<p>This specification defines the following XML namespace:</p>
<ul>
<li>urn:xmpp:jingle:transports:raw-udp:0</li>
<li>urn:xmpp:jingle:transports:raw-udp:info:0</li>
<li>urn:xmpp:jingle:transports:raw-udp:1</li>
</ul>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespaces to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
<p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
</section2>
<section2 topic='Protocol Versioning' anchor='registrar-versioning'>
<p>If the protocol defined in this specification undergoes a major revision that is not fully backward-compatible with an older version, or that contains significant new features, the XMPP Registrar shall increment the protocol version number found at the end of the XML namespaces defined herein, as described in Section 4 of <cite>XEP-0053</cite>.</p>
@ -361,14 +375,13 @@ INITIATOR RESPONDER
</section1>
<section1 topic='XML Schema' anchor='schema'>
<section2 topic='Transport' anchor='schema-transport'>
<code><![CDATA[
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:jingle:transports:raw-udp:0'
xmlns='urn:xmpp:jingle:transports:raw-udp:0'
targetNamespace='urn:xmpp:jingle:transports:raw-udp:1'
xmlns='urn:xmpp:jingle:transports:raw-udp:1'
elementFormDefault='qualified'>
<xs:element name='transport'>
@ -401,33 +414,11 @@ INITIATOR RESPONDER
</xs:simpleType>
</xs:schema>
]]></code>
</section2>
<section2 topic='Informational Messages' anchor='schema-info'>
<code><![CDATA[
<?xml version='1.0' encoding='UTF-8'?>
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:jingle:transports:raw-udp:info:0'
xmlns='urn:xmpp:jingle:transports:raw-udp:info:0'
elementFormDefault='qualified'>
<xs:element name='trying' type='infoElementType'/>
<xs:complexType name='infoElementType'>
<xs:simpleContent>
<xs:extension base='empty'>
<xs:attribute name='id' type='xs:NCName' use='required'/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:schema>
]]></code>
</section2>
]]></code>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to Paul Chitescu, Diana Cionoiu, Olivier Cr&#234;te, Steffen Larsen, Robert McQueen, Mike Ruprecht, and Paul Witty for their feedback.</p>
</section1>
</xep>