PSA edits

git-svn-id: file:///home/ksmith/gitmigration/svn/xmpp/trunk@3325 4b5297f7-1745-476d-ba37-a9c6900126ab

xep-0260.xml

@@ -63,8 +63,8 @@
 </header>
 
 <section1 topic='Introduction' anchor='intro'>
-  <p>&xep0166; defines a framework for negotiating and managing data sessions over XMPP. In order to provide a flexible framework, the base Jingle specification defines neither data transport methods nor application formats, leaving that up to separate specifications. The current document defines a transport method for establishing and managing data exchanges between XMPP entities using the existing SOCKS5 Bytestreams (S5B) protocol specified in &xep0065;. This "jingle-s5b" method results in a streaming transport method suitable for use in Jingle application types where packet loss cannot be tolerated (e.g., file transfer). Jingle-S5B reuses the protocol flow from <cite>XEP-0065</cite> for the communication with a SOCKS5 streamhost; the communication between two clients to negotiate the possible candidates differ from <cite>XEP-0065</cite> and share similarities to &xep0176;</p>
+  <p>&xep0166; defines a framework for negotiating and managing data sessions over XMPP. In order to provide a flexible framework, the base Jingle specification defines neither data transport methods nor application formats, leaving that up to separate specifications. The current document defines a transport method for establishing and managing data exchanges between XMPP entities using the existing SOCKS5 Bytestreams (S5B) protocol specified in &xep0065;. This "jingle-s5b" method results in a streaming transport method suitable for use in Jingle application types where packet loss cannot be tolerated (e.g., file transfer). Jingle-S5B reuses the protocol flow from <cite>XEP-0065</cite> for the communication with a SOCKS5 streamhost; the communication between two clients to negotiate the possible candidates differs from <cite>XEP-0065</cite> and share similarities with &xep0176;</p>
-  <p>It is RECOMMENDED that a client offers as much &lt;candidate/&gt; elements with itself as host as possible. This includes opening the TCP port on all available interfaces the user wants to use (e.g. maybe not an expensive UMTS link), both the IPv4 and IPv6 of that interface (if available), and using an assisting NAT protocol if possible. If the client knows it is behind and the router announces UPnP IGD or NAT-PMP support, the client SHOULD map the open port to the external interface of the router and include the public IP address and port information in the &lt;candidate/&gt; offers. To increase the chance of success without using a proxy, this specification allows the responder to also send offers.</p>
+  <p>It is RECOMMENDED that a client offers as many &lt;candidate/&gt; elements as possible with itself as the host (i.e., non-proxy candidates). This includes opening the TCP port on all available interfaces the user wants to use (e.g. maybe not an expensive UMTS link), both the IPv4 and IPv6 addresses of that interface (if available), and using an assisting NAT protocol if possible. If the client knows it is behind a NAT and the router announces UPnP IGD or NAT-PMP support, the client SHOULD map the open port to the external interface of the router and include the public IP address and port information in the &lt;candidate/&gt; offers. To increase the chance of success without using a proxy, this specification allows the responder to also send offers.</p>
 </section1>
 
 <section1 topic='Protocol' anchor='protocol'>
@@ -98,7 +98,7 @@ Romeo                               Juliet
   |--------------------------------->|
   |                                  |
   ]]></code>
