0.9 RC1 restored <required/> elements, language field, security field, otr field...

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

xep-0155.xml

@@ -25,6 +25,12 @@
   <shortname>chatneg</shortname>
   &stpeter;
   &ianpaterson;
+  <revision>
+    <version>0.9</version>
+    <date>2006-10-05</date>
+    <initials>ip</initials>
+    <remark><p>Added language field; replaced secure field with security field; changed otr field to list-single; several clarifications.</p></remark>
+  </revision>
   <revision>
     <version>0.8</version>
     <date>2006-10-02</date>
@@ -92,8 +98,8 @@
 </section1>
 <section1 topic='Use Cases' anchor='usecases'>
   <section2 topic='Initiating a Chat' anchor='initiate'>
-    <p>In order to initiate a negotiated chat session, the initiating party ("user") sends a &MESSAGE; stanza to the receiving party ("contact") containing a &lt;feature/&gt; child qualified by the 'http://jabber.org/protocol/feature-neg' namespace. The &MESSAGE; stanza MUST NOT contain a &BODY; child element (as specified in &rfc3921;). The &MESSAGE; stanza is used because the user does not necessarily know which of the contact's resources is most available (or indeed if the contact is online). The &MESSAGE; stanza type SHOULD be "normal" (either explicitly or by non-inclusion of the 'type' attribute). The stanza SHOULD include an 'id' attribute and MUST contain a &THREAD; element for tracking purposes (where the newly-generated ThreadID is unique to the proposed session). The data form MUST contain a hidden FORM_TYPE field whose value is "http://jabber.org/protocol/chatneg" and MUST contain a boolean field named "accept". &BOOLEANNOTE;</p>
+    <p>In order to initiate a negotiated chat session, the initiating party ("user") sends a &MESSAGE; <note>The &MESSAGE; stanza is used because the user does not necessarily know which of the contact's resources is most available (or indeed if the contact is online).</note> stanza to the receiving party ("contact") containing a &lt;feature/&gt; child qualified by the 'http://jabber.org/protocol/feature-neg' namespace. The &MESSAGE; stanza MUST NOT contain a &BODY; child element (as specified in &rfc3921;). The &MESSAGE; stanza type SHOULD be "normal" (either explicitly or by non-inclusion of the 'type' attribute). The stanza MAY include an 'id' attribute and MUST contain a &THREAD; element for tracking purposes (where the newly-generated ThreadID is unique to the proposed session). The data form MUST contain a hidden FORM_TYPE field whose value is "http://jabber.org/protocol/chatneg" and MUST contain a boolean field named "accept". &BOOLEANNOTE; The inclusion of "otr" and "security" fields is also RECOMMENDED. Note: The options within any 'list-single' fields SHOULD appear in order of preference.</p>
-    <p>The following is an example of a negotiation request:</p>
+    <p>In the following example of a negotiation request, Romeo requests a chat with Juliet and also queries her regarding whether she wants to enable all message logging (see &xep0136;) <note>A client MUST NOT set the 'otr' field to 'true' unless it has confirmed that its server will allow it to switch off Automated Archiving (see <cite>Message Archiving</cite>).</note> and support the &xep0071; and &xep0085; extensions during this chat session. He also requires that they are both connected securely to their servers, and asks which language she prefers amoungst those he can write. (Note: These fields are examples only; a full set of chat session negotiation parameters will be registered as described in the <link url='#registrar'>XMPP Registrar Considerations</link> section of this document.)</p>
     <example caption="User requests chat session"><![CDATA[
 <message type='normal'
          from='romeo@montague.net/orchard'
@@ -109,26 +115,47 @@
              type='boolean'
              var='accept'>
         <value>true</value>
+        <required/>
+      </field>
+      <field label='Off-The-Record?'
+             type='list-single'
+             var='otr'>
+        <value>false</value>
+        <option label='Allow message logging'>
+          <value>false</value>
+        </option>
+        <option label='Disable all message logging'>
+          <value>true</value>
+        </option>
       </field>
       <field label='Enable XHTML Formatting?'
              type='boolean'
              var='http://jabber.org/protocol/xhtml-im'>
-        <value>0</value>
+        <value>1</value>
       </field>
       <field label='Enable Chat State Notifications?'
              type='boolean'
              var='http://jabber.org/protocol/chatstates'>
-        <value>0</value>
-      </field>
-      <field label='Disable All Message Logging?'
-             type='boolean'
-             var='otr'>
         <value>1</value>
       </field>
-      <field label='Must Both Parties Be Securely Connected to Their Servers?'
+      <field label='Minimum security level'
-             type='boolean'
+             type='list-single'
-             var='secure'>
+             var='security'>
-        <value>1</value>
+        <value>c2s</value>
+        <option label='Both parties must be securely connected to their servers'>
+          <value>c2s</value>
+        </option>
+      </field>
+      <field label='Primary written language of the chat'
+             type='list-single'
+             var='language'>
+        <value>en</value>
+        <option label='English'>
+          <value>en</value>
+        </option>
+        <option label='Italiano'>
+          <value>it</value>
+        </option>
       </field>
       <field label='Reason'
              type='text-single'
@@ -139,10 +166,10 @@
   </feature>
 </message>
     ]]></example>
