0.14rc2

xep-0234.xml

@@ -25,10 +25,20 @@
   <shortname>NOT_YET_ASSIGNED</shortname>
   &stpeter;
   <revision>
-    <version>0.14rc1</version>
+    <version>0.14rc2</version>
-    <date>2011-06-23</date>
+    <date>2011-06-24</date>
     <initials>psa</initials>
-    <remark><p>Defined file description format separate from XEP-0096; modified the checksum format to reuse the &lt;hashes/&gt; element from XEP-0300; removed the 'urn:xmpp:jingle:apps:file-transfer:info:2' namespace by putting all elements into the 'urn:xmpp:jingle:apps:file-transfer:3' namespace; incremented namespace version from 2 to 3.</p></remark>
+    <remark>
+      <ul>
+        <li>Defined file description format separate from XEP-0096</li>
+        <li>Modified the checksum format to reuse the &lt;hashes/&gt; element from incoming proposal</li>
+        <li>Described the process of aborting a file transfer.</li>
+        <li>Clarified the order of events (Jingle, then transport) when the session is terminated</li>
+        <li>Added section on determining spport, including service discovery feature for multi-file support</li>
+        <li>Removed the 'urn:xmpp:jingle:apps:file-transfer:info:2' namespace by putting all elements into the 'urn:xmpp:jingle:apps:file-transfer:3' namespace</li>
+        <li>Incremented namespace version from 2 to 3</li>
+      </ul>
+    </remark>
   </revision>
   <revision>
     <version>0.13</version>
@@ -350,6 +360,7 @@ Initiator                    Responder
   </jingle>
 </iq>
   ]]></example>
+  <p>After terminating the session, the parties would close the data transport as described in the relevant specification (e.g., <cite>XEP-0260</cite> or <cite>XEP-0261</cite>).</p>
   <p>For a description of the transport fallback scenario (from SOCKS5 Bytestreams to In-Band Bytestreams), refer to <cite>XEP-0260</cite>.</p>
 </section1>
 
@@ -376,6 +387,45 @@ Initiator                    Responder
   ]]></example>
 </section1>
 
+<section1 topic='Aborting a Transfer' anchor='abort'>
+  <p>If either party wishes to abort the transfer of a file but not the entire session (e.g., when the parties are exchanging multiple files), it SHOULD send a Jingle session-info message containing an &lt;abort/&gt; child element qualified by the 'urn:xmpp:jingle:apps:file-transfer:3' namespace.</p>
+  <example caption="Initiator aborts transfer of file"><![CDATA[
+<iq from='romeo@montague.lit/orchard'
+    id='hv9sx61j'
+    to='juliet@capulet.lit/balcony'
+    type='set'>
+  <jingle xmlns='urn:xmpp:jingle:1'
+          action='session-info'
+          initiator='romeo@montague.lit/orchard'
+          sid='a73sjjvkla37jfea'>
+    <abort xmlns='urn:xmpp:jingle:apps:file-transfer:3'>
+      <file>
+        <hashes xmlns='urn:xmpp:hashes:0'>
+          <hash algo='sha-1'>a749930852c69ae5d2141d3766b1552d</hash>
+        </hashes>
+      </file>
+    </abort>
+  </jingle>
+</iq>
+  ]]></example>
+  <p>If either party wishes to end the entire file transfer session instead of aborting transfer of a particular file, it MUST instead send a session-terminate message containing a reason of &lt;cancel/&gt; as described in <cite>XEP-0166</cite>.</p>
+  <example caption="Receiver sends session-terminate"><![CDATA[
+<iq from='juliet@capulet.lit/balcony'
+    id='og61bvs98'
+    to='romeo@montague.lit/orchard'
+    type='set'>
+  <jingle xmlns='urn:xmpp:jingle:1'
+          action='session-terminate'
+          sid='a73sjjvkla37jfea'>
+    <reason>
+      <cancel/>
+    </reason>
+  </jingle>
+</iq>
+  ]]></example>
+  <p>After terminating the session, the parties would close the data transport as described in the relevant specification (e.g., <cite>XEP-0260</cite> or <cite>XEP-0261</cite>).</p>
+</section1>
+
 <section1 topic='Requesting a File' anchor='request'>
   <p>If the entity that hosts a file has advertised its existence (or if a previous file transfer attempt has failed and the receiver would like to initiate another attempt), the entity that wishes to receive the file can "pull" the file from the hosting entity. This is done by sending a Jingle session-initiate to the hosting entity, including a &DESCRIPTION; element qualified by the 'urn:xmpp:jingle:apps:file-transfer:3' namespace and containing a &lt;request/&gt; element that defines the requested file.</p>
   <example caption="Receiver requests hosted file"><![CDATA[
@@ -555,13 +605,16 @@ Initiator                    Responder
         <hashes xmlns='urn:xmpp:hashes:0'>
           <hash algo='sha-1'>a749930852c69ae5d2141d3766b1552d</hash>
         </hashes>
+      </file>
     </received>
   </jingle>
 </iq>
   ]]></example>
   <p>The hosting entity SHOULD NOT wait for arrival of the &lt;received/&gt; acknowledgement before starting to send the next file in its list.</p>
   <p>After the recipient has received all of the files, it SHOULD send a final acknowledgement and then terminate the session.</p>
