defined remote-candidate element

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

xep-0176.xml

@@ -29,6 +29,18 @@
   &hildjj;
   &seanegan;
   &robmcqueen;
+  <revision>
+    <version>0.26</version>
+    <date>2009-02-26</date>
+    <initials>psa</initials>
+    <remark><p>Added transport-info payload for communication of the remote candidate.</p></remark>
+  </revision>
+  <revision>
+    <version>0.25</version>
+    <date>2009-02-18</date>
+    <initials>psa</initials>
+    <remark><p>Specified that pwd and ufrag attributes must be included when sending the first candidate; removed rem-addr and rem-port attributes.</p></remark>
+  </revision>
   <revision>
     <version>0.24</version>
     <date>2009-02-17</date>
@@ -295,7 +307,7 @@ INITIATOR                              RESPONDER
     ]]></example>
   </section2>
   <section2 topic='Syntax' anchor='protocol-syntax'>
-    <p>The &TRANSPORT; element's 'pwd' and 'ufrag' attributes MUST be included in the session-initiate request, in subsequent content-add and transport-replace actions, and when offering candidates via the transport-info action. The attributes MAY be included in a session-accept action. The values are separately generated for both the initiator and the responder, in accordance with &icecore; and as shown in the examples. The attributes are defined as follows.</p>
+    <p>The &TRANSPORT; element's 'pwd' and 'ufrag' attributes MUST be included whenever sending one or more candidates to the other party, e.g. in a session-initiate, session-accept, transport-info, content-add, or transport-replace message. The values for these attributes are separately generated for both the initiator and the responder, in accordance with &icecore; and as shown in the examples. The attributes are defined as follows.</p>
     <table caption='Transport Attributes'>
       <tr>
         <th>Name</th>
@@ -392,18 +404,6 @@ INITIATOR                              RESPONDER
         <td>rport value in a=candidate line</td>
         <td>8998</td>
       </tr>
-      <tr>
-        <td>rem-addr</td>
-        <td>A IP address for a remote address as defined in &icecore;.</td>
-        <td>connection-address value in a=remote-candidates line</td>
-        <td>192.0.2.1</td>
-      </tr>
-      <tr>
-        <td>rem-port</td>
-        <td>The port for a remote address as defined in &icecore;.</td>
-        <td>port value in a=remote-candidates line</td>
-        <td>3478</td>
-      </tr>
       <tr>
         <td>type</td>
         <td>A Candidate Type as defined in &icecore;. The allowable values are "host" for host candidates, "prflx" for peer reflexive candidates, "relay" for relayed candidates, and "srflx" for server reflexive candidates.</td>
@@ -420,7 +420,7 @@ INITIATOR                              RESPONDER
     to='romeo@montague.lit/orchard'
     type='result'/>
     ]]></example>