-  <p>This flow is illustrated in the following examples (to prevent confusion these use a "stub" transport instead of a real application type).</p>
+  <p>This flow is illustrated in the following examples (to simplify the presentation these use a "stub" application instead of a real application type).</p>
   <section2 topic='Exchange Candidates'>
     <p>First the initiator sends a Jingle session-initiate request that contains one or more transport candidates which are a mixture of <cite>XEP-0065</cite> streamhosts and ICE candidates used in <cite>XEP-0176</cite>.</p>
     <example caption="Initiator sends session-initiate (stub)"><![CDATA[
@@ -116,13 +116,13 @@ Romeo                               Juliet
                  sid='vj3hs98y'
         	 mode='tcp'>
         <candidate cid='hft54dqy'
-                   jid='romeo@montague.lit/orchard'
                    host='192.168.4.1'
+                   jid='romeo@montague.lit/orchard'
                    port='5086'
                    priority='8257636'/>
         <candidate cid='hutr46fe'
-                   jid='romeo@montague.lit/orchard'
                    host='24.24.24.1'
+                   jid='romeo@montague.lit/orchard'
                    port='5086'
                    priority='8258636'/>
       </transport>
@@ -155,19 +155,19 @@ Romeo                               Juliet
                  sid='vj3hs98y'
         	 mode='tcp'>
         <candidate cid='ht567dq'
-                   jid='juliet@capulet.lit/balcony'
                    host='192.169.1.10'
-                   port='6539'/>
+                   jid='juliet@capulet.lit/balcony'
+                   port='6539'
                    priority='8257636'/>
         <candidate cid='hr65dqyd'
-                   jid='juliet@capulet.lit/balcony'
                    host='134.102.201.180'
-                   port='16453'/>
+                   jid='juliet@capulet.lit/balcony'
+                   port='16453'
                    priority='7929856'/>
         <candidate cid='grt654q2'
-                   jid='juliet@capulet.lit/balcony'
                    host='2001:638:708:30c9:219:d1ff:fea4:a17d'
-                   port='6539'/>
+                   jid='juliet@capulet.lit/balcony'
+                   port='6539'
                    priority='8257606'/>
       </transport>
     </content>
@@ -185,11 +185,11 @@ Romeo                               Juliet
     <example caption="Priority Calculation"><![CDATA[
 priority = (2^16)*(type preference) + (local preference)
      ]]></example>
-    <p>The type preference is an integer value between 0 and 127. The following types and their preference are defined here:</p>
+    <p>The type preference is an integer value between 0 and 127. The following types and their suggested preference values are defined here:</p>
-    <table caption='Possible Types'>
+    <table caption='Defined Types'>
       <tr>
 	<th>Description</th>
-	<th>Value</th>
+	<th>Preference Value</th>
       </tr>
       <tr>
 	<td>Direct connection using the given interface</td>
@@ -208,7 +208,7 @@ priority = (2^16)*(type preference) + (local preference)
 	<td>10</td>
       </tr>
     </table>
-    <p>The local preference is used to rate different candidates of the same type, e.g. a DSL link may be preferred over a VPN connection. The value of the local preference SHOULD be between 0 and 65535. The proposed values are only guidelines. If a client wants to increase or decrease the value of a specific candidate it is free to do so. For instance, a client may have an expensive UMTS link as last resort and may rate this link lower than all SOCKS5 relays.</p>
+    <p>The local preference is used to rate different candidates of the same type, e.g. a DSL link might be preferred over a VPN connection. The value of the local preference SHOULD be between 0 and 65535. The proposed values are only guidelines. If a client wants to increase or decrease the value of a specific candidate it is free to do so. For instance, a client might have an expensive UMTS link as last resort and might rate this link lower than all SOCKS5 relays.</p>
   </section2>
   <section2 topic='Connecting to Candidates'>
     <p>After receiving its peer's candidates, a client start to connect to them in order of the priority. The protocol is described in <cite>XEP-0065</cite> in detail. Once one client has successfully created a connection, it sends the &lt;candidate-used/&gt; element to the peer inside a transport-info Jingle message. If a client receives a candidate-used information it SHOULD continue trying to connect to candidates of its peer while it has not tried all candidates with a higher priority than the one successfully used by the peer.</p>
@@ -237,7 +237,7 @@ priority = (2^16)*(type preference) + (local preference)
     to='romeo@montague.lit/orchard'
     type='result'/>
   ]]></example>