+  <p>After terminating the session, the parties would close the data transport as described in the relevant specification (e.g., <cite>XEP-0260</cite> or <cite>XEP-0261</cite>).</p>
   <p class='box'>OPEN ISSUE: Provide a way for the hosting entity to add more files to the original "manifest"?</p>
+  <p>Support for transferring multiple files is OPTIONAL. If an application supports multi-file exchange, it MUST advertise a service discovery feature of "urn:xmpp:jingle:apps:file-transfer:multi".</p>
 </section1>
 
 <section1 topic='Use of Jingle Actions' anchor='jingle'>
@@ -646,6 +699,33 @@ Initiator                    Responder
   </section2>
 </section1>
 
+<section1 topic='Determining Support' anchor='support'>
+  <p>To advertise its support for the Jingle File Transfer, when replying to service discovery information ("disco#info") requests an entity MUST return URNs for any version of this protocol that the entity supports -- e.g., "urn:xmpp:jingle:apps:file-transfer:3" for this version &VNOTE;.</p>
+  <example caption="Service discovery information request"><![CDATA[
+<iq from='romeo@montague.lit/orchard'
+    id='uw72g176'
+    to='juliet@capulet.lit/balcony'
+    type='get'>
+  <query xmlns='http://jabber.org/protocol/disco#info'/>
+</iq>
+  ]]></example>
+  <example caption="Service discovery information response"><![CDATA[
+<iq from='juliet@capulet.lit/balcony'
+    id='uw72g176'
+    to='romeo@montague.lit/orchard'
+    type='result'>
+  <query xmlns='http://jabber.org/protocol/disco#info'>
+    <feature var='urn:xmpp:jingle:1'/>
+    <feature var='urn:xmpp:jingle:apps:file-transfer:3'/>
+    <feature var='urn:xmpp:jingle:transports:s5b:1'/>
+    <feature var='urn:xmpp:jingle:transports:ibb:1'/>
+  </query>
+</iq>
+  ]]></example>
+  <p>As noted, if an application supports exchange of multiple files, it MUST advertise a service discovery feature of "urn:xmpp:jingle:apps:file-transfer:multi".</p>
+  <p>In order for an application to determine whether an entity supports this protocol, where possible it SHOULD use the dynamic, presence-based profile of service discovery defined in &xep0115;. However, if an application has not received entity capabilities information from an entity, it SHOULD use explicit service discovery instead.</p>
+</section1>
+
 <section1 topic='Security Considerations' anchor='security'>
   <p>For historical reasons and for backward-compatibility with <cite>XEP-0096</cite>, the hashing algorithm used in computing the file checksum defaults to MD5. It is RECOMMENDED for implementations to use stronger hashing algorithms.</p>
   <p>In order to secure the data stream, implementations SHOULD use encryption methods appropriate to the transport method being used. For example, end-to-end encryption can be negotiated over either SOCKS5 Bytestreams or In-Band Bytestreams as described in <cite>XEP-0260</cite> and <cite>XEP-0261</cite>.</p>
@@ -667,6 +747,17 @@ Initiator                    Responder
   <section2 topic='Namespace Versioning' anchor='registrar-versioning'>
     &NSVER;
   </section2>
+  <section2 topic='Service Discovery Features' anchor='registrar-features'>
+    <p>The service discovery feature for advertising support for exchange of multiple files is "urn:xmpp:jingle:apps:file-transfer:multi".</p>
+    <p>The registry submission is as follows.</p>
+    <code caption='Registry Submission'><![CDATA[
+<var>
+  <name>urn:xmpp:jingle:apps:file-transfer:multi</name>
+  <desc>Signals support for exchange of multiple files.</desc>
+  <doc>XEP-0234</doc>
+</var>
+    ]]></code>
+  </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>
     <code><![CDATA[