moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-21 16:55:07 -05:00
Code Issues Releases Wiki Activity

0.6

Browse Source 
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@763 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2007-04-17 21:07:57 +00:00
parent 78269e486d
commit 3cedbe3b71
2 changed files with 97 additions and 16 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
xep-0177.xml
View File

@ -26,6 +26,12 @@
&scottlu;
&hildjj;
&seanegan;
<revision>
<version>0.6</version>
<date>2007-04-17</date>
<initials>psa</initials>
<remark><p>Specified Jingle conformance, including definition of transport type as lossy; added section on service discovery.</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2007-03-23</date>
@ -58,7 +64,7 @@
</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 content 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;).</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 content 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 lossy transport method suitable for use in media applications where some packet loss is tolerable (e.g., audio and video).</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>The Jingle transport method defined herein is designed to meet the following requirements:</p>
@ -69,6 +75,15 @@
</ol>
<p>Note: The Raw UDP transport does not provide traversal of Network Address Translators (NATs) and is provided only for the purpose of specifying the IP address and port that an entity considers most likely to succeed without the need for NAT traversal. <note>This is also helpful for bootstrapping of Jingle implementation by developers working on a local network.</note> If NAT traversal is needed, &xep0176; SHOULD be used.</p>
</section1>
<section1 topic='Jingle Conformance' anchor='conformance'>
<p>In accordance with Section 8 of <cite>XEP-0166</cite>, this document specifies the following information related to the Jingle Raw UDP transport type:</p>
<ol>
<li><p>The transport negotiation process is defined in the <link url='#protocol'>Protocol Description</link> section of this document.</p></li>
<li><p>The semantics of the &DESCRIPTION; element are defined in the <link url='#initiate'>Transport Initiation</link> section of this document.</p></li>
<li><p>Successful negotiation of the Raw UDP method results in use of a lossy transport that is suitable for applications where some packet loss is tolerable, such as audio and video.</p></li>
<li><p>If multiple components are to be communicated over the transport, the first component shall be associated with the port in the transport initiation stanza and the second component (e.g., for RTCP) shall be associated with a UDP port that is one number higher than the specified port (e.g., if the specified port is 13540 then the port for the second component shall be 13541).</p></li>
</ol>
</section1>
<section1 topic='Protocol Description' anchor='protocol'>
<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 'http://www.xmpp.org/extensions/xep-0177.html#ns' namespace (see <link url='#ns'>Protocol Namespaces</link>), 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 'name' attributes of the &CANDIDATE; element.</p>
@ -121,7 +136,7 @@
</ul>
<p>These are done simultaneously in order to ensure that a connection can be made, since the initiator's Raw UDP candidate may not result in success.</p>
<section3 topic='Checking the Initiator&apos;s Candidate' anchor='response-check'>
<p>The responder MUST immediately attempt to send data to the IP and port specified in the initiation request. Because delivery of UDP data is not necessarily acknowledged, the data can be sent using &rfc0862;; if the data is echoed back, the recipient would then send a Jingle "content-accept" (or "session-accept") action to the initiator.</p>
<p>The responder MUST immediately attempt to send data to the IP and port specified in the initiation request. Because delivery of UDP data is not acknowledged, the data SHOULD be sent using the echo protocol (&rfc0862;) over the IP address and port specified in the Raw UDP candidate; if the data is echoed back, the recipient would then send a Jingle "content-accept" (or "session-accept") action to the initiator.</p>
<example caption="Responder Returns Transport-Accept"><![CDATA[
<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' type='set' id='accept1'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
@ -192,6 +207,30 @@
</section2>
</section1>
<section1 topic='Determining Support' anchor='support'>
<p>If an entity supports the Jingle Raw UDP transport, it MUST return a feature of "http://www.xmpp.org/extensions/xep-0177.html#ns" &NSNOTE; in response to &xep0030; information requests.</p>
<example caption="Service Discovery information request"><![CDATA[
<iq type='get'
from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<example caption="Service Discovery information response"><![CDATA[
<iq type='result'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='disco1'>
<query xmlns='http://jabber.org/protocol/disco#info'>
...
<feature var='http://www.xmpp.org/extensions/xep-0177.html#ns'/>
...
</query>
</iq>
]]></example>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>In order to secure the data stream that is negotiated via the Jingle ICE transport, implementations SHOULD use encryption methods appropriate to the transport method and media being exchanged (for details regarding audio and video exchanges via RTP, refer to <cite>XEP-0167</cite> and <cite>XEP-0180</cite>).</p>
</section1>
@ -210,6 +249,7 @@
<transport>
<name>raw-udp</name>
<desc>A method for exchanging data over a raw UDP connection.</desc>
<type>lossy</type>
<doc>XEP-0176</doc>
</transport>
]]></code>

69
xep-0180.xml
View File

@ -27,6 +27,12 @@
<surname>Chen</surname>
<email>Milton.Chen@vseelab.com</email>
</author>
<revision>
<version>0.6</version>
<date>2007-04-17</date>
<initials>psa</initials>
<remark><p>Specified Jingle conformance, including the need to use a lossy transport and the process of sending and receiving video content.</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2007-03-23</date>
@ -65,7 +71,7 @@
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>&xep0166; can be used to initiate and negotiate a wide range of peer-to-peer sessions. One session type of interest is video exchange. This document specifies a format for describing Jingle video sessions, where the media exchange occurs using the Real-time Transport Protocol (see &rfc3550;).</p>
<p>&xep0166; can be used to initiate and negotiate a wide range of peer-to-peer sessions. One session type of interest is video exchange. This document specifies a format for describing Jingle video sessions, where the media exchange occurs using the Real-time Transport Protocol (see &rfc3550;). Such sessions require the use of a lossy transport method such as &xep0177; or the "ice-udp" method specified in &xep0176;.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
@ -77,6 +83,22 @@
</ol>
</section1>
<section1 topic='Jingle Conformance' anchor='conformance'>
<p>In accordance with Section 8 of <cite>XEP-0166</cite>, this document specifies the following information related to the Jingle Video via RTP application type:</p>
<ol>
<li><p>The content negotiation process is defined in the <link url='#negotiation'>Negotiating a Jingle Video Session</link> section of this document.</p></li>
<li><p>The semantics of the &DESCRIPTION; element are defined in the <link url='#format'>Content Description Format</link> section of this document.</p></li>
<li><p>A mapping of Jingle semantics to the Session Description Protocol is provided in the <link url='#sdp'>Mapping to Session Description Protocol</link> section of this document.</p></li>
<li><p>A Jingle video session MUST use a lossy transport method such as &xep0177; or the "ice-udp" method specified in &xep0176;.</p></li>
<li>
<p>Content is to be sent and received as follows:</p>
<ul>
<li><p>Outbound video content shall be encoded into RTP packets and each packet shall be sent individually over the transport. Each inbound packet received over the transport is an RTP packet.</p></li>
</ul>
</li>
</ol>
</section1>
<section1 topic='Content Description Format' anchor='format'>
<p>A Jingle video session is described by one or more encodings contained within a wrapper &DESCRIPTION; element. In the language of <cite>RFC 4566</cite> these encodings are payload-types; therefore, each &lt;payload-type/&gt; child element specifies an encoding that can be used for the video stream. Such encodings are often used in the context of the Real-time Transfer Protocol (RTP; see <cite>RFC 3550</cite>) but may be used in other contexts as well. The most common encodings for the Audio/Video Profile (AVP) of RTP are listed in &rfc3551; (these "static" types are reserved from payload ID 0 through payload ID 95), although other encodings are allowed (these "dynamic" types use payload IDs 96 to 127) in accordance with the dynamic assignment rules described in Section 3 of <cite>RFC 3551</cite>. The &PAYLOADTYPE; element's 'id' attribute is REQUIRED and its 'name' attribute is RECOMMENDED. The encodings SHOULD be provided in order of preference.</p>
<example caption="Video Description Format"><![CDATA[
@ -146,7 +168,10 @@
<section1 topic='Negotiating a Jingle Video Session' anchor='negotiation'>
<p>When the initiator sends a session-initiate stanza to the receiver, the &DESCRIPTION; element includes all of the payload types that the initiator can receive for Jingle video (each one encapsulated in a separate &PAYLOADTYPE; element):</p>
<example caption="Initiation Example"><![CDATA[
<iq from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' id='jinglevideo1' type='set'>
<iq from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='jinglevideo1'
type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'>
action='session-initiate'
initiator='romeo@montague.net/orchard'
@ -158,14 +183,17 @@
<payload-type id='103' name='L16' clockrate='16000' channels='2'/>
<payload-type id='98' name='x-ISAC' clockrate='8000'/>
</description>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns'/>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'/>
</content>
</jingle>
</iq>
]]></example>
<p>Upon receiving the session-initiate stanza, the receiver determines whether it can provisionally accept the session and proceed with the negotiation. The general Jingle error cases are specified in <cite>XEP-0166</cite>. In addition, the receiver must determine if it supports any of the payload types advertised by the initiator; if it does not, it MUST reject the session by sending a &lt;unsupported-codecs/&gt; error:</p>
<example caption="Receiver Does Not Support Codecs"><![CDATA[
<iq type='error' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jinglevideo1'>
<iq type='error'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='jinglevideo1'>
<error type='cancel'>
<not-acceptable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
<unsupported-codecs xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns-errors'/>
@ -174,11 +202,17 @@
]]></example>
<p>If there is no error, the receiver provisionally accepts the session:</p>
<example caption="Receiver Provisionally Accepts Session"><![CDATA[
<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jinglevideo1' type='result' />
<iq from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='jinglevideo1'
type='result' />
]]></example>
<p>The receiver then should send a list of the payload types that it can receive via a Jingle "content-accept" (or "session-accept") action. The list that the receiver sends MAY include any payload types (not a subset of the payload types sent by the initiator) but SHOULD retain the ID numbers and order specified by the initiator.</p>
<example caption="Receiver Accepts Content Type"><![CDATA[
<iq from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='jinglevideo2' type='set'>
<iq from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='jinglevideo2'
type='set'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'>
action='content-accept'
initiator='romeo@montague.net/orchard'
@ -193,18 +227,24 @@
<payload-type id='8' name='PCMA'/>
<payload-type id='13' name='CN'/>
</description>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns'/>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'/>
</content>
</jingle>
</iq>
]]></example>
<p>The initiator acknowledges the 'content-accept' with an empty IQ result:</p>
<example caption="Initiator Acknowledges Modified Content Description"><![CDATA[
<iq from='romeo@montegue.net/orchard' to='juliet@capulet.com/balcony' id='jinglevideo2' type='result' />
<iq from='romeo@montegue.net/orchard'
to='juliet@capulet.com/balcony'
id='jinglevideo2'
type='result' />
]]></example>
<p>After successful transport negotiation (not shown here), the receiver then accepts the session:</p>
<example caption="Receiver Definitively Accepts the Session"><![CDATA[
<iq type='set' from='juliet@capulet.com/balcony' to='romeo@montague.net/orchard' id='accept1'>
<iq type='set'
from='juliet@capulet.com/balcony'
to='romeo@montague.net/orchard'
id='accept1'>
<jingle xmlns='http://www.xmpp.org/extensions/xep-0166.html#ns'
action='session-accept'
initiator='romeo@montague.net/orchard'
@ -212,7 +252,7 @@
sid='v1d30k1ll3dth3r4d10st4r'>
<content creator='initiator' name='this-is-the-video-content' profile='RTP/AVP'>
<description xmlns='http://www.xmpp.org/extensions/xep-0167.html#ns'/>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns'>
<transport xmlns='http://www.xmpp.org/extensions/xep-0176.html#ns-udp'>
<candidate component='2'
foundation='1'
generation='0'
@ -231,7 +271,10 @@
]]></example>
<p>And the initiator acknowledges session acceptance:</p>
<example caption="Initiator Acknowledges Session Acceptance"><![CDATA[
<iq from='romeo@montague.net/orchard' to='juliet@capulet.com/balcony' id='accept1' type='result' />
<iq from='romeo@montague.net/orchard'
to='juliet@capulet.com/balcony'
id='accept1'
type='result' />
]]></example>
</section1>
@ -330,6 +373,7 @@ bitrate=384000;buffer=2000;config=4e291800
<content>
<name>video-rtp</name>
<desc>Jingle sessions that support video exchange via the Real-time Transport Protocol</desc>
<transport>lossy</transport>
<doc>XEP-0180</doc>
</content>
]]></code>
@ -383,8 +427,5 @@ bitrate=384000;buffer=2000;config=4e291800
</xs:schema>
]]></code>
</section2>
<section2 topic='Informational Messages' anchor='schema-info'>
<p>To follow.</p>
</section2>
</section1>
</xep>