-    <p>If a client was unable to connect to any candidate of its peer or stopped trying because the peer already send a candidate-used information with a priority higher than its remaining candidates, it sends a candidate-error Jingle transport-info message. If both clients happen to send a candidates-used message with candidates with the same priority, the candidate chosen by the initiator wins (consistent with the rules in <cite>XEP-0166</cite>) and the responder closes the connection it was able to establish.</p>
+    <p>If a client was unable to connect to any candidate of its peer or stopped trying because the peer already send a candidate-used notification with a priority higher than its remaining candidates, it sends a candidate-error Jingle transport-info message. If both clients happen to send a candidates-used message with candidates with the same priority, the candidate chosen by the initiator wins (consistent with the rules in <cite>XEP-0166</cite>) and the responder closes the connection it was able to establish.</p>
     <example caption="Responder sends candidate-error in Jingle transport-info"><![CDATA[
 <iq from='juliet@capulet.lit/balcony'
     id='gft65ewd'
@@ -250,7 +250,7 @@ priority = (2^16)*(type preference) + (local preference)
     <content creator='initiator' name='stub'>
       <transport xmlns='urn:xmpp:jingle:transports:s5b:1'
                  sid='vj3hs98y'>
-        <candidate-error'/>
+        <candidate-error/>
       </transport>
     </content>
   </jingle>
@@ -291,7 +291,7 @@ priority = (2^16)*(type preference) + (local preference)
 </section1>
 
 <section1 topic='Fallback to IBB' anchor='fallback'>
-  <p>The protocol flow is as follows.</p>
+  <p>If the SOCKS5 Bytestreams negotiation fails, the parties might want to "fall back" to the transport of last resort, which for a streaming transport is typically &xep0047; as described for Jingle in &xep0261;. The protocol flow is as follows.</p>
   <code><![CDATA[
 Romeo                               Juliet
   |                                  |
@@ -326,8 +326,8 @@ Romeo                               Juliet
   <jingle xmlns='urn:xmpp:jingle:1'
           action='transport-replace'
           initiator='romeo@montague.lit/orchard'
-          sid='851ba2'>
+          sid='a73sjjvkla37jfea'>
-    <content creator='initiator' name='a-file-offer'>
+    <content creator='initiator' name='stub'>
       <transport xmlns='urn:xmpp:jingle:transports:ibb:0'
                  block-size='4096'
                  sid='ch3d9s71'/>
@@ -351,8 +351,8 @@ Romeo                               Juliet
   <jingle xmlns='urn:xmpp:jingle:1'
           action='transport-accept'
           initiator='romeo@montague.lit/orchard'
-          sid='851ba2'>
+          sid='a73sjjvkla37jfea'>
-    <content creator='initiator' name='a-file-offer'>
+    <content creator='initiator' name='stub'>
       <transport xmlns='urn:xmpp:jingle:transports:ibb:0'
                  block-size='4096'
                  sid='ch3d9s71'/>
@@ -374,9 +374,9 @@ Romeo                               Juliet
   <p>The same processing rules and usage guidelines defined in XEP-0065 apply to the Jingle S5B Transport Method. Additional implementation suggestions are:</p>
   <ol>
     <li>A client SHOULD try the offered candidates in the order of their priority.</li>
-    <li>If more than one &lt;candidate/&gt; element is present a client should wait 200ms before trying the next one.</li>
+    <li>If more than one &lt;candidate/&gt; element is present a client SHOULD wait 200ms before trying the next one.</li>
     <li>If the candidate has a JID attribute and that JID is not the one of the peer it indicates the usage of a proxy. If the client had offered direct connection information it MAY want to wait a little bit longer than 200ms before trying the first proxy.</li>
-    <li>A client should NOT wait for a TCP timeout on connect. If it is unable to connect to any candidate within 5 seconds it should send the candidate-error.</li>
+    <li>A client SHOULD NOT wait for a TCP timeout on connect. If it is unable to connect to any candidate within 5 seconds it SHOULD send a candidate-error.</li>
   </ol>
 </section1>
 
@@ -467,12 +467,12 @@ Romeo                               Juliet
     <xs:complexType>
       <xs:simpleContent>
         <xs:extension base='empty'>
-          <xs:attribute name='jid' type='xs:string' use='optional'/>
           <xs:attribute name='cid' type='xs:string' use='required'/>
-          <xs:attribute name='priority' type='xs:positiveInteger' use='required'/>
           <xs:attribute name='host' type='xs:string' use='required'/>
-          <xs:attribute name='zeroconf' type='xs:string' use='optional'/>
+          <xs:attribute name='jid' type='xs:string' use='optional'/>
           <xs:attribute name='port' type='xs:positiveInteger' use='optional'/>
+          <xs:attribute name='priority' type='xs:positiveInteger' use='required'/>
+          <xs:attribute name='zeroconf' type='xs:string' use='optional'/>
         </xs:extension>
       </xs:simpleContent>
     </xs:complexType>