-    <p>Depending on the application type, a user agent controlled by a human user might need to wait for the user to affirm a desire to proceed with the session before continuing. When the user agent has received such affirmation (or if the user agent can automatically proceed for any reason, e.g. because no human intervention is expected or because a human user has configured the user agent to automatically accept sessions with a given entity), it returns a Jingle session-accept message. This message SHOULD also contain a &TRANSPORT; element that in turn contain one &CANDIDATE; element for each of the responder's higher-priority transport candidates, just as for the session-initiate message, but MAY instead be empty (with each candidate to be sent as the payload of a transport-info message).</p>
+    <p>Depending on the application type, a user agent controlled by a human user might need to wait for the user to affirm a desire to proceed with the session before continuing. When the user agent has received such affirmation (or if the user agent can automatically proceed for any reason, e.g. because no human intervention is expected or because a human user has configured the user agent to automatically accept sessions with a given entity), it returns a Jingle session-accept message. This message MUST contain a &TRANSPORT; element qualified by the 'urn:xmpp:jingle:transports:ice-udp:1' namespace, which SHOULD in turn contain one &CANDIDATE; element for each ICE-UDP candidate generated by or known to the responder, but MAY instead be empty (with each candidate to be sent as the payload of a transport-info message).</p>
      <p>Note: See the <link url='#security'>Security Considerations</link> section of this document regarding the exposure of IP addresses on behalf by the responder's client.</p>
     <example caption="Responder accepts the session request"><![CDATA[
 <iq from='juliet@capulet.lit/balcony'
@@ -535,7 +535,30 @@ INITIATOR                  NAT                  RESPONDER
     <p>Note: Here the initiator (controlling agent) is using "aggressive nomination" as described in Section 8.1.1.2 of &icecore; and therefore includes the USE-CANDIDATE attribute in the STUN Binding Requests it sends.</p>
   </section2>
   <section2 topic='Acceptance of Successful Candidate' anchor='protocol-acceptance'>
-    <p>If, based on STUN connectivity checks, the parties determine that they will be able to exchange media between a given pair of local candidates and remote candidates (i.e., the pair is "nominated" and ICE processing is "completed"), they can then begin using that candidate pair to exchange media. There is no need for the parties to communicate the chosen candidate pair in the signalling channel.</p>
+    <p>If, based on STUN connectivity checks, the parties determine that they will be able to exchange media between a given pair of local candidates and remote candidates (i.e., the pair is "nominated" and ICE processing is "completed"), they can then begin using that candidate pair to exchange media.</p>
+    <p>Once the parties have connectivity and therefore the initiator has completed ICE as explained in &icecore;, the initiator MAY communicate the in-use candidate pair in the signalling channel by sending a transport-info message that contains a &lt;remote-candidate/&gt; element (this maps to the SDP "remote-candidates attribute as described in Section B.6 of &icecore;, i.e., remote candidates are "the actual candidates at R that were selected by the offerer", of which there will be only one at this stage of the ICE-UDP negotiation).</p>
+    <example caption="Initiator communicates in-use candidate"><![CDATA[
+<iq from='romeo@montague.lit/orchard'
+   id='pd81b49s'
+   to='juliet@capulet.lit/balcony'
+   type='set'>
+ <jingle xmlns='urn:xmpp:jingle:0'
+         action='transport-info'
+         initiator='romeo@montague.lit/orchard'
+         sid='a73sjjvkla37jfea'>
+   <content creator='initiator' name='this-is-the-audio-content'>
+     <transport xmlns='urn:xmpp:jingle:transports:ice-udp:1'
+                pwd='asd88fgpdd777uzjYhagZg'
+                ufrag='8hhy'>
+       <remote-candidate component'1'
+                         ip='10.0.1.2'
+                         port='9001'/>
+     </transport>
+   </content>
+ </jingle>
+</iq>
+    ]]></example>
+    <p>(In accordance with Jingle core, the responder will also acknowledge the transport-info message.)</p>
     <p>In the unlikely event that one of the parties determines that it cannot establish connectivity even after sending and checking lower-priority candidates, it SHOULD terminate the session as described in <cite>XEP-0166</cite>.</p>
   </section2>
   <section2 topic='Modifying an Existing Candidate' anchor='protocol-modify'>
@@ -1046,12 +1069,20 @@ Romeo                    Gateway                    Juliet
 
   <xs:element name='transport'>
     <xs:complexType>
+      <xs:choice minOccurs='0'>
         <xs:sequence>
           <xs:element name='candidate' 
                       type='candidateElementType'
-                    minOccurs='0' 
+                      minOccurs='1' 
                       maxOccurs='unbounded'/>
         </xs:sequence>
+        <xs:sequence>
+          <xs:element name='remote-candidate' 
+                      type='remoteCandidateElementType'
+                      minOccurs='1' 
+                      maxOccurs='1'/>
+        </xs:sequence>
+      </xs:choice>
       <xs:attribute name='pwd' type='xs:string' use='optional'/>
       <xs:attribute name='ufrag' type='xs:string' use='optional'/>
     </xs:complexType>
@@ -1071,8 +1102,6 @@ Romeo                    Gateway                    Juliet
         <xs:attribute name='protocol' type='xs:NCName' use='required'/>
         <xs:attribute name='rel-addr' type='xs:string' use='optional'/>
         <xs:attribute name='rel-port' type='xs:unsignedShort' use='optional'/>
-        <xs:attribute name='rem-addr' type='xs:string' use='optional'/>
-        <xs:attribute name='rem-port' type='xs:unsignedShort' use='optional'/>
         <xs:attribute name='type' use='required'>
           <xs:simpleType>
             <xs:restriction base='xs:NCName'>
@@ -1087,6 +1116,16 @@ Romeo                    Gateway                    Juliet
     </xs:simpleContent>
   </xs:complexType>
 
+  <xs:complexType name='remoteCandidateElementType'>
+    <xs:simpleContent>
+      <xs:extension base='empty'>
+        <xs:attribute name='component' type='xs:unsignedByte' use='required'/>
+        <xs:attribute name='ip' type='xs:string' use='required'/>
+        <xs:attribute name='port' type='xs:unsignedShort' use='required'/>
+      </xs:extension>
+    </xs:simpleContent>
+  </xs:complexType>
+
   <xs:simpleType name='empty'>
     <xs:restriction base='xs:string'>
       <xs:enumeration value=''/>