Add some GC3 membership config

Author: Kev

gc3.md

@@ -81,6 +81,8 @@ Client sends an iq set, optionally including the form. Not including the form is
 
 #### Channel responds with result containing join details
 
+This includes the subscription-jid (occupant JID), and also the membership configuration (which could contain fields not part of the join and is in the member-form rather than join-form (QUESTION: do we want to merge these?))
+
 ```xml
 <iq
     to='[email protected]/pda'
@@ -89,6 +91,16 @@ Client sends an iq set, optionally including the form. Not including the form is
     type='result'>
   <joined xmlns="urn:xmpp:gc3:0">
     <subscription-jid>[email protected]</subscription-jid>
+    <x xmlns='jabber:x:data' type='form'>
+      <field type='hidden'
+             var='FORM_TYPE'>
+        <value>urn:xmpp:gc3:member-form</value>
+      </field>
+      <field type='text-single'
+             var='urn:xmpp:gc3:fields:nickname'>
+         <value>Haggish</value>
+      </field>
+    </x>
   </joined>
 </iq>
 ```
@@ -234,6 +246,10 @@ If a user's server does not support gc3pam, a client supporting the fallback mec
 
 ### Channel roles and affiliations
 
+GC3 uses ACL.md for access control, and hats for roles. Perform Hats/ACL queries against the channel JID.
+
+When dual-stacking with MUC (which it's assumed almost all implementations will), Hats of Owner, Admin, Member should exist to map onto the MUC affiliations.
+
 ### Channel configuration
 
 ### Inviting to a channel
@@ -242,6 +258,100 @@ If a user's server does not support gc3pam, a client supporting the fallback mec
 
 ### Configuring a user's membership of the channel (changing nick, xep4 form)
 
+Users can configure their membership of a room (particularly their nickname, but also whatever else the service exposes).
+
+#### Client requests membership form from channel
+
+A client can the membership configuration form from a channel they're in by sending an iq get
+
+```xml
+<iq
+    from='[email protected]/pda'
+    id='ia324fih'
+    to='[email protected]'
+    type='get'>
+  <member-form xmlns="urn:xmpp:gc3:0"/>
+</iq>
+```
+
+The server responds with a form with fields, some of which may be mandatory.
+
+```xml
+<iq
+    to='[email protected]/pda'
+    id='ia324fih'
+    from='[email protected]'
+    type='result'>
+  <member-form xmlns="urn:xmpp:gc3:0">
+    <x xmlns='jabber:x:data' type='form'>
+      <title>Member options</title>
+      <instructions>Fill out this form to configure your membership</instructions>
+      <field type='hidden'
+             var='FORM_TYPE'>
+        <value>urn:xmpp:gc3:member-form</value>
+      </field>
+      <field type='text-single'
+             label='Nickname'
+             var='urn:xmpp:gc3:fields:nickname'>
+         <required/>
+      </field>
+  </member-form>
+</iq>
+```
+
+A field whose var is `urn:xmpp:gc3:fields:nickname` is always the user's nickname in the room, and clients might wish to special-case presentation of this field.
+
+#### Client sends iq to channel with membership details
+
+Client sends an iq set, including the form. Not including a field is an instruction to use the existing value for that field.
+
+```xml
+<iq
+    from='[email protected]/pda'
+    id='39dhs'
+    to='[email protected]'
+    type='set'>
+  <member-form xmlns="urn:xmpp:gc3:0">
+    <x xmlns='jabber:x:data' type='form'>
+      <field type='hidden'
+             var='FORM_TYPE'>
+        <value>urn:xmpp:gc3:member-form</value>
+      </field>
+      <field type='text-single'
+             var='urn:xmpp:gc3:fields:nickname'>
+         <value>Haggish</value>
+      </field>
+    </x>
+  </member-form>
+</iq>
+```
+
+#### Channel responds with result containing membership details
+
+Like the join response.
+
+```xml
+<iq
+    to='[email protected]/pda'
+    id='39dhs'
+    from='[email protected]'
+    type='result'>
+  <member-form xmlns="urn:xmpp:gc3:0">
+    <subscription-jid>[email protected]</subscription-jid>
+    <x xmlns='jabber:x:data' type='form'>
+      <field type='hidden'
+             var='FORM_TYPE'>
+        <value>urn:xmpp:gc3:member-form</value>
+      </field>
+      <field type='text-single'
+             var='urn:xmpp:gc3:fields:nickname'>
+         <value>Haggish</value>
+      </field>
+    </x>
+  </member-form>
+</iq>
+```
+
 ### GC3PAM
 
 * Watches outbound GC3 joins