This section provides a friendly introduction to Jingle file transfer.
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):
The initiator then sends a Jingle session-initiation request to a potential responder. The content-type of the request specifies two things:
In this example, the initiator is <kingclaudius@shakespeare.lit>, the responder is <laertes@shakespeare.lit>, and the initiation request specifies a file offer and a transport method of bytestreams (i.e., XEP-0065).
@@ -138,12 +150,12 @@ Claudius Laertes id='jingle1' to='laertes@shakespeare.lit/castle' type='set'> -The initiator then attempts to initiate a SOCKS5 Bytestream with the responder.
+The initiator then attempts to initiate a SOCKS5 Bytestream with the responder (see XEP-0065 for details).
XEP-0096 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 <content/> element (each with a different proposed transport method) and the responder removes all but its desired transport method before the session is accepted.
-The protocol flow is as follows:
+The session flow is as follows.
|
| |
]]>
+ The protocol flow is as follows.
First the initiator sends a Jingle session-initiate, in this case with multiple transports (SOCKS5 Bytestreams and IBB).
Currently, XEP-0096 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.
-The protocol flow is as follows:
+The session flow is as follows.
|
@@ -432,6 +445,10 @@ Claudius Laertes
|---------------------------->|
| ack |
|<----------------------------|
+ | content-remove (SOCK5) |
+ |<----------------------------|
+ | ack |
+ |---------------------------->|
| [ IBB negotiation ] |
|<--------------------------->|
| session-accept |
@@ -446,18 +463,19 @@ Claudius Laertes
|---------------------------->|
| |
]]>
+ The protocol flow is as follows.
First the initiator sends a Jingle session-initiate, in this case with a transport of SOCKS5 Bytestreams.
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 request for the file originally offered (note the use of the <request/> element instead of the <offer/> element, since the responder wants the initiator to send the previously-offered file).
-The initiator then acknowledges the content-replace action.
-The responder then sends a Jingle content-remove (deleting SOCKS5 Bytestreams) in order to choose the desired transport, which in this case is IBB.
+The initiator acknowledges receipt of the Jingle content-remove action.
+The initiator then sends an IBB initiation request to the responder.
An application MAY present transport methods in any order, except that the In-Band Bytestreams method MUST be the lowest preference.
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 (XEP-0030) or entity capabilities (XEP-0115). If the initiator knows that the responder supports Jingle file transfer, it SHOULD first attempt negotiation using XEP-0166 rather than XEP-0095.
+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 (XEP-0030) or entity capabilities (XEP-0115). If the initiator knows that the responder supports Jingle file transfer, it SHOULD first attempt negotiation using XEP-0166 rather than XEP-0095.
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 ®ISTRAR; 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.
+This specification defines the following XML namespaces:
+Upon advancement of this specification from a status of Experimental to a status of Draft, the ®ISTRAR; shall add the foregoing namespaces to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.
+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 XEP-0053.
The XMPP Registrar shall include "file-transfer" in its registry of Jingle application formats. The registry submission is as follows:
@@ -690,8 +749,8 @@ Claudius Laertes