From ff83d6940043aad193144575c5b40937207ef29c Mon Sep 17 00:00:00 2001
From: Steve Kille <Steve Kille>
Date: Fri, 30 Sep 2016 09:10:04 +0100
Subject: [PATCH] Add vCard personal prefence

---
 xep-0369.xml | 63 +++++++++++++++++++++++++++++++++++++++++-----------
 1 file changed, 50 insertions(+), 13 deletions(-)

diff --git a/xep-0369.xml b/xep-0369.xml
index 21da0843..59c92c34 100644
--- a/xep-0369.xml
+++ b/xep-0369.xml
@@ -728,26 +728,63 @@
     </section3>
 
    <section3 topic="User Preferences and Additional Information" anchor="usecase-visibilty-pref">
-     <p>A channel may store additional user preferences and parameters.  Where the channel requires a value to be explicitly a &xep0004; form will be returned in response to the join request with mandatory and optional fields.  If parameters are optional, the user may request to set them. </p>
+     <p>A channel MAY store user preferences and parameters with each user.    There are two preference options.
+       </p>
      <p>
-       A user may set their JID visibility preference to one of the following values:
+       A user  JID visibility preference have the following values:
      </p>
      <ol>
        <li>'Use Channel Default'.   In this setting, the channel default value will be used.  This value is used if another value is not explicitly set.</li>
        <li>'Never Show JID'.  If this is set, JID will never be shared and user will be removed from the channel if its mode changes to JID-visible-mandatory.</li>
-       <li>'Prefer Not Show JID.   If this is set, JID will only be shared if mode is JID-visible-mandatory.</li>
+       <li>'Prefer Not Show JID'.   If this is set, JID will only be shared if mode is JID-visible-mandatory.</li>
      </ol>
      <p>
-       AUTHOR'S NOTE AND QUESTION: Dave Cridland (+1) has suggested.   I would prefer:
-      
-        a) User options be sent in the initial join/>.
-        b) Unknown options are ignored.
-       c) User options can be requested (as a form). If clients require an option to
-        be supported, they should request the form.
-       
-       
+      The user may specify that no Private Messages are to be sent from the channel, and allow vCard retrieval.
      </p>
-     <p>AUTHOR'S NOTE AND QUESTION:  Add protocol specifications  and examples.   Are there any other specific per user values that should be listed here? </p>
+     <p>
+       The following table sets out the standardized user preference values.   A MIX implementation may use other values.
+     </p>
+     <table caption="Standard User Preference Options">
+       <tr><th>Option</th> <th>Values</th><th>Default</th></tr>
+       
+       <tr><td>'JID Visibility'</td> <td>'Use Channel Default', 'Never Show JID',  'Prefer Not Show JID'</td>  <td>'Use Channel Default'</td></tr>
+       
+       <tr><td>'Private Messages'</td><td>'Allow', 'Block'</td> <td>'Allow'</td></tr>
+       
+       <tr><td>'vCard'</td><td>'Allow', 'Block'</td> <td>'Block'</td></tr>
+     </table>
+     
+     <p>When joining a channel, the client may specify one or more preference options.   In the response, the  server MUST specify all of the user preferences supported by the server, with default values if the user has not requested a different value.  The following example shows joining a channel and setting a preference.</p>
+     
+     <example caption="User Joins a Channel and Specifies a preference"><![CDATA[
+<iq type='set'
+    from='hag66@shakespeare.example'
+    to='coven@mix.shakespeare.example'
+    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
+  <join xmlns='urn:xmpp:mix:0'>
+    <subscribe node='urn:xmpp:mix:nodes:messages'/>
+    <subscribe node='urn:xmpp:mix:nodes:presence'/>
+    <user-preference key='JID Visibility' value='Never Show JID'/>
+  </join>
+</iq>
+]]></example>
+     <p>The following example shows a successful join, which also reports all the user preferences. </p>
+     <example caption="Channel Successfully Processes Join and returns the preferences set"><![CDATA[
+<iq type='result'
+    from='coven@mix.shakespeare.example'
+    to='hag66@shakespeare.example'
+    id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
+  <join xmlns='urn:xmpp:mix:0' jid='hag66@shakespeare.example'>
+    <subscribe node='urn:xmpp:mix:nodes:messages'/>
+    <subscribe node='urn:xmpp:mix:nodes:presence'/>
+    <user-preference key='JID Visibility' value='Never Show JID'/>
+    <user-preference key='Private Messages' value='Allow'/>
+    <user-preference key='vCard' value='Block'/>
+  </join>
+</iq>
+]]></example>
+     
+     
    </section3>
 
     <section3 topic='Leaving a Channel' anchor='usecase-user-leaving'>
@@ -1095,7 +1132,7 @@
        Private Messages are used to provide communication with another channel participant through the MIX channel, without the initiating  user knowing the real JID of the channel participant.  A channel MAY support use of Private Messages.  Private messages are standard XMPP messages.   A message goes through a number of stages with different addressing.  This is set out in the following table.
       </p>
       
-      <table>
+      <table caption="Setting From and To when sending Private Messages">
         <tr><th>Message</th><th>From</th><th>To</th></tr>
         
         <tr><td>First Message from Client to MIX Channel</td><td>Full JID of initiator's client</td><td>Proxy bare JID of responder</td></tr>