0.7

xep-0261.xml

@@ -4,13 +4,6 @@
 %ents;
 ]>
 <?xml-stylesheet type='text/xsl' href='xep.xsl'?>
-
-<!-- TODO 
-
-- use 'sid' from S5B, not Jingle
-
--->
-
 <xep>
 <header>
   <title>Jingle In-Band Bytestreams Transport Method</title>
@@ -29,6 +22,12 @@
   <shortname>jingle-ibb</shortname>
   <discuss>jingle</discuss>
   &stpeter;
+  <revision>
+    <version>0.7</version>
+    <date>2011-05-16</date>
+    <initials>psa</initials>
+    <remark><p>Further clarified order of layers, in particular the reuse of IBB &lt;open/&gt; and &lt;close/&gt; elements.</p></remark>
+  </revision>
   <revision>
     <version>0.6</version>
     <date>2011-03-07</date>
@@ -106,18 +105,22 @@ Initiator                   Responder
   |<---------------------------|
   |  IBB "SESSION"             |
   |<==========================>|
+  |  IBB <close/>              |
+  |--------------------------->|
+  |  ack                       |
+  |<---------------------------|
   |  session-terminate         |
   |<---------------------------|
   |  ack                       |
   |--------------------------->|
   |                            |
     ]]></code>
-    <p>This flow is illustrated in the following sections (to prevent confusion these use a "stub" description instead of a real application type).</p>
+    <p>This flow is illustrated in the following sections (to prevent confusion these use an "example" description instead of a real application type).</p>
   </section2>
 
   <section2 topic='Establishing a Bytestream' anchor='protocol-start'>
     <p>First the initiator sends a Jingle session-initiate request.</p>