-    <p>In the foregoing example, Romeo requests a chat with Juliet and also queries her regarding whether she wants to disable all message logging (see &xep0136;) <note>A client MUST NOT set the 'otr' field to 'true' unless it has confirmed that its server will allow it to switch off Automated Archiving (see <cite>Message Archiving</cite>).</note> and support &xep0071; and &xep0085; extensions during this chat session. (Note: These fields are examples only; a full set of chat session negotiation parameters will be registered as described in the <link url='#registrar'>XMPP Registrar Considerations</link> section of this document.)</p>
+    <p>The contact's server delivers the request to the contact's most available resource (which in the examples below happens to be "balcony").</p>
-    <p>Juliet's server delivers Romeo's request to her most available resource (which happens to be "balcony").</p>
+    <p>In any response to the request, the contact's client MUST mirror any 'id' attribute and &THREAD; value so that the user's client can correctly track the response.</p>
-    <p>In any response to the request, the contact's client MUST mirror the 'id' attribute and &THREAD;value so that the user's client can correctly track the response.</p>
+    <p>If the contact's client does not support one of the default values or if the contact has disabled its support (as for Chat State Notifications and XHTML formatting in the example below), and the client can still accept the request, then it MUST set that field to a value that it can support.</p>
-    <p>We assume that Juliet accepts the chat and specifies that she does not want to log messages or use XHTML formatting but that she does want to use Chat State Notifications:</p>
+    <p>In the example below we assume that Juliet accepts the chat and specifies that she prefers to speak Italian with Romeo:</p>
     <example caption="Contact accepts offer and specifies parameters"><![CDATA[
 <message type='normal'
          from='juliet@capulet.com/balcony'
@@ -157,26 +184,30 @@
       <field var='accept'>
         <value>true</value>
       </field>
+      <field var='otr'>
+        <value>false</value>
+      </field>
       <field var='http://jabber.org/protocol/xhtml-im'>
         <value>0</value>
       </field>
       <field var='http://jabber.org/protocol/chatstates'>
-        <value>1</value>
+        <value>0</value>
       </field>
-      <field var='otr'>
+      <field var='security'>
-        <value>1</value>
+        <value>c2s</value>
       </field>
-      <field var='secure'>
+      <field var='language'>
-        <value>1</value>
+        <value>it</value>
       </field>
       <field var='reason'>
-        <value>Sure, let's talk!</value>
+        <value>OK, but I'm too tired to practice my English!</value>
       </field>
     </x>
   </feature>
 </message>
     ]]></example>
