copy edit

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

xep-0177.xml

@@ -7,7 +7,7 @@
 <xep>
 <header>
   <title>Jingle Raw UDP Transport Method</title>
-  <abstract>This specification defines a Jingle transport method that results in sending media data using raw datagram sockets via the User Datagram Protocol (UDP). This simple transport method does not provide NAT traversal, and the ICE-UDP transport method should be used if NAT traversal is required.</abstract>
+  <abstract>This specification defines a Jingle transport method that results in sending media data using raw datagram associations via the User Datagram Protocol (UDP). This simple transport method does not provide NAT traversal, and the ICE-UDP transport method should be used if NAT traversal is required.</abstract>
   &LEGALNOTICE;
   <number>0177</number>
   <status>Proposed</status>
@@ -126,8 +126,8 @@
 </header>
 
 <section1 topic='Introduction' anchor='intro'>
-  <p>&xep0166; defines a framework for negotiating and managing out-of-band 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 between XMPP entities using a raw User Datagram Protocol (UDP) "association" (see &rfc0768;). This "raw-udp" method results in a datagram transport method suitable for use in media applications where some packet loss is tolerable (e.g., audio and video).</p>
+  <p>&xep0166; defines a framework for negotiating and managing out-of-band 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 between XMPP entities using a raw User Datagram Protocol (UDP) association (see &rfc0768;). This "raw-udp" method results in a datagram transport method suitable for use in media applications where some packet loss is tolerable (e.g., audio and video).</p>
-  <p>Note: The Raw UDP transport does not provide end-to-end traversal of Network Address Translators (NATs), or even basic connectivity checks; if NAT traversal is needed, Jingle clients SHOULD use &ice; as described in &xep0176;. The Raw UDP transport method is defined only for the purpose of specifying the IP address and port that an entity considers "most likely to succeed" and is a "hit-or-miss" method that might work end-to-end in some circumstances (especially when the sending entity is a gateway or relay, for example when a back-to-back user agent or call manager sends an early media offer to the initiator on behalf of the responder, as described in &xep0167;).</p>
+  <p>The Raw UDP transport does not provide end-to-end traversal of Network Address Translators (NATs), or even basic connectivity checks; if NAT traversal is needed, Jingle clients SHOULD use &ice; as described in &xep0176;. The Raw UDP transport method is defined only for the purpose of specifying the IP address and port that an entity considers "most likely to succeed" and is a "hit-or-miss" method that might work end-to-end in some circumstances (especially when the sending entity is a gateway or relay, for example when a back-to-back user agent or call manager sends an early media offer to the initiator on behalf of the responder, as described in &xep0167;).</p>
 </section1>
 
 <section1 topic='Requirements' anchor='reqs'>
@@ -151,7 +151,7 @@
 <section1 topic='Protocol Description' anchor='protocol'>
 
   <section2 topic='Flow' anchor='protocol-flow'>
-    <p>The overall protocol flow for negotiation of the Jingle Raw UDP Transport Method is as follows (note: many of these events happen simultaneously, not in sequence).</p>
+    <p>The overall protocol flow for negotiation of the Jingle Raw UDP Transport Method is as follows.</p>
     <code><![CDATA[
 INITIATOR                            RESPONDER
     |                                    |
@@ -170,10 +170,11 @@ INITIATOR                            RESPONDER
     |<========MEDIA NOW FLOWS===========>|
     |                                    |
     ]]></code>
+    <p>The following sections describe the protocol flow in detail.</p>
   </section2>
 
   <section2 topic='Transport Initiation' anchor='initiate'>
-    <p>In order for the initiator in a Jingle exchange to start the negotiation, it MUST send a Jingle "session-initiate" stanza as described in <cite>XEP-0166</cite>. This stanza MUST include at least one content type. If the initiator wishes to negotiate the Raw UDP transport for a given content type, it MUST include a &TRANSPORT; child element qualified by the 'urn:xmpp:jingle:transports:raw-udp:1' namespace &VNOTE;, which MUST <note>This is required to avoid a round trip and help expedite the negotiation.</note> include the initiator's Raw UDP candidate via the 'ip', 'port', 'generation', and 'id' attributes of the &CANDIDATE; element. The &TRANSPORT; element MAY include more than one &CANDIDATE; element (typically one for RTP and another for RTCP).</p>
+    <p>In order for the initiator in a Jingle exchange to start the negotiation, it sends a Jingle "session-initiate" stanza that includes at least one content type, as described in <cite>XEP-0166</cite>. If the initiator wishes to negotiate the Raw UDP transport for a given content type, it MUST include a &TRANSPORT; child element qualified by the 'urn:xmpp:jingle:transports:raw-udp:1' namespace &VNOTE;, which MUST <note>This is required to avoid a round trip and help expedite the negotiation.</note> include the initiator's Raw UDP candidate via the 'ip', 'port', 'generation', and 'id' attributes of the &CANDIDATE; element. The &TRANSPORT; element MAY include more than one &CANDIDATE; element (typically one for RTP and another for RTCP).</p>
     <example caption="Initiation"><![CDATA[
 <iq from='romeo@montague.net/orchard'
     id='jingle1'
@@ -198,8 +199,8 @@ INITIATOR                            RESPONDER
   </jingle>
 </iq>
     ]]></example>