-    <example caption="Initiator sends session-initiate (stub)"><![CDATA[
+    <example caption="Initiator sends session-initiate"><![CDATA[
 <iq from='romeo@montague.lit/orchard'
     id='xn28s7gk'
     to='juliet@capulet.lit/balcony'
@@ -126,8 +129,8 @@ Initiator                   Responder
           action='session-initiate'
           initiator='romeo@montague.lit/orchard'
           sid='a73sjjvkla37jfea'>
-    <content creator='initiator' name='stub'>
+    <content creator='initiator' name='ex'>
-      <description xmlns='urn:xmpp:jingle:apps:stub:0'/>
+      <description xmlns='urn:xmpp:example'/>
       <transport xmlns='urn:xmpp:jingle:transports:ibb:1'
                  block-size='4096'
                  sid='ch3d9s71'/>
@@ -154,8 +157,8 @@ Initiator                   Responder
           initiator='romeo@montague.lit/orchard'
           responder='juliet@capulet.lit/balcony'
           sid='a73sjjvkla37jfea'>
-    <content creator='initiator' name='stub'>
+    <content creator='initiator' name='ex'>
-      <description xmlns='urn:xmpp:jingle:apps:stub:0'/>
+      <description xmlns='urn:xmpp:example'/>
       <transport xmlns='urn:xmpp:jingle:transports:ibb:1'
                  block-size='2048'
                  sid='ch3d9s71'/>
@@ -227,7 +230,7 @@ Initiator                   Responder
           action='transport-info'
           initiator='romeo@montague.lit/orchard'
           sid='a73sjjvkla37jfea'>
-    <content creator='initiator' name='stub'>
+    <content creator='initiator' name='ex'>
       <transport xmlns='urn:xmpp:jingle:transports:ibb:1'
                  block-size='2048'
                  sid='bt8a71h6'/>
@@ -236,13 +239,27 @@ Initiator                   Responder
 </iq>
     ]]></example>
     <p>Here the Jingle Session ID is the same ("a73sjjvkla37jfea") but the new IBB Session ID ("bt8a71h6") is different from the old IBB Session ID that is already in use ("ch3d9s71").</p>
+    <p>The initiator opens the second session by sending an IBB &lt;open/&gt; element, which the responder acknowledges (not shown).</p>
+    <example caption='Initiator sends IBB &lt;open/&gt;'><![CDATA[
+<iq from='romeo@montague.net/orchard'
+    id='yh3vs613'
+    to='juliet@capulet.com/balcony'
+    type='set'>
+  <open xmlns='http://jabber.org/protocol/ibb'
+        block-size='2048'
+        sid='pd51xa96'
+        stanza='iq'/>
+</iq>
+    ]]></example>
+    <p>The parties can then exchange data over the second session (see <cite>XEP-0047</cite>).</p>
     <p>If a party wishes to close one session within a bytestream, it sends an IBB &lt;close/&gt; element as defined in <cite>XEP-0047</cite> specifying the appropriate IBB SessionID.</p>
-    <example caption='Closing the bytestream'><![CDATA[
+    <example caption='Ending an IBB session'><![CDATA[
 <iq from='romeo@montague.net/orchard'
     id='us71g45j'
     to='juliet@capulet.com/balcony'
     type='set'>
-  <close xmlns='http://jabber.org/protocol/ibb' sid='bt8a71h6'/>
+  <close xmlns='http://jabber.org/protocol/ibb' 
+         sid='bt8a71h6'/>
 </iq>
       ]]></example>
       <p>The receiving party then acknowledges that the IBB session has been closed by returning an IQ-result.</p>
@@ -255,7 +272,8 @@ Initiator                   Responder
   </section2>
 
   <section2 topic='Closing the Bytestream' anchor='protocol-close'>
-    <p>If a party wishes to close the bytestream itself (e.g., because the parties have finished using all sessions associated with the bytestream), it sends a Jingle session-terminate action as defined in <cite>XEP-0166</cite>.</p>
+    <p>Whenever a party is finished with a particular session within the bytestream, it SHOULD send an IBB &lt;close/&gt; as shown above. This applies to all sessions, including the last one.</p>
+    <p>To close the bytestream itself (e.g., because the parties have finished using all sessions associated with the bytestream), a party sends a Jingle session-terminate action as defined in <cite>XEP-0166</cite>.</p>
     <example caption="Initiator terminates the session"><![CDATA[
 <iq from='romeo@montague.lit/orchard'
     id='hz81vf48'
@@ -312,7 +330,7 @@ Initiator                   Responder
     <p>A Jingle implementation SHOULD support security preconditions that are enforced before application media is allowed to flow over the bytestream, such as those described in &xtls;.</p>
   </section2>
   <section2 topic='Use of Base64' anchor='security-base64'>
-    <p>See <cite>XEP-0047</cite> for security considerations related to the user of Base64.</p>
+    <p>See <cite>XEP-0047</cite> for security considerations related to the use of Base64.</p>
   </section2>
 </section1>
 
@@ -336,7 +354,9 @@ Initiator                   Responder
     <code><![CDATA[
 <transport>
   <name>ibb</name>
-  <desc>A method for data exchange over In-Band Bytestreams.</desc>
+  <desc>
+    A method for data exchange over In-Band Bytestreams.
+  </desc>
   <type>streaming</type>
   <doc>XEP-0261</doc>
 </transport>
@@ -358,9 +378,15 @@ Initiator                   Responder
      <xs:complexType>
       <xs:simpleContent>
         <xs:extension base='empty'>
-          <xs:attribute name='block-size' type='xs:short' use='required'/>
+          <xs:attribute name='block-size' 
-          <xs:attribute name='sid' type='xs:string' use='required'/>
+                        type='xs:short' 
-          <xs:attribute name='stanza' use='optional' default='iq'>
+                        use='required'/>
+          <xs:attribute name='sid' 
+                        type='xs:string' 
+                        use='required'/>
+          <xs:attribute name='stanza' 
+                        use='optional' 
+                        default='iq'>
             <xs:simpleType>
               <xs:restriction base='xs:NCName'>
                 <xs:enumeration value='iq'/>