-    <p>However, it could be that Juliet is busy so she declines the invitation.</p>
+    <p>If the contact does not want to reveal presence to the user for whatever reason then the contact's client SHOULD return no response or error (see <link url='#security'>Security Considerations</link>). Also, if the contact is using a legacy client then it MAY not support returning any response or error. In both these cases the user MAY, proceed to send stanzas to the contact outside the context of a negotiated chat session.</p>
+    <p>However, if the contact simply prefers not to chat then the client SHOULD decline the invitation:</p>
     <example caption="Contact declines offer and specifies reason"><![CDATA[
 <message type='normal'
          from='juliet@capulet.com/balcony'
@@ -198,105 +229,44 @@
   </feature>
 </message>
     ]]></example>
-    <p>If Juliet's client does not support feature negotiation or does not support the "http://jabber.org/protocol/chatneg" FORM_TYPE, it SHOULD return a &unavailable; error. However, if Juliet does not want to reveal her presence to Romeo for whatever reason, or she is using a legacy client that does not support returning a &unavailable; error, then her client MAY return no error. In this case Romeo MAY, proceed to send stanzas to Juliet outside the context of a negotiated chat session.</p>
+    <p>If the contact's client does not support feature negotiation or does not support the "http://jabber.org/protocol/chatneg" FORM_TYPE, it SHOULD return a &unavailable; error:</p>
     <example caption="Contact returns service unavailable error"><![CDATA[
 <message type='error'
          from='juliet@capulet.com/balcony'
          to='romeo@montague.net/orchard'
          id='init1'>
   <thread>ffd7076498744578d10edabfe7f4a866</thread>
-  <feature xmlns='http://jabber.org/protocol/feature-neg'>
-    <x xmlns='jabber:x:data' type='form'>
-      <field var='FORM_TYPE' type='hidden'>
-        <value>http://jabber.org/protocol/chatneg</value>
-      </field>
-      <field label='Accept this chat?'
-             type='boolean'
-             var='accept'>
-        <value>1</value>
-      </field>
-      <field label='Enable XHTML Formatting?'
-             type='boolean'
-             var='http://jabber.org/protocol/xhtml-im'>
-        <value>0</value>
-      </field>
-      <field label='Enable Chat State Notifications?'
-             type='boolean'
-             var='http://jabber.org/protocol/chatstates'>
-        <value>0</value>
-      </field>
-      <field label='Disable All Message Logging?'
-             type='boolean'
-             var='otr'>
-        <value>1</value>
-      </field>
-      <field label='Must Both Parties Be Securely Connected to Their Servers?'
-             type='boolean'
-             var='secure'>
-        <value>1</value>
-      </field>
-      <field label='Reason'
-             type='text-single'
-             var='reason'>
-        <value>Can we talk?</value>
-      </field>
-    </x>
-  </feature>
   <error code='503' type='cancel'>
     <service-unavailable xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
   </error>
 </message>
     ]]></example>