-    <p>All attributes are REQUIRED. The 'ip' and 'port' attributes are self-explanatory. The 'generation' attribute provides a tracking mechanism for determining which version of this candidate is in force (this is useful if the candidate is redefined mid-stream, for example if the port is changed). The 'id' attribute uniquely identifies this candidate for tracking purposes.</p>
+    <p>All attributes are REQUIRED. The 'ip' and 'port' attributes are self-explanatory. The 'component' attribute enables the parties to distinguish between different aspects of the media stream that each need to use a separate transport address (e.g., RTP and RTCP). The 'generation' attribute defines which version of this candidate is in force (this is useful if the candidate is redefined mid-stream, for example if the port is changed). The 'id' attribute uniquely identifies this candidate for tracking purposes.</p>
-    <p>Note: The "Raw UDP candidate" is the candidate that the entity has reason to believe will be most likely to succeed for that content type, and thus is equivalent to the "default" candidate as described in &ice;. This is not necessarily the entity's preferred address for communication, but instead is the "address most likely to succeed", i.e., the address that is assumed to be reachable by the vast majority of target entities. To determine reachability, the sender needs to classify ahead of time the permissiveness of the NAT or firewall it is behind, if any. It then SHOULD assign the Raw UDP candidate as follows, where the candidate types are as described in <cite>ICE</cite>:</p>
+    <p>Note: The "Raw UDP candidate" is the candidate that the entity has reason to believe will be most likely to succeed for that content type, and thus is equivalent to the "default" candidate as described in the ICE specification. This is not necessarily the entity's preferred address for communication, but instead is the "address most likely to succeed", i.e., the address that is assumed to be reachable by the vast majority of target entities. To determine reachability, the sender needs to classify ahead of time the permissiveness of the NAT or firewall it is behind, if any. It then SHOULD assign the Raw UDP candidate as follows, where the candidate types are as described in <cite>ICE</cite>:</p>
     <table caption='Raw UDP Candidate Assignment'>
       <tr>
         <th>NAT Type</th>
@@ -210,7 +211,7 @@ INITIATOR                            RESPONDER
         <td>Host candidate</td>
       </tr>
       <tr>
-        <td>Symmetric (not permissive)</td>
+        <td>Symmetric</td>
         <td>Relay candidate</td>
       </tr>
       <tr>
@@ -228,7 +229,7 @@ INITIATOR                            RESPONDER
     to='romeo@montague.net/orchard'
     type='result'/>
     ]]></example>
-    <p>Once the responder acknowledges the session initiation request, it SHOULD send its own Raw UDP candidate to the initiator via a Jingle "transport-info" message. It does this by sending a transport-info message to the initiator, as shown in the following example (notice that this example includes two &CANDIDATE; elements, one for RTP and the other for RTCP).</p>
+    <p>As soon as the responder acknowledges the session initiation request, it SHOULD send its own Raw UDP candidate to the initiator via a Jingle "transport-info" message. It does this by sending a transport-info message to the initiator, as shown in the following example (notice that this example includes two &CANDIDATE; elements, one for RTP and the other for RTCP).</p>
     <example caption="Responder sends its Raw UDP candidate"><![CDATA[
 <iq from='juliet@capulet.com/balcony'
     id='jingle2'
@@ -262,7 +263,7 @@ INITIATOR                            RESPONDER
     to='juliet@capulet.com/balcony'
     type='result'/>
     ]]></example>
-    <p>It is then the responsibility of the responder to send accept the session offer.</p>
+    <p>It is then the responsibility of the responder to accept the session offer.</p>
     <example caption="Responder definitively accepts the session"><![CDATA[
 <iq from='juliet@capulet.com/balcony'
     id='accept1'
@@ -315,6 +316,13 @@ INITIATOR                            RESPONDER
   </jingle>
 </iq>
     ]]></example>
+    <p>The other party then acknowledges termination of the session.</p>
+    <example caption="Initiator acknowledges termination"><![CDATA[
+<iq from='romeo@montague.lit/orchard'
+    id='term1'
+    to='juliet@capulet.lit/balcony'
+    type='result'/>
+    ]]></example>
   </section2>
 
 </section1>
@@ -359,14 +367,14 @@ INITIATOR                            RESPONDER
     <p>Upon advancement of this specification from a status of Experimental to a status of Draft, the &REGISTRAR; shall add the foregoing namespace to the registry located at &NAMESPACES;, as described in Section 4 of &xep0053;.</p>
   </section2>
   <section2 topic='Protocol 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>
+    <p>If the protocol defined in this specification undergoes a major revision that is not fully backwards-compatible with an older version, 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 Transport Methods' anchor='registrar-transports'>
     <p>The XMPP Registrar shall include "raw-udp" in its registry of Jingle transport methods. The registry submission is as follows:</p>
     <code><![CDATA[
 <transport>
   <name>raw-udp</name>
-  <desc>A method for exchanging data over raw UDP datagrams.</desc>
+  <desc>A method for exchanging data over raw UDP associations.</desc>
   <type>datagram</type>
   <doc>XEP-0177</doc>
 </transport>