1
0
mirror of https://github.com/moparisthebest/xeps synced 2024-10-31 15:35:07 -04:00
git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@2271 4b5297f7-1745-476d-ba37-a9c6900126ab
This commit is contained in:
Peter Saint-Andre 2008-09-25 21:32:30 +00:00
parent c40fd521cf
commit cc04a2ded3

View File

@ -24,6 +24,18 @@
<supersededby/>
<shortname>NOT_YET_ASSIGNED</shortname>
&stpeter;
<revision>
<version>0.7</version>
<date>2008-09-25</date>
<initials>psa</initials>
<remark>
<ul>
<li>Deleted content-replace from session flows.</li>
<li>Modified namespaces to incorporate namespace versioning.</li>
<li>Cleaned up XML schemas.</li>
</ul>
</remark>
</revision>
<revision>
<version>0.6</version>
<date>2008-07-31</date>
@ -99,14 +111,14 @@
<p>This section provides a friendly introduction to Jingle file transfer.</p>
<p>First, the party that wishes to initiate the file transfer determines the responder's capabilities (via &xep0030; or &xep0115;). Here we assume that the responder supports the following service discovery features (note: these features may not reflect final namespace assignments):</p>
<ul>
<li>urn:xmpp:tmp:jingle</li>
<li>urn:xmpp:tmp:jingle:apps:file-transfer</li>
<li>urn:xmpp:tmp:jingle:transports:bytestreams</li>
<li>urn:xmpp:tmp:jingle:transports:ibb</li>
<li>urn:xmpp:jingle:0</li>
<li>urn:xmpp:jingle:apps:file-transfer:0</li>
<li>urn:xmpp:jingle:transports:bytestreams:0</li>
<li>urn:xmpp:jingle:transports:ibb:0</li>
</ul>
<p>The initiator then sends a Jingle session-initiation request to a potential responder. The content-type of the request specifies two things:</p>
<ol>
<li>An application type of "urn:xmpp:tmp:jingle:apps:file-transfer" &NSNOTE;. In particular, the &lt;description/&gt; element contains an &lt;offer/&gt; or &lt;request/&gt; element that in turn contains a &lt;file/&gt; element qualified by the existing 'http://jabber.org/protocol/si/profile/file-transfer' namespace from <cite>XEP-0096</cite>.</li>
<li>An application type of "urn:xmpp:jingle:apps:file-transfer:0" &VNOTE;. In particular, the &lt;description/&gt; element contains an &lt;offer/&gt; or &lt;request/&gt; element that in turn contains a &lt;file/&gt; element qualified by the existing 'http://jabber.org/protocol/si/profile/file-transfer' namespace from <cite>XEP-0096</cite>.</li>
<li>An appropriate transport method. Because the existing transport methods used in <cite>XEP-0096</cite> (i.e., &xep0065; and &xep0047;) are not yet defined as Jingle transport methods, this specification registers those definitions (if this specification is approved, those definitions will be moved to <cite>XEP-0047</cite> and <cite>XEP-0065</cite>).</li>
</ol>
<p>In this example, the initiator is &lt;kingclaudius@shakespeare.lit&gt;, the responder is &lt;laertes@shakespeare.lit&gt;, and the initiation request specifies a file offer and a transport method of bytestreams (i.e., XEP-0065).</p>
@ -138,12 +150,12 @@ Claudius Laertes
id='jingle1'
to='laertes@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
<jingle xmlns='urn:xmpp:jingle:0'
action='session-initiate'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:0'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
@ -154,7 +166,7 @@ Claudius Laertes
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
<transport xmlns='urn:xmpp:jingle:transports:bytestreams:0'/>
</content>
</jingle>
</iq>
@ -166,7 +178,7 @@ Claudius Laertes
to='kingclaudius@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>The initiator then attempts to initiate a SOCKS5 Bytestream with the responder.</p>
<p>The initiator then attempts to initiate a SOCKS5 Bytestream with the responder (see <cite>XEP-0065</cite> for details).</p>
<example caption='Initiation of Interaction'><![CDATA[
<iq type='set'
from='kingclaudius@shakespeare.lit/castle'
@ -214,12 +226,12 @@ STATUS = X'00'
id='accept1'
to='kingclaudius@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
<jingle xmlns='urn:xmpp:jingle:0'
action='session-accept'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:0'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
@ -230,7 +242,7 @@ STATUS = X'00'
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
<transport xmlns='urn:xmpp:jingle:transports:bytestreams:0'/>
</content>
</jingle>
</iq>
@ -250,7 +262,7 @@ STATUS = X'00'
<section1 topic='Scenarios' anchor='scenarios'>
<section2 topic='Transport Selection' anchor='select'>
<p><cite>XEP-0096</cite> enables the initiator to offer more than one transport and for the receiving party to choose its desired transport. This flow can be emulated in Jingle negotiation if the initiator includes more than one &lt;content/&gt; element (each with a different proposed transport method) and the responder removes all but its desired transport method before the session is accepted.</p>
<p>The protocol flow is as follows:</p>
<p>The session flow is as follows.</p>
<code><![CDATA[
Claudius Laertes
| |
@ -277,18 +289,19 @@ Claudius Laertes
|---------------------------->|
| |
]]></code>
<p>The protocol flow is as follows.</p>
<p>First the initiator sends a Jingle session-initiate, in this case with multiple transports (SOCKS5 Bytestreams and IBB).</p>
<example caption="Initiator sends session-initiate with multiple transports"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
id='jingle1'
to='laertes@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
<jingle xmlns='urn:xmpp:jingle:0'
action='session-initiate'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='first-transport'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:0'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
@ -299,10 +312,10 @@ Claudius Laertes
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
<transport xmlns='urn:xmpp:jingle:transports:bytestreams:0'/>
</content>
<content creator='initiator' name='second-transport'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:0'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
@ -313,7 +326,7 @@ Claudius Laertes
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:ibb'/>
<transport xmlns='urn:xmpp:jingle:transports:ibb:0'/>
</content>
</jingle>
</iq>
@ -331,12 +344,12 @@ Claudius Laertes
id='remove1'
to='kingclaudius@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
<jingle xmlns='urn:xmpp:jingle:0'
action='content-remove'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='first-transport'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:0'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
@ -347,7 +360,7 @@ Claudius Laertes
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
<transport xmlns='urn:xmpp:jingle:transports:bytestreams:0'/>
</content>
</jingle>
</iq>
@ -382,12 +395,12 @@ Claudius Laertes
id='accept1'
to='kingclaudius@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
<jingle xmlns='urn:xmpp:jingle:0'
action='session-accept'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:0'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
@ -398,7 +411,7 @@ Claudius Laertes
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
<transport xmlns='urn:xmpp:jingle:transports:bytestreams:0'/>
</content>
</jingle>
</iq>
@ -414,7 +427,7 @@ Claudius Laertes
</section2>
<section2 topic='Fallback' anchor='fallback'>
<p>Currently, <cite>XEP-0096</cite> does not enable the parties to fall back to a second method (e.g., In-Band Bytestreams) if the first method tried (e.g., SOCKS5 Bytestreams) does not work. This problem is addressed by Jingle. Such a fallback scenario is especially helpful when re-using the existing SOCKS5 Bytestreams method, since that method does not necessarily result in NAT or firewall traversal and therefore often results in a failed attempt at setting up the initial transport. However, because In-Band Bytestreams almost always succeeds (except if the parties violate rate-limiting policies at their servers), it provides a reliable transfer method of last resort. To provide seamless fallback, the initiator or responder can counter-propose IBB if S5B setup fails.</p>
<p>The protocol flow is as follows:</p>
<p>The session flow is as follows.</p>
<code><![CDATA[
Claudius Laertes
| |
@ -424,7 +437,7 @@ Claudius Laertes
|<----------------------------|
| [ SOCKS5 failure! ] |
|x---------------------------x|
| content-replace (IBB) |
| content-add (IBB) |
|<----------------------------|
| ack |
|---------------------------->|
@ -432,6 +445,10 @@ Claudius Laertes
|---------------------------->|
| ack |
|<----------------------------|
| content-remove (SOCK5) |
|<----------------------------|
| ack |
|---------------------------->|
| [ IBB negotiation ] |
|<--------------------------->|
| session-accept |
@ -446,18 +463,19 @@ Claudius Laertes
|---------------------------->|
| |
]]></code>
<p>The protocol flow is as follows.</p>
<p>First the initiator sends a Jingle session-initiate, in this case with a transport of SOCKS5 Bytestreams.</p>
<example caption="Initiator sends session-initiate"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
id='jingle1'
to='laertes@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
<jingle xmlns='urn:xmpp:jingle:0'
action='session-initiate'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:0'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
@ -468,7 +486,7 @@ Claudius Laertes
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
<transport xmlns='urn:xmpp:jingle:transports:bytestreams:0'/>
</content>
</jingle>
</iq>
@ -512,18 +530,18 @@ Claudius Laertes
</error>
</iq>
]]></example>
<p>At this point the file transfer has failed using SOCKS5 Bytestreams. However, all is not lost, because the parties can attempt to fall back to In-Band Bytestreams. Therefore the responder sends a content-replace action including a transport of IBB and a <em>request</em> for the file originally offered (note the use of the &lt;request/&gt; element instead of the &lt;offer/&gt; element, since the responder wants the initiator to send the previously-offered file).</p>
<example caption="Responder requests content-replace"><![CDATA[
<p>At this point the file transfer has failed using SOCKS5 Bytestreams. However, all is not lost, because the parties can attempt to fall back to In-Band Bytestreams. Therefore the responder sends a content-add action including a transport of IBB and a <em>request</em> for the file originally offered (note the use of the &lt;request/&gt; element instead of the &lt;offer/&gt; element, since the responder wants the initiator to send the previously-offered file).</p>
<example caption="Responder adds IBB to session"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='replace1'
id='add1'
to='kingclaudius@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
action='content-replace'
<jingle xmlns='urn:xmpp:jingle:0'
action='content-add'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='responder' name='a-file-request'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:0'>
<request>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
hash='552da749930852c69ae5d2141d3766b1'
@ -531,15 +549,15 @@ Claudius Laertes
</file>
</request>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:ibb'/>
<transport xmlns='urn:xmpp:jingle:transports:ibb:0'/>
</content>
</jingle>
</iq>
]]></example>
<p>The initiator then acknowledges the content-replace action.</p>
<example caption="Initiator acknowledges content-replace"><![CDATA[
<p>The initiator then acknowledges the content-add action.</p>
<example caption="Initiator acknowledges content-add"><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
id='replace1'
id='add1'
to='laertes@shakespeare.lit/castle'
type='result'/>
]]></example>
@ -549,12 +567,12 @@ Claudius Laertes
id='accept2'
to='laertes@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
<jingle xmlns='urn:xmpp:jingle:0'
action='content-accept'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='responder' name='a-file-request'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:0'>
<request>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
hash='552da749930852c69ae5d2141d3766b1'
@ -562,7 +580,7 @@ Claudius Laertes
</file>
</request>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:ibb'/>
<transport xmlns='urn:xmpp:jingle:transports:ibb:0'/>
</content>
</jingle>
</iq>
@ -574,6 +592,40 @@ Claudius Laertes
to='kingclaudius@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>The responder then sends a Jingle content-remove (deleting SOCKS5 Bytestreams) in order to choose the desired transport, which in this case is IBB.</p>
<example caption="Responder sends content-remove"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='remove1'
to='kingclaudius@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:jingle:0'
action='content-remove'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='first-transport'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:0'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
size='1022'
hash='552da749930852c69ae5d2141d3766b1'
date='1969-07-21T02:56:15Z'>
<desc>This is a test. If this were a real file...</desc>
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:jingle:transports:bytestreams:0'/>
</content>
</jingle>
</iq>
]]></example>
<p>The initiator acknowledges receipt of the Jingle content-remove action.</p>
<example caption="Responder acknowledges content-remove"><![CDATA[
<iq from='laertes@shakespeare.lit/castle'
id='remove1'
to='kingclaudius@shakespeare.lit/castle'
type='result'/>
]]></example>
<p>The initiator then sends an IBB initiation request to the responder.</p>
<example caption='Initiation of Interaction'><![CDATA[
<iq from='kingclaudius@shakespeare.lit/castle'
@ -597,12 +649,12 @@ Claudius Laertes
id='accept1'
to='kingclaudius@shakespeare.lit/castle'
type='set'>
<jingle xmlns='urn:xmpp:tmp:jingle'
<jingle xmlns='urn:xmpp:jingle:0'
action='session-accept'
initiator='kingclaudius@shakespeare.lit/castle'
sid='851ba2'>
<content creator='initiator' name='a-file-offer'>
<description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
<description xmlns='urn:xmpp:jingle:apps:file-transfer:0'>
<offer>
<file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
name='test.txt'
@ -613,7 +665,7 @@ Claudius Laertes
</file>
</offer>
</description>
<transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
<transport xmlns='urn:xmpp:jingle:transports:bytestreams:0'/>
</content>
</jingle>
</iq>
@ -637,7 +689,7 @@ Claudius Laertes
<p>An application MAY present transport methods in any order, except that the In-Band Bytestreams method MUST be the lowest preference.</p>
</section2>
<section2 topic='Migration from XEP-0096' anchor='impl-migration'>
<p>Support for Jingle file transfer can be determined through discovery of the 'urn:xmpp:tmp:jingle:apps:file-transfer' namespace &NSNOTE;, via either service discovery (<cite>XEP-0030</cite>) or entity capabilities (<cite>XEP-0115</cite>). If the initiator knows that the responder supports Jingle file transfer, it SHOULD first attempt negotiation using XEP-0166 rather than XEP-0095.</p>
<p>Support for Jingle file transfer can be determined through discovery of the 'urn:xmpp:jingle:apps:file-transfer:0' namespace &VNOTE;, via either service discovery (<cite>XEP-0030</cite>) or entity capabilities (<cite>XEP-0115</cite>). If the initiator knows that the responder supports Jingle file transfer, it SHOULD first attempt negotiation using XEP-0166 rather than XEP-0095.</p>
</section2>
</section1>
@ -650,8 +702,15 @@ Claudius Laertes
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<section2 topic='Protocol Namespaces' anchor='ns'>
<p>Until this specification advances to a status of Draft, its associated namespaces shall be 'urn:xmpp:tmp:jingle:apps:file-transfer'. Upon advancement of this specification, the &REGISTRAR; shall issue a permanent namespace in accordance with the process defined in Section 4 of &xep0053;. The namespace 'urn:xmpp:jingle:apps:file-transfer' is requested, and is thought to be unique per the XMPP Registrar's requirements.</p>
<section2 topic='Protocol Namespaces' anchor='registrar-ns'>
<p>This specification defines the following XML namespaces:</p>
<ul>
<li>urn:xmpp:jingle:apps:file-transfer:0</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>
</section2>
<section2 topic='Namespace 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>
</section2>
<section2 topic='Jingle Application Formats' anchor='registrar-content'>
<p>The XMPP Registrar shall include "file-transfer" in its registry of Jingle application formats. The registry submission is as follows:</p>
@ -690,8 +749,8 @@ Claudius Laertes
<xs:schema
xmlns:xs='http://www.w3.org/2001/XMLSchema'
targetNamespace='urn:xmpp:tmp:jingle:apps:file-transfer'
xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'
targetNamespace='urn:xmpp:jingle:apps:file-transfer:0'
xmlns='urn:xmpp:jingle:apps:file-transfer:0'
elementFormDefault='qualified'>
<xs:import
@ -701,30 +760,20 @@ Claudius Laertes
<xs:element name='description'>
<xs:complexType>
<xs:choice>
<xs:element ref='offer'/>
<xs:element ref='request'/>
<xs:element name='offer' type='fileTransferElementType'/>
<xs:element name='request' type='fileTransferElementType'/>
</xs:choice>
</xs:complexType>
</xs:element>
<xs:element name='offer'>
<xs:complexType>
<xs:sequence xmlns:ft='http://jabber.org/protocol/si/profile/file-transfer'>
<xs:element ref='ft:file'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name='request'>
<xs:complexType>
<xs:sequence xmlns:ft='http://jabber.org/protocol/si/profile/file-transfer'>
<xs:element ref='ft:file'/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:complexType name='fileTransferElementType'>
<xs:sequence xmlns:ft='http://jabber.org/protocol/si/profile/file-transfer'>
<xs:element ref='ft:file'/>
</xs:sequence>
</xs:complexType>
</xs:schema>
]]></code>
]]></code>
</section1>
</xep>