0.25

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

xep-0166.xml

@@ -26,6 +26,12 @@
   &robmcqueen;
   &seanegan;
   &hildjj;
+  <revision>
+    <version>0.25</version>
+    <date>2008-02-29</date>
+    <initials>psa</initials>
+    <remark><p>More clearly specified the content-replace action (essentially similar to content-add); specified that content-accept shall be sent in response to content-replace; removed content-modify and content-accept from PENDING state; adjusted text regarding initial session negotiation.</p></remark>
+  </revision>
   <revision>
     <version>0.24</version>
     <date>2008-02-28</date>
@@ -384,16 +390,17 @@ Romeo                         Juliet
     <li>Transport methods (the "how")</li>
   </ol>
   <p>This document defines the semantics and syntax for overall session management. It also provides pluggable "slots" for application formats and transport methods, which are specified in separate documents.</p>
-  <p>At the most basic level, the process for negotiating a Jingle session is as follows:</p>
+  <p>At the most basic level, the process for initial negotiation of a Jingle session is as follows (i.e., the actions that can be generated during the PENDING state):</p>
   <ol>
     <li>One user (the "initator") sends to another user (the "responder") a session request with at least one content type.</li>
     <li>If the responder wants to proceed, it acknowledges the session initiation request by sending an IQ result.</li>
-    <li>Both the initiator and responder start exchanging possible transport candidates as quickly as possible (these are sent in quick succession before further negotiation in order to minimize the time required before media data can flow).</li>
+    <li>The parties attempt to set up data transmission over the designated transport method as defined in the relevant specification (e.g., this may involve sending multiple transport-info actions).</li>
-    <li>These candidates are checked for connectivity.</li>
+    <li>Optionally, the responder may remove content types via the content-remove action or change the direction of the media flow via the content-modify action.</li>
-    <li>As soon as the responder finds a candidate over which media can flow, the responder sends to the initiator a "session-accept" action.</li>
+    <li>Optionally, either party may send session-info actions (to inform the other party that it is attempting transport negotiation, that its device is ringing, etc.).</li>
-    <li>The parties start sending media over the negotiated candidate.</li>
+    <li>As soon as the responder determines that data can flow over the designated transport, it sends to the initiator a session-accept action.</li>
+    <li>The parties start sending data over the transport.</li>
   </ol>
-  <p>If the parties later discover a better candidate, they perform a "content-modify" negotiation and then switch to the better candidate. Naturally they can also modify various other parameters related to the session (e.g., adding video to a voice chat).</p>
+  <p>After the initial session negotiation has been completed and the session is in the ACTIVE state, the parties can adjust the session definition. This may involve sending the content-modify and content-remove actions (which are allowed while in the PENDING state), but it may also involve sending the content-add and content-replace actions, which are acknowledged via the content-accept action. In addition, certain transport methods allow continued sending of transport-info actions while in the ACTIVE state. And naturally the parties may send session-info actions at any time.</p>
   <section2 topic='Overall Session Management' anchor='concepts-session'>
     <p>The state machine for overall session management (i.e., the state per Session ID) is as follows:</p>
     <code>
@@ -435,7 +442,7 @@ PENDING  o---------------------+   |
       <li>ACTIVE</li>
       <li>ENDED</li>
     </ol>
-    <p>The actions related to management of the overall Jingle session are as follows:</p>
+    <p>The actions related to management of the overall Jingle session are described in the following table.</p>
     <table caption='Jingle Actions'>
       <tr>
         <th>Action</th>
@@ -443,23 +450,23 @@ PENDING  o---------------------+   |
       </tr>
       <tr>
         <td>content-accept</td>
-        <td>Accept a content-add or content-modify action received from another party.</td>
+        <td>Accept the content type of a session-initiate action, or accept a content-add or content-replace action received from another party.</td>
       </tr>
       <tr>
         <td>content-add</td>
-        <td>Add one or more new content types to the session. The sender MUST specify only the added content-type(s), not the added content-type(s) plus the existing content-type(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definition. This action MUST NOT be sent while the session is in the PENDING state. When a party sends a content-add, it MUST ignore any actions received from the other party until it receives acknowledgement of the content-add. <note>In the event that a session contains two unidirectional streams of the same type because a content-add was issued simultaneously by both parties, it is RECOMMENDED that participants close the duplicate stream in favour of that created by the session initiator, which should be made bidirectional with a 'content-modify' action by the responder.</note></td>
+        <td>Add one or more new content types to the session. The sender MUST specify only the added content-type(s), not the added content-type(s) plus the existing content-type(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definition. This action MUST NOT be sent while the session is in the PENDING state. When a party sends a content-add, it MUST ignore any actions received from the other party until it receives acknowledgement of the content-add. If the recipient wishes to include the new content type in the session, it MUST send a content-accept action to the other party. <note>In the event that a session contains two unidirectional streams of the same type because a content-add was issued simultaneously by both parties, it is RECOMMENDED that participants close the duplicate stream in favor of that created by the session initiator, which should be made bidirectional via a content-modify action sent by the responder.</note></td>
       </tr>
       <tr>
         <td>content-modify</td>
-        <td>Change an existing content type. The sender SHOULD specify only the aspects for which a modification is desired (e.g., if a party wishes to change only the profile then it would send an empty &lt;content/&gt; element with a modified value for the 'profile' attribute; if a party wishes to change only the transport, then it would send a &lt;content/&gt; element that contains only a &lt;transport/&gt; child; etc.). Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definition. The recipient MUST NOT reply to a content-modify action with another content-modify action. <note>If both parties send modify messages at the same time, the modify message from the session initiator MUST trump the modify message from the recipient and the initiator SHOULD return an &unexpected; error to the other party.</note></td>
+        <td>Change the direction of an existing content type thorugh modification of the 'senders' attribute. The recipient MUST NOT reply to a content-modify action with another content-modify action and MUST NOT send a content-accept action in response to the content-modify (but MAY terminate the session if the new directionality is unacceptable, or MAY simply refuse to send or accept application data in the new direction). <note>If both parties send content-modify actions at the same time, the content-modify from the session initiator MUST trump the content-modify from the recipient and the initiator SHOULD return an &unexpected; error to the other party.</note></td>
       </tr>
       <tr>
         <td>content-remove</td>
-        <td>Remove one or more content types from the session. The sender MUST specify only the removed content-type(s), not the removed content-type(s) plus the remaining content-type(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definition. <note>The recipient SHOULD NOT send a content-accept with the new content type definition after receiving a content-remove.</note> <note>A client MUST NOT return an error upon receipt of a 'content-remove' action for a content type that is received after a 'content-remove' action has been sent but before the action has been acknowledged by the peer.</note> <note>If the content-remove results in zero content types for the session, the entity that receives the content-remove SHOULD send a session-terminate action to the other party (since a session with no content types is void).</note></td>
+        <td>Remove one or more content types from the session. The sender MUST specify only the removed content-type(s), not the removed content-type(s) plus the remaining content-type(s). Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definition. Upon receiving a content-remove from the other party, the recipient MUST NOT send a content-accept and MUST NOT continue to negotiate the transport method related to that content type or send application data related to that content type. The recipient MUST NOT send a content-accept in response to a content-remove. <note>A client MUST NOT return an error upon receipt of a 'content-remove' action for a content type that is received after a 'content-remove' action has been sent but before the action has been acknowledged by the peer.</note> <note>If the content-remove results in zero content types for the session, the entity that receives the content-remove SHOULD send a session-terminate action to the other party (since a session with no content types is void).</note></td>
       </tr>
       <tr>
         <td>content-replace</td>
-        <td>Replace the definition of a content type with a new definition. The application type MUST NOT change but the definition of the application type MAY change. The transport method MAY change or MAY be modified.</td>
+        <td>Replace the definition of a content type with a new definition. The application type MUST NOT change but the definition of the application type MAY be modified (e.g., a file offer may be modified to a file request). The transport method MAY be changed (e.g., from &xep0065; to &xep0047;) or the definition of the existing method MAY be modified. The sender MUST specify only the replaced content-type(s), not any existing content-type that has not been replaced. Therefore it is the responsibility of the recipient to maintain a local copy of the current content type definition. This action MUST NOT be sent while the session is in the PENDING state. When a party sends a content-replace, it MUST ignore any actions received from the other party until it receives acknowledgement of the content-replace. If the recipient wishes to include the replaced content type in the session, it MUST send a content-accept action to the other party.</td>
       </tr>
       <tr>
         <td>session-accept</td>
@@ -467,7 +474,7 @@ PENDING  o---------------------+   |
       </tr>
       <tr>
         <td>session-info</td>
-        <td>Send session-level information / messages, such as (for Jingle audio) a ringing message.</td>
+        <td>Send session-level information, such as (for Jingle audio) a ringing message.</td>
       </tr>
       <tr>
         <td>session-initiate</td>
@@ -491,8 +498,34 @@ PENDING  o---------------------+   |
   </section2>
   <section2 topic='Initiation' anchor='protocol-initiate'>
     <p>Once the initiator has discovered which of the responder's XMPP resources is ideal for the desired application format, it sends a session initiation request to the responder. This request is an IQ-set containing a &JINGLE; element qualified by the 'urn:xmpp:tmp:jingle' namespace &NSNOTE;, where the value of the 'action' attribute is "session-initiate" and where the &JINGLE; element contains one or more &CONTENT; elements. Each &CONTENT; element defines a content type to be transferred during the session, and each &CONTENT; element in turn contains one &DESCRIPTION; child element that specifies a desired application format and one &TRANSPORT; child element that specifies a potential transport method. If either party wishes to propose the use of multiple transport methods for the same application format, it must send multiple &CONTENT; elements.</p>
+    <example caption="Initiator sends session-initiate"><![CDATA[
+<iq from='kingclaudius@shakespeare.lit/castle'
+    id='jingle1'
+    to='laertes@shakespeare.lit/castle'
+    type='set'>
+  <jingle xmlns='urn:xmpp:tmp:jingle'
+          action='session-initiate'
+          initiator='kingclaudius@shakespeare.lit/castle'
+          sid='851ba2'>
+    <content creator='initiator' name='a-file-offer'>
+      <description xmlns='urn:xmpp:tmp:jingle:apps:file-transfer'>
+        <offer>
+          <file xmlns='http://jabber.org/protocol/si/profile/file-transfer'
+                name='test.txt'
+                size='1022'
+                hash='552da749930852c69ae5d2141d3766b1'
+                date='1969-07-21T02:56:15Z'>
+            <desc>This is a test. If this were a real file...</desc>
+          </file>
+        </offer>
+      </description>
+      <transport xmlns='urn:xmpp:tmp:jingle:transports:bytestreams'/>
+    </content>
+  </jingle>
+</iq>
+    ]]></example>
     <p>Note: The syntax and semantics of the &DESCRIPTION; and &TRANSPORT; elements are out of scope for this specification, since they are defined in related specifications. The syntax and semantics of the &JINGLE; and &CONTENT; elements are specified in this document under <link url='#def'>Formal Definition</link>.</p>
-    <p>Note: In order to expedite session establishment, the initiator MAY send transport candidates (e.g., for negotiation of the ICE transport) immediately after sending the "session-initiate" message and before receiving acknowledgement from the responder (i.e., the initiator MUST consider the session to be PENDING even before receiving acknowledgement). Given in-order delivery, the responder should receive such "transport-info" messages after receiving the "session-initiate" message (if not, it is appropriate for the responder to return &lt;unknown-session/&gt; errors since according to its state machine the session does not exist).</p>
+    <p>Note: In order to expedite session establishment, the initiator MAY send transport candidates (e.g., for negotiation of the ICE transport) immediately after sending the session-initiate action and before receiving acknowledgement from the responder (i.e., the initiator MUST consider the session to be PENDING even before receiving acknowledgement). Given in-order delivery, the responder should receive such transport-info actions after receiving the session-initiate action (if not, it is appropriate for the responder to return &lt;unknown-session/&gt; errors since according to its state machine the session does not exist).</p>
     <example caption="Receiver returns unknown-session error"><![CDATA[
 <iq from='laertes@shakespeare.lit/castle'
     id='jingle1'
@@ -590,8 +623,9 @@ PENDING  o---------------------+   |
     <p>The allowable negotiations (including content-level and transport-level negotiations) are as follows:</p>
     <ul>
       <li>Adding a content type via the content-add action (not allowed in the PENDING state).</li>
-      <li>Modifying a content type via the content-modify action.</li>
+      <li>Modifying the communication direction for a content type via the content-modify action.</li>
       <li>Removing a content type via the content-remove action.</li>
+      <li>Changing the definition of a content type via the content-replace action (not allowed in the PENDING state).</li>
       <li>Exchanging transport methods via the transport-info action.</li>
     </ul>
   </section2>
@@ -605,7 +639,7 @@ PENDING  o---------------------+   |
     <p>Once a session is in the ACTIVE state, it may be modified via a content-add, content-modify, content-remove, or transport-info action. Examples of such modifications are shown in the specifications for various application formats and transport methods.</p>
   </section2>
   <section2 topic='Termination' anchor='session-terminate'>
-    <p>In order to gracefully end the session (which MAY be done at any point after acknowledging receipt of the initiation request, including immediately thereafter in order to decline the request), either the responder or the initiator MUST send a "terminate" action to the other party.</p>
+    <p>In order to gracefully end the session (which MAY be done at any point after acknowledging receipt of the initiation request, including immediately thereafter in order to decline the request), either the responder or the initiator MUST send a session-terminate action to the other party.</p>
     <p>The party that terminates the session SHOULD include a &lt;reason/&gt; element that specifies why the session is being terminated. Examples follow.</p>
     <p>One reason for terminating the session is that the terminating party is busy; in this case, the recommended condition is "busy".</p>
     <example caption="Terminating the session (busy)"><![CDATA[
@@ -690,7 +724,7 @@ PENDING  o---------------------+   |
     to='laertes@shakespeare.lit/castle'
     type='result'/>
     ]]></example>
-    <p>Note: As soon as an entity sends a "session-terminate" action, it MUST consider the session to be in the ENDED state (even before receiving acknowledgement from the other party). If the terminating entity receives additional Jingle-related IQ-sets from the other party after sending the "session-terminate" action, it MUST reply with an &lt;unknown-session/&gt; error.</p>
+    <p>Note: As soon as an entity sends a session-terminate action, it MUST consider the session to be in the ENDED state (even before receiving acknowledgement from the other party). If the terminating entity receives additional Jingle-related IQ-sets from the other party after sending the session-terminate action, it MUST reply with an &lt;unknown-session/&gt; error.</p>
     <p>Unfortunately, not all sessions end gracefully. In applications of Jingle that also involve the exchange of presence information, receipt of &UNAVAILABLE; from the other party MAY be considered a session-ending event. However, in this case there is nothing for the party to acknowledge.</p>
   </section2>
   <section2 topic='Informational Messages' anchor='session-info'>
@@ -720,7 +754,7 @@ PENDING  o---------------------+   |
   </error>
 </iq>
     ]]></example>
-    <p>If either party receives an empty "session-info" message for an active session, it MUST send an empty IQ result; this way, an empty "session-info" message may be used as a "ping" to determine session vitality.</p>
+    <p>If either party receives an empty session-info action for an active session, it MUST send an empty IQ result; this way, an empty session-info action may be used as a "ping" to determine session vitality.</p>
     <p>Informational messages are specific to a particular application type or transport method and therefore are described in specifications other than this one.</p>
   </section2>
 </section1>
@@ -861,7 +895,7 @@ PENDING  o---------------------+   |
     <tr>
       <td>&lt;unsupported-info/&gt;</td>
       <td>&feature;</td>
-      <td>The recipient does not support the informational payload of a session-info message.</td>
+      <td>The recipient does not support the informational payload of a session-info action.</td>
     </tr>
   </table>
 </section1>