-    <p>If Juliet's client does not support one of the required features, it SHOULD return a &feature; error (but MAY return no error if, for example, Juliet does not want to reveal her presence to Romeo for whatever reason):</p>
+    <p>If the contact's client does not support one or more of the <em>required</em> features, it SHOULD return a &feature; error and SHOULD specify the field(s) not implemented in a comma-separated list in the XMPP &lt;text/&gt; element:</p>
     <example caption="Contact returns feature not implemented error"><![CDATA[
 <message type='error'
          from='juliet@capulet.com/balcony'
          to='romeo@montague.net/orchard'
          id='init1'>
   <thread>ffd7076498744578d10edabfe7f4a866</thread>
-  <feature xmlns='http://jabber.org/protocol/feature-neg'>
-    <x xmlns='jabber:x:data' type='form'>
-      <field var='FORM_TYPE' type='hidden'>
-        <value>http://jabber.org/protocol/chatneg</value>
-      </field>
-      <field label='Accept this chat?'
-             type='boolean'
-             var='accept'>
-        <value>1</value>
-      </field>
-      <field label='Enable XHTML Formatting?'
-             type='boolean'
-             var='http://jabber.org/protocol/xhtml-im'>
-        <value>0</value>
-      </field>
-      <field label='Enable Chat State Notifications?'
-             type='boolean'
-             var='http://jabber.org/protocol/chatstates'>
-        <value>0</value>
-      </field>
-      <field label='Disable All Message Logging?'
-             type='boolean'
-             var='otr'>
-        <value>1</value>
-      </field>
-      <field label='Must Both Parties Be Securely Connected to Their Servers?'
-             type='boolean'
-             var='secure'>
-        <value>1</value>
-      </field>
-      <field label='Reason'
-             type='text-single'
-             var='reason'>
-        <value>Can we talk?</value>
-      </field>
-    </x>
-  </feature>
   <error code='501' type='cancel'>
     <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
+    <text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>otr</text>
+  </error>
+</message>
+    ]]></example>
+    <p>If the contact's client supports <em>none</em> of the options for one or more fields, it SHOULD return a &notacceptable; error and SHOULD specify the field(s) with unsupported options in a comma-separated list in the XMPP &lt;text/&gt; element:</p>
+    <example caption="Contact returns options not acceptable error"><![CDATA[
+<message type='error'
+         from='juliet@capulet.com/balcony'
+         to='romeo@montague.net/orchard'
+         id='init1'>
+  <thread>ffd7076498744578d10edabfe7f4a866</thread>
+  <error code='501' type='cancel'>
+    <feature-not-implemented xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
+    <text xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'>security</text>
   </error>
 </message>
     ]]></example>
-    <p>If Juliet's client does not support one of the optional features (e.g., Chat State Notifications) but it accepts the request, it MUST set the value of that boolean variable to "0" or "false".</p>
   </section2>
   <section2 topic='Renegotiating a Chat' anchor='renegotiate'>
     <p>At any time during an existing chat session, either party MAY attempt to renegotiate the parameters of the session. The requesting party does this by sending a new &MESSAGE; stanza containing a feature negotiation form and a &THREAD; element with the same value as that of the existing chat session.</p>
@@ -312,30 +282,18 @@
       <field var='FORM_TYPE' type='hidden'>
         <value>http://jabber.org/protocol/chatneg</value>
       </field>
-      <field label='Enable XHTML Formatting?'
+      <field label='Off-The-Record?'
-             type='boolean'
+             type='list-single'
-             var='http://jabber.org/protocol/xhtml-im'>
-        <value>1</value>
-      </field>
-      <field label='Enable Chat State Notifications?'
-             type='boolean'
-             var='http://jabber.org/protocol/chatstates'>
-        <value>1</value>
-      </field>
-      <field label='Disable All Message Logging?'
-             type='boolean'
              var='otr'>
-        <value>1</value>
+        <value>true</value>
-      </field>
+        <option label='Disable all message logging'>
-      <field label='Must Both Parties Be Securely Connected to Their Servers?'
+          <value>true</value>
-             type='boolean'
+        </option>
-             var='secure'>
-        <value>1</value>
       </field>
       <field label='Reason'
              type='text-single'
              var='reason'>
-        <value>Gotta have formatting!</value>
+        <value>Lets keep this private!</value>
       </field>
     </x>
   </feature>
@@ -352,26 +310,17 @@
       <field var='FORM_TYPE' type='hidden'>
         <value>http://jabber.org/protocol/chatneg</value>
       </field>
-      <field var='http://jabber.org/protocol/xhtml-im'>
+      <field var='otr'>
         <value>true</value>
       </field>
-      <field var='http://jabber.org/protocol/chatstates'>
-        <value>1</value>
-      </field>
-      <field var='otr'>
-        <value>1</value>
-      </field>
-      <field var='secure'>
-        <value>1</value>
-      </field>
       <field var='reason'>
-        <value>Agreed, XHTML is fun.</value>
+        <value>Yes, the sys admin might tell our families!</value>
       </field>
     </x>
   </feature>
 </message>
     ]]></example>
-    <p>If the other party's client does not support one of the required features, it SHOULD return a &feature; error instead. In that case the existing negotiated chat session parameters are maintained. Either party MAY then terminate the chat session as specified in the section <link url='#terminate'>Terminating a Chat</link>.</p>
+    <p>If the other party's client does not support one or more of the <em>required</em> features, it SHOULD return a &feature; error instead, while if it supports <em>none</em> of the options for one or more fields, it SHOULD return a &notacceptable; error instead (see <link url='#initiate'>Initiating a Chat</link>). In either of these cases the existing negotiated chat session parameters are maintained. Either party MAY then terminate the chat session as specified in the section <link url='#terminate'>Terminating a Chat</link>.</p>
   </section2>
   <section2 topic='Switching Resources' anchor='switch'>
     <p>Either party MAY use chat renegotiation to attempt to continue the session using another of its resources. The requesting party does this by sending a feature renegotiation form with a "continue" field containing the value of the new resource:</p>
@@ -379,7 +328,7 @@
 <message type='normal'
          from='juliet@capulet.com/balcony'
          to='romeo@montague.net/orchard'
-         id='reneg1'>
+         id='reneg2'>
   <thread>ffd7076498744578d10edabfe7f4a866</thread>
   <feature xmlns='http://jabber.org/protocol/feature-neg'>
     <x xmlns='jabber:x:data' type='form'>
@@ -406,7 +355,7 @@
 <message type='normal'
          from='romeo@montague.net/orchard'
          to='juliet@capulet.com/balcony'
-         id='reneg1'>
+         id='reneg2'>
   <thread>ffd7076498744578d10edabfe7f4a866</thread>
   <feature xmlns='http://jabber.org/protocol/feature-neg'>
     <x xmlns='jabber:x:data' type='submit'>
@@ -516,6 +465,10 @@ However, if the receiving party assumes that the other client will <em>not</em>
       var='accept'
       type='boolean'
       label='Whether to accept the invitation'/>
+  <field
+      var='continue'
+      type='text-single'
+      label='Another resource with which to continue the session'/>
   <field
       var='http://jabber.org/protocol/chatstates'
       type='boolean'
@@ -524,22 +477,45 @@ However, if the receiving party assumes that the other client will <em>not</em>
       var='http://jabber.org/protocol/xhtml-im'
       type='boolean'
       label='Whether to enable XHTML-IM formatting per XEP-0071'/>
+  <field
+      var='language'
+      type='list-single'
+      label='Primary written language of the chat (each value appears in order of preference and conforms to RFC 3066 and the IANA registry)'/>
   <field
       var='otr'
-      type='boolean'
+      type='list-single'
-      label='Off-The-Record: whether to disable absolutely all message logging including automatic archiving - see XEP-0136'/>
+      label='Off-The-Record'>
+    <option label='Allow message logging'>
+      <value>false</value>
+    </option>
+    <option label='Disable absolutely all message logging including automatic archiving - see XEP-0136'>
+      <value>true</value>
+    </option>
+  </field>
   <field
       var='reason'
       type='text-single'
       label='A reason for chatting (or not)'/>
   <field
-      var='continue'
+      var='security'
-      type='text-single'
+      type='list-single'
-      label='Another resource with which to continue the session'/>
+      label='Minimum security level'>
-  <field
+    <option label='Secure connections not required'>
-      var='secure'
+      <value>none</value>
-      type='boolean'
+    </option>
-      label='Whether both parties must be securely connected to their servers'/>
+    <option label='Both parties must be securely connected to their servers'>
+      <value>c2s</value>
+    </option>
+    <option label='Both parties must be securely connected to each other'>
+      <value>e2e</value>
+    </option>
+    <option label='Both parties must be securely connected either to their servers or to each other'>
+      <value>c2sORe2e</value>
+    </option>
+    <option label='Both parties must be securely connected both to their servers and to each other'>
+      <value>c2sANDe2e</value>
+    </option>
+  </field>
   <field
       var='terminate'
       type='boolean'