moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-27 19:52:18 -05:00
Code Issues Releases Wiki Activity
2e53f9ad30
xeps/xep-0369.xml
Steve Kille 31b8526e59 MIX (XEP-0369) to version 0.9 (#455) 
* XEP-0369: Minor editing

* Small edit following Georg's edits

* Edits to address Georg's comments

* New Proxy JID format.

* Clarify MAM Archive on Send

* Sort Mechanisms to only share JIDs when users prefer to

* Add examples of Real JID lookup and set version date
2017-03-22 09:19:55 -05:00

2636 lines
158 KiB
XML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<?xml version='1.0' encoding='UTF-8'?>
<!DOCTYPE xep SYSTEM 'xep.dtd' [
<!ENTITY % ents SYSTEM 'xep.ent'>
%ents;
]>
<?xml-stylesheet type='text/xsl' href='xep.xsl'?>
<?xml-stylesheet type="text/css" href="xmpp.css"?>
<xep>
<header>
<title>Mediated Information eXchange (MIX)</title>
<abstract>This document defines Mediated Information eXchange (MIX), an XMPP protocol extension for the exchange of information among multiple users through a mediating service. The protocol can be used to provide human group communication and communication between non-human entities using channels, although with greater flexibility and extensibility than existing groupchat technologies such as Multi-User Chat (MUC). MIX uses Publish-Subscribe to provide flexible access and publication, and uses Message Archive Management (MAM) to provide storage and archiving. </abstract>
&LEGALNOTICE;
<number>0369</number>
<status>Experimental</status>
<type>Standards Track</type>
<sig>Standards</sig>
<approver>Council</approver>
<dependencies>
<spec>XMPP Core</spec>
<spec>XMPP IM</spec>
<spec>XEP-0004</spec>
<spec>XEP-0030</spec>
<spec>XEP-0054</spec>
<spec>XEP-0060</spec>
<spec>XEP-0084</spec>
<spec>XEP-0128</spec>
<spec>XEP-0198</spec>
<spec>XEP-0292</spec>
<spec>XEP-0297</spec>
<spec>XEP-0313</spec>
<spec>XEP-0372</spec>
</dependencies>
<supersedes/>
<supersededby/>
<shortname>MIX</shortname>
&ksmithisode;
&skille;
&stpeter;
<revision>
<version>0.9</version>
<date>2017-03-27</date>
<initials>sek</initials>
<remark><p>
Editorial Changes (mainly from Georg Lukas);
Change to new syntax for proxy JIDs;
Clarify MAM archive on Send;
Extend to sort Selected JID visibility;
Add examples of lookup read JID from proxy JID;
</p></remark>
</revision>
<revision>
<version>0.8.2</version>
<date>2017-03-3</date>
<initials>sek</initials>
<remark><p>
Make example ids pseudo-random;
Shorten the example BIND2 resources;
Fix Disco features to not use second namespace;
Correct encoding of jid-multi;
MAM intro clarification;
Always add to roster, with direction of roster controlled by share preference;
</p></remark>
</revision>
<revision>
<version>0.8.1</version>
<date>2017-02-20</date>
<initials>sek</initials>
<remark><p>
Editorial Updates;
Clarify Access to MAM history, prior to user joining channel;
Add option for user to join without presence;
Check invitee supports MIX;
</p></remark>
</revision>
<revision>
<version>0.8</version>
<date>2017-02-13</date>
<initials>sek</initials>
<remark><p>
Update after Brussels Summit;
Remove Explicit Client Activation and replace with client capability discovery (summit 3);
Limit Indirect to Join/Leave;
Clarify Server use of Disco of Client;
Add MIX capability information to Roster (summit 10);
MIX as Core Spec (summit 1);
Clarifications of password control, voice and name/description (summit 4/5/6)
Removal of Subject and reference future Sticky Messages XEP (summit 7);
Use example JIDs aligned to anticipated BIND2 specification;
Clarify PubSub Node Type;
Add Error handling section;
Substantial Editorial Review;
</p></remark>
</revision>
<revision>
<version>0.7.1</version>
<date>2017-01-30</date>
<initials>sek</initials>
<remark><p>
Ensure all RFC 2119 keywords are capitalized and used correctly;
Use MAM ID to identify message;
Clarify use of the various channel names;
Require all client operations to be direct or indirect (choice is just confusing);
Add description of implicit activation ;
MIX Domains must not contain users;
Clarification on identifying channels in rosters;
</p></remark>
</revision>
<revision>
<version>0.7</version>
<date>2017-01-27</date>
<initials>sek</initials>
<remark><p>
Correct multi-language subject setting;
Remove MIX Proxy terminology and replace with Participant Server Behaviour;
</p></remark>
</revision>
<revision>
<version>0.6.5</version>
<date>2017-01-10</date>
<initials>sek</initials>
<remark><p>
Modify MIX Proxy so that client sends to bare JID
</p></remark>
</revision>
<revision>
<version>0.6.4</version>
<date>2017-01-10</date>
<initials>sek</initials>
<remark><p>
Add node='mix' to channel disco to facilitate MIX and MUC co-existence on same node;
Return Proxy JID on Join;
Adjustment to message reflection
</p></remark>
</revision>
<revision>
<version>0.6.3</version>
<date>2016-12-22</date>
<initials>sek</initials>
<remark><p>
Add Update and Distribution to Table 3;
Correct from in messages from channel;
Use XEP-0297 in message forwarding;
Update Dependent XEPs
</p></remark>
</revision>
<revision>
<version>0.6.2</version>
<date>2016-12-21</date>
<initials>sek</initials>
<remark><p>
Editorial Changes (Georg Lukas Review);
Improve 1:1 Conversion;
Sort out MIX Proxy and Presence Update
</p></remark>
</revision>
<revision>
<version>0.6.1</version>
<date>2016-12-05</date>
<initials>sek</initials>
<remark><p>
Clarify Direct PubSub access to each node type.
</p></remark>
</revision>
<revision>
<version>0.6</version>
<date>2016-12-02</date>
<initials>sek (XEP Editor: ssw)</initials>
<remark><p>
Added Internationalization Consideration section, and various I18n edits;
Added Security Considerations section;
Tombstoning of Redaction changes made optional;
Added a section specifying MIX Proxy;
Change configuration and information node management to directly use PubSub;
Provide for XEP-0202 (vCard4 over XMPP) in addition to vcard-temp support.
</p></remark>
</revision>
<revision>
<version>0.5</version>
<date>2016-11-04</date>
<initials>sek (XEP Editor: ssw)</initials>
<remark><p>
Complete and restructure Administration Section: Creating Channels and modifying configuration;
Add avatar nodes;
Add section on roster handling;
Discovering MIX Services;
Resolve questions on future capabilities;
Administration of Allowed/Banned; clarify Kick functionality is replaced;
User Presence Probes on Channel Start-up;
Add user Presence preference;
Clarify and Expand MAM Archiving;
Sort Retraction;
Add Marker IQ;
Conversion 1:1
</p></remark>
</revision>
<revision>
<version>0.4</version>
<date>2016-09-21</date>
<initials>sek</initials>
<remark><p>Clarification of MIX Proxy concept; Clarify node definitions; Make all nodes optional; Merge ACL node into configuration node; Add information node including avatar; Resolve 4.1 question by accepting provisional answer; Add discovery examples; setting and sharing Subject; Protocol to request channel information and participants; vCard Request; Private Messages; Set user preferences with XEP-0004; Remove references to member and occupant; Add Role Definition; Add Banned and Allowed Nodes; Update Configuration Definition;Add information on original id to message reflected back to sender Add XEP-0372 mechanism to reference channel and informal invite; Channel Invitations </p></remark>
</revision>
<revision>
<version>0.3.1</version>
<date>2016-09-07</date>
<initials>sek</initials>
<remark><p>Introduce MIX Proxy concept. Add MIX capability in client discovery.</p></remark>
</revision>
<revision>
<version>0.3</version>
<date>2016-09-05</date>
<initials>sek</initials>
<remark><p>Addressing comments from review of 0.2 and expansion/clarification of MUC/MIX dual working</p></remark>
</revision>
<revision>
<version>0.2.3</version>
<date>2016-09-01</date>
<initials>ssw, ks</initials>
<remark><p>Cleanup, use precis nickname for nicknames, and allow multiple subject languages.</p></remark>
</revision>
<revision>
<version>0.2.2</version>
<date>2016-08-26</date>
<initials>ssw</initials>
<remark><p>Phrasing and grammar.</p></remark>
</revision>
<revision>
<version>0.2.1</version>
<date>2016-08-25</date>
<initials>sek, egp</initials>
<remark><p>Includes Link Mauve (Emmanuel Gil PEYROT) editorial changes</p></remark>
</revision>
<revision>
<version>0.2</version>
<date>2016-08-16</date>
<initials>sek, ks</initials>
<remark><p>Significant update based on XMPP Summit discussions</p></remark>
</revision>
<revision>
<version>0.1.1</version>
<date>2016-03-17</date>
<initials>XEP Editor (ssw)</initials>
<remark><p>Fix XML in join example.</p></remark>
</revision>
<revision>
<version>0.1</version>
<date>2016-01-07</date>
<initials>XEP Editor (asw)</initials>
<remark><p>Initial published version approved by the XMPP Council.</p></remark>
</revision>
<revision>
<version>0.0.1</version>
<date>2015-10-12</date>
<initials>kis/psa</initials>
<remark><p>First draft.</p></remark>
</revision>
</header>
<section1 topic='Introduction' anchor='intro'>
<p>The Mediated Information eXchange (MIX) protocol is intended as a replacement for Multi-User Chat (MUC). MUC is a major application of XMPP that was developed in 2002 and standardized in &xep0045;. MIX implements the same basic MUC patterns in a more flexible and extensible way in order to address requirements that have emerged since MUC was developed. MIX supports all of the core chatroom features that are familiar from MUC, such as discussion topics and invitations. Like MUC, it also defines a strong access control model, including the ability to ban users, to name administrators, and to provide controls as to which users can participate in channels.</p>
<p>Several reasons exist for replacing MUC:</p>
<ul>
<li>A number of use cases for group communication have emerged since MUC was first published.</li>
<li>Experience has shown that it is difficult to use MUC to build several kinds of communication applications (such as a multimedia conference) without undesirable adaptations.</li>
<li>It is impractical to address a number of the requirements listed in the next section with MUC or with extensions to MUC. </li>
<li>In the years after MUC was designed, both &xep0060; and &xep0313; have been developed and it is desirable to reuse these building blocks (e.g., MAM can be used for message history) rather than using the less robust methods defined in &xep0045;.</li>
</ul>
<p>Because it is anticipated that there will be significant co-existence between MUC and MIX, this specification is designed so that:</p>
<ul>
<li>XMPP clients can implement MUC and this specification in a way that provides a coherent user experience.</li>
<li>XMPP servers can implement this specification and also provide a MUC interface in order to support clients that only implement MUC.</li>
</ul>
<p>If a server wishes to expose both MUC and MIX representations of chatrooms, it is RECOMMENDED to do so by serving MUC and MIX on different domains, but a server MAY serve them on the same domain.</p>
</section1>
<section1 topic='Requirements' anchor='reqs'>
<p>The following requirements have been identified, which MIX aims to address.</p>
<ol>
<li>A user's participation in a channel persists and is not modified by the user's client going online and offline.</li>
<li>Multiple devices associated with the same account can share the same nick in the channel, with well-defined rules making each client individually addressable.</li>
<li>Channels are NOT REQUIRED to support or reflect presence for participants.</li>
<li>A reconnecting client can quickly resync with respect to messages and presence.</li>
<li>A user MAY (subject to configuration) receive messages from a channel as an invisible observer.</li>
<li>Configuration can be observed externally to the channel (e.g., list of participants, access control rights, etc.).</li>
<li>MIX services SHOULD provide mechanisms to prevent JIDs from being harvested.</li>
<li>MIX and Message Archive Management (MAM) MUST work well together.</li>
<li>A user can determine which channels they participate in.</li>
<li>Provide extensibility regarding data formats that can be sent within a channel (files, structured data, indications about media sources in multimedia conferences, etc.) as well as flexibility regarding which data formats a user wants to receive.</li>
<li>Enable federation of a channel across multiple servers, to provide a service equivalent to "federated MUC" &xep0289;.</li>
<li>Enable sharing of messages on a channel without requiring sharing of presence.</li>
<li>Enable sharing of presence without requiring message sending.</li>
<li>(Desirable) Make it easier to reduce duplicate traffic.</li>
</ol>
</section1>
<section1 topic='Concepts' anchor='concepts'>
<section2 topic="Specification Appproach" anchor="concepts-approach">
<p>
MIX will enable a wide range of auxiliary services. The goal of the MIX specification is to set out the core capabilities needed for MIX. It is anticipated that additional XEPs will be written to extend the core MIX, and the core MIX specification notes some areas where this may happen. This approach will avoid the core MIX specification becoming unduly large. Profiles referencing sets of related MIX XEPs may be developed in the future.
</p>
</section2>
<section2 topic="Core Concepts" anchor="concepts-core">
<p>The following concepts underlie the design of MIX.</p>
<ol>
<li>MIX channels (roughly equivalent to MUC rooms) are hosted on one or more MIX domains, (examples: 'mix.example.com'; 'conference.example.com'; 'talk.example.com'), which are discoverable through &xep0030;. Each channel on a MIX service can then be discovered and queried.</li>
<li> In MIX each channel (e.g., 'channel@mix.example.com') is a specialized pubsub service. This is based on the model from &xep0163; where every user JID (e.g., 'user@example.com') is its own pubsub service. </li>
<li>A channel's pubsub service contains a number of nodes for different event types or data formats. As described below, this document defines several standard nodes; however, future specifications or proprietary services can define their own nodes for extensibility.</li>
<li>Affiliations with the nodes are managed by the MIX service by channel level operations, so that the user does not have to separately manage affiliations with the individual PubSub nodes.
</li>
<li>&xep0313; (MAM) is used for all history access, with each node being individually addressable for MAM queries. This simplifies implementation compared to MUC (which had a specialized and rather limited history retrieval mechanism).</li>
<li>A client can achieve a 'quick resync' of a node by requesting just those changes it has not yet received, using standard MAM protocol. This solves the MUC issue of either receiving duplicate messages when rejoining a room or potentially missing messages.</li>
<li>Because MAM is used for history, only those nodes that have a 'current value' need to store any items in them &mdash; e.g., 'urn:xmpp:mix:nodes:presence' and 'urn:xmpp:mix:nodes:information' would store their current values (with older values being queryable through MAM), while 'urn:xmpp:mix:nodes:messages' would store no items.</li>
<li>A user's participation in a channel outlives their client sessions. A client which is offline will not share presence within the channel, but the associated user will still be listed as an participant. </li>
<li>Presence is sent to participants using bare JID, whether or not the user has an online client. </li>
<li>Online clients MAY register presence, which is then shared with participants who have subscribed to presence.</li>
<li>MIX decouples addressing of channel participants from their nicknames, so that nickname changes do not affect addressing.</li>
<li>Each participant is addressable by a single bare JID, which is a proxy JID (not the user's real JID) to make it straightforward to hide the user's real JID from other channel participants. Full JIDs comprised of this bare JID plus a resource (also anonymized) are then constructed, allowing visibility into the number of online resources participating in a channel.</li>
<li> Although some protocol is shared with MUC, MUC clients are not interoperable with a MIX service. This means that where a user chooses to use MIX, all of the users clients need to support MIX.</li>
<li>MIX requires the server to which the MIX client connects to provide functionality to support MIX. This functionality is defined in this specification and referenced as "MIX Participant's Server Behaviour".</li>
<li>MIX domains MUST NOT be used to host end user JIDs. </li>
</ol>
</section2>
<section2 topic="MIX and PubSub" anchor="concepts-pubsub">
<p>MIX is based upon domains providing a MIX service, such as 'mix.shakespeare.example'. Note that although PubSub communication is used, a domain used for MIX is a MIX domain and not a standard &xep0060; domain. Like MUC, there is no requirement on the naming of these domains; the label 'mix' used in examples in this specification and the fact that it is a subdomain of a 'shakespeare.example' service are purely for example.</p>
<p>Every MIX channel is an addressable PubSub service (with additional MIX semantics) that will be addressed using a bare JID by other XMPP entities, for example coven@mix.shakespeare.example. While &xep0060; is used as the basis for the MIX model, MIX uses standard presence and groupchat messages to provide an interface to the MIX service that does not expose PubSub protocol for many of the more common functions.
</p>
</section2>
<section2 topic="MIX and MAM" anchor="concepts-mam">
<p> Historical data (such as the messages sent to the channel) is stored in an archive supporting Message Archive Management (MAM) so that clients can subsequently access this data with MAM. Each node can be archived separately (e.g., the presence node or the configuration node). MIX messages are archived by both the MIX channel and the user's server, so that clients can generally use their local MAM archiver. MIX clients can retrieve archived information with MAM in order to quickly resync messages with regard to a channel, and can do so without providing presence information.</p>
</section2>
<section2 topic="Behaviour of MIX Participant's Server" anchor="concepts-mix-participant-server">
<p>
A MIX channel does not send messages and presence directly to the MIX client of a channel participant, but addresses them to the participant using the participant's bare JID. The participant's server MUST then handle these messages and pass them on to zero, one or multiple clients. To enable MIX to work, this behaviour is necessary and so the server of every MIX client MUST follow the rules set out in this specification.
This approach enables flexible support of multiple clients for a MIX channel participant.
The MIX model is that a user will join a channel over an extended period, and that the user (not a specific client used by the user) joins the channel. The primary subscription is with the client's bare JID.
There are a number of MIX requirements on behaviour of the MIX Participant's server, which are summarized here:
</p>
<ol>
<li>Messages from a MIX client to a MIX channel will go direct to the MIX service. They are relayed, but not modified, by the participant's server.</li>
<li>Messages from a MIX channel to a MIX client are always sent to the MIX participant's server (addressed by bare JID) and MUST be handled by the MIX participant's server.</li>
<li>All messages received by the MIX participant's server MUST be stored using MAM.</li>
<li>The MIX participant's server will only forward messages to online clients and will not forward messages if no clients are online.
This means that a MIX client needs to resynchronize with all MIX channels when it comes online. This message synchronization will happen between the MIX client and the MAM archive held on the MIX participant's server.</li>
<li>The MIX client will generally send management and other messages directly to the MIX channel and this MUST be done except where specifically noted. </li>
<li>The user's roster contains each MIX channel to which the user is subscribed. To achieve this the user's server needs to manage the roster on behalf of the user. For this reason, MIX join and leave commands MUST be sent by a client to the user's server. This enables the user's server to correctly manage the roster on behalf of the user.</li>
</ol>
<p>
Messages from a MIX channel to a MIX participant (which will be of type=groupchat) and presence information are sent to the participant's server using the participant's bare JID. This means that the MIX participant's server MUST implement a modification of the standard &rfc6121; message processing rules.
</p>
<p>
The core MIX specification sets out how the MIX channel interacts directly with XMPP clients and with the MIX participant's server. Behaviour of the MIX participant's server is also specified in this MIX specification.
</p>
</section2>
<section2 topic="User Presence in MIX" anchor="concepts-presence">
<p>
MIX channels store presence of each online client for a user that chooses to publish presence. Presence is stored in the presence node and is encoded using a full proxy JID. Where a user publishes presence for one or more clients, this information is available to all users subscribing to the channel presence.
</p>
<p>
Channel participants can send messages to clients publishing their presence by sending them to the full proxy JID published in the presence node. These stanzas MAY be routed to the client by the MIX channel. The choice to do this is dependent on MIX channel policy. For example, a disco request MAY be routed through the MIX channel to the client.
</p>
<p>
Presence updates are distributed by a channel to the bare JID of subscribers and then the subscriber's server will distribute to each of the subscriber's currently online clients.
</p>
</section2>
<section2 topic="Private Messages" anchor="concepts-pm">
<p>
Private messages MAY be sent to channel participants if allowed by channel policy. Private messages are
addressed to the user's bare proxy JID determined from the participants node, and routed by the MIX to the user's bare real JID, where standard distribution rules will apply.
</p>
</section2>
<section2 topic="Proxy JIDs and JID Visibility" anchor="proxy-jid">
<p>
MIX channels have three modes controlling JID visibility:
</p>
<table caption="JID Visibility Modes">
<tr><th>Mode</th><th>Description</th></tr>
<tr><td>'JID Visible'</td><td>In these channels all participant JIDs are visible to all channel participants.</td></tr>
<tr><td>'JID Maybe Visible'</td><td>In these channels, participant JIDs are visible to all channel participants when participant preference allows.</td></tr>
<tr><td>'JID&nbsp;Hidden'</td><td>In these channels, no participant JIDs are visible to channel participants, but they are visible to channel administrators.</td></tr>
</table>
<p>
A channel participant MAY specify a preference for JID visibility for the channel, with one of the following values:
</p>
<table caption="JID Visibility Preference Options">
<tr><th>Preference</th><th>Description</th></tr>
<tr><td>'No JID Visibility Preference'</td><td>The users JID will be visible if the channel is JID Visible or JID Maybe Visible channels and hidden if the channel is JID Hidden. </td></tr>
<tr><td>'Prefer Hidden'</td><td>The user's JID will be hidden if the channel is JID Maybe Visible and shown if the channel is JID Visible .</td></tr>
<tr><td>'Enforce Hidden'</td><td>The user's JID will never be shown and the user will be removed from channel if channel mode is changed to JID Visible.</td></tr>
<tr><td>'Enforce Visible'</td><td>The users JID will always be shown and the user will be removed from channel if mode is changed to 'JID Hidden'.</td></tr>
</table>
<p>
For JID Visible and JID Hidden channels the default user visibility preference is No JID Visibility Preference. For JID Maybe Visible channels, the default user visibility preference is Prefer Hidden, so that JIDs will only be visible when users explicitly permit this.
</p>
<p>
The primary representation of a participant in a MIX channel is a proxy JID, which is an anonymized JID using the same domain as the channel and with the name of the channel encoded, using the format "&lt;generated identifier&gt;#&lt;channel&gt;@&lt;mix domain&gt;". The generated identifier MUST NOT contain the '#', '/' or '@' characters. The Channel name MAY contain the '#' character. For example in the channel 'coven@mix.shakespeare.example', the user 'hag66@shakespeare.example' might have a proxy JID of '123456#coven@mix.shakespeare.example'. The reason for the proxy JID is to support JID Hidden channels. Proxy JIDs are also used in JID Visible channels, for consistency and to enable switching of JID visibility. The "urn:xmpp:mix:nodes:jidmap" node maps from proxy JID to real JID. Servers and clients MUST determine that a JID is a proxy JID from context and MUST NOT infer that a JID is a proxy JID because it contains the '#' character.
</p>
<p>
The mapping of real bare JID to proxy JID is defined when a participant joins a channel. While a user is a participant in a Channel, the mapping between real JID and proxy JID MUST NOT be changed. This mapping must be maintained after the user leaves the channel. Proxy JID values MUST NOT be re-used. If a JID that left a channel joins the channel again the same proxy JID MAY be used again or a different new proxy JID MAY be assigned.
</p>
<p>
The example real full JIDs in this specification are aligned the anticipated new format that splits the resource into two parts. The first part is UUID that is a stable and fixed value for the client and is anticipated to be a fixed format which may well be UUID 4. The second part is server assigned and will vary with each session. A realistic JID with resource is: 'hag66@shakespeare.example/d104f6a7-97e9-477f-8947-e4a37691d7ee/7533375f2cd'. This specification uses examples of the style: 'hag66@shakespeare.example/UUID-a1j/7533' which are aligned to real resources, but more compact. CITATION TO BE ADDED. If the final specification differs from this, the examples will be updated.
</p>
<p>
The full JIDs held in the presence nodes are anonymized using a similar mechanism. First the bare JID is mapped to a bare proxy JID, using the mapping held in the "urn:xmpp:mix:nodes:jidmap" node for the bare JID. Then the resource is replaced with a generated value. For example, 'hag66@shakespeare.example/UUID-a1j/7533' in the channel coven might have a proxy JID of '123456#coven@mix.shakespeare.example/789'. There is no client visible mapping of proxy full JIDs maintained as this is not needed. The MIX channel will need to maintain a mapping, to support directly addressing clients, such as for client to client disco#info queries. While an full proxy JID is held in the presence node, the mapping to real JID MUST NOT be changed. When adding a client to the presence node, the server MAY add the same anonymized JID as used before by that client, or it MAY create a different anonymized JID.
</p>
</section2>
<section2 topic="Standard Nodes" anchor="concepts-nodes">
<p>MIX defines a number standard nodes are as follows. Note that all nodes are OPTIONAL and that not every channel will necessarily use each node:</p>
<table caption="Standard MIX Nodes">
<tr><th>Name</th><th>Node</th><th>Description</th><th>Update</th><th>Distribution</th></tr>
<tr><td>Messages</td><td>'urn:xmpp:mix:nodes:messages'</td><td>For distributing messages to the channel. Each item of this node will contain a message sent to the channel.</td><td>Message</td><td>Message</td></tr>
<tr><td>Participants</td><td>'urn:xmpp:mix:nodes:participants'</td><td>For storing the list of participants and the associated nick. Channel participants are added when they join the channel and removed when they leave </td><td>Join/Leave/Set Nick</td><td>PubSub</td></tr>
<tr><td>JID Map</td><td>'urn:xmpp:mix:nodes:jidmap'</td><td>For storing a list of bare proxy JIDs from the participants node with a 1:1 mapping to the corresponding real JIDs.</td><td>Automatic</td><td>PubSub</td></tr>
<tr><td>JID Maybe Visible Map</td><td>'urn:xmpp:mix:nodes:jidmap2'</td><td>For storing a list of bare proxy JIDs from the participants node with a 1:1 mapping to the corresponding real JIDs for participants that choose to share real JIDs in a channel with JID Maybe Visible mode.</td><td>Automatic</td><td>PubSub</td></tr>
<tr><td>Presence</td><td>'urn:xmpp:mix:nodes:presence'</td><td>For storing information about the availability status of online participants, which MAY include multiple clients for a single participant.</td><td>Presence</td><td>Presence</td></tr>
<tr><td>Information</td><td>'urn:xmpp:mix:nodes:info'</td><td>For storing general channel information, such as description. </td><td>PubSub</td><td>PubSub</td></tr>
<tr><td>Allowed</td><td>'urn:xmpp:mix:nodes:allowed'</td><td>For storing JIDs that are allowed to be channel participants.</td><td>PubSub</td><td>PubSub</td></tr>
<tr><td>Banned</td><td>'urn:xmpp:mix:nodes:banned'</td><td>For storing JIDs that are not allowed to be channel participants. </td><td>PubSub</td><td>PubSub</td></tr>
<tr><td>Configuration</td><td>'urn:xmpp:mix:nodes:config'</td><td>For storing channel configuration. </td><td>PubSub</td><td>PubSub</td></tr>
</table>
<p>
All of the standard nodes are OPTIONAL. A channel providing a service similar to MUC will typically use all of the standard nodes, but other channels MAY use any combination of these nodes.
MIX provides mechanisms to allow users to conveniently subscribe to a chosen set of nodes and to unsubscribe to all nodes with a single operation. Some nodes are accessed and managed with PubSub, whereas other nodes define MIX specific mechanisms for their use, as shown in the last two columns of the table.
</p>
<p>
MIX also makes use of two nodes for support of Avatars. These nodes and their use is defined in &xep0084;. These nodes MAY be created as part of a MIX channel, where it is desired to publish an avatar associated with the channel.
</p>
<table caption="MIX Nodes for Avatar Support">
<tr><th>Name</th><th>Node</th><th>Description</th></tr>
<tr><td>Avatar Data</td><td>'urn:xmpp:avatar:data'</td><td>For publishing an Avatar</td></tr>
<tr><td>Avatar Metadata</td><td>'urn:xmpp:avatar:metadata'</td><td>For publishing Avatar metadata</td></tr>
</table>
<p>
The structure of each of the standard nodes defined by MIX is now considered in more detail in the rest of this section, after explaining roles.
</p>
<section3 topic="Roles" anchor="roles">
<p>
There are a number of MIX roles for each channel, listed in the following table. Rights will be assigned to the various roles in the channel configuration node.
</p>
<table caption="Channel Roles">
<tr><th>Role</th><th>Membership and Rights</th></tr>
<tr><td>Owners</td><td>These are owners of the channel, as specified in the channel configuration node. Only owners are allowed to modify the channel configuration node.</td></tr>
<tr><td>Administrators</td><td>Administrators are defined in the channel configuration node. Administrators have update rights to the Allowed Node and Banned Node, so they can control which users are allowed to participate in a channel. </td></tr>
<tr><td>Participants</td><td>Participants are users listed by JID in the participants node.</td></tr>
<tr><td>Allowed</td><td>Allowed is the set of JIDs that are participants or are allowed to become participants. A JID is allowed if it does not match an entry in the banned node and either it matches an entry in the allowed node or the allowed node is not present. </td></tr>
<tr><td>Anyone</td><td>Any user, including users in the banned node.</td></tr>
</table>
<p>
There MUST always be at least one Owner. Administrators, Participants, and Allowed MAY NOT have any members. Rights are defined in a strictly hierarchical manner following the order of this table, so that for example Owners will always have rights that Administrators have.
</p>
</section3>
<section3 topic="Node Archiving" anchor="node-archiving">
<p>
Nodes MAY be archived and where this is done MAM MUST be used. Archiving of the Messages node MUST be done as part of the MIX specification. Archiving of other nodes is OPTIONAL.
</p>
</section3>
<section3 topic="Messages Node" anchor="messages-node">
<p>
The Messages node is used to distribute messages. The Messages node is a transient node and so no PubSub items are held. Messages MUST go to the associated MAM archive and history is retrieved by use of MAM. Users subscribe to this node to indicate that messages from the channel are to be sent to them. Private Messages are not distributed by the Messages node.
</p>
</section3>
<section3 topic="Participants Node" anchor="participants-node">
<p>Each channel participant is represented as an item of the 'urn:xmpp:mix:nodes:participants' channel node. Each item is named by the bare proxy JID of the participant. For example '123456#coven@mix.shakespeare.example' might name the node item associated with participant 'hag66@shakespeare.example'. The nick associated with the user is mandatory and is stored in the item. The nick for each channel participant MUST be different to the nick of other participants.
</p>
<p>
When a user joins a channel, the user's bare JID is added to the participants node by the MIX service. When a user leaves a channel, they are removed from the participants node. The participants node MUST NOT be directly modified using pubsub.
This node MAY be subscribed to for jid-visible channels that permit subscription to this node - this will allow users to see changes to the channel participants.
</p>
<p>The participants node is OPTIONAL. If the Participants Node is not used, information on channel participants is not shared. If there is no participants node, the access control value 'participants' MUST NOT be used. The Participants node is a permanent node with one item per participant.</p>
<example caption="Value of Participants Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:participants'>
<item id='123456#coven@mix.shakespeare.example'>
<participant xmlns='urn:xmpp:mix:0'
nick='thirdwitch'/>
</item>
</items>
]]></example>
</section3>
<section3 topic="JID Map Node" anchor="jid-map-node">
<p>The JID Map node is used to associate a proxy bare JID to its corresponding real bare JID. The JID Map node MUST have one entry for each entry in the Participants node. This value is added when a user joins the channel and is removed when the user leaves the channel.
Each item is identified by proxy bare JID, mapping to the real bare JID. This node is used to give administrator access to real JIDs and participant access to real JIDs in jid-visible channels. This node MUST NOT be modified directly using pubsub.
In JID Visible channels, all participants MAY subscribe to this node. In JID Hidden and JID Maybe Visible channels, only administrators can subscribe. The JID Map node is a permanent node with one item per participant.</p>
<example caption="Value of JID Map Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:jidmap'>
<item id='123456#coven@mix.shakespeare.example'>
<participant xmlns='urn:xmpp:mix:0'
jid='hecate@mix.shakespeare.example'/>
</item>
</items>
]]></example>
</section3>
<section3 topic="JID Maybe Visible Map Node" anchor="jid-map2-node">
<p>The JID Maybe Visible Map node is a similar node to the JID Map node that is used in addition to the JID Map Node in JID Maybe Visible channels. All participants may subscribe to and access this node. It uses the same encoding as JID Map node and all participant JIDs MUST be included. Where a participant's preference is to not share the JID, the encoded participant value is the proxy JID. This will enable a user looking up a JID to clearly determine that the user preference is to not share the JID and to clearly distinguish this case from an erroneous proxy JID.
</p>
</section3>
<section3 topic="Presence Node" anchor="presence-node">
<p>
The presence node contains the presence value for clients belonging to participants that choose to publish presence to the channel. A MIX channel MAY require that all participants publish presence. Each item in the presence node is identified by the full proxy JID, and contains the current presence value for that JID. The presence is encoded in the same way as data that would be sent in a presence stanza. The full proxy JID is always used in this node. In MIX it is possible to have a 'presence-less channel' by not using this node. Access Control MAY be set to enforce that for each of the full JIDs in this list, the bare JID MUST be in the participants list.
</p>
<p>
This node MAY be subscribed to by users and this subscription MUST use the user's bare JID. So presence of online clients is sent to the user's server for each user subscribed to this node. Presence is always sent using standard presence protocol and NOT using pubsub protocol. Clients MUST NOT directly access the presence node using pubsub. The Presence node is a permanent PubSub node.
</p>
<example caption="Value of Presence Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:presence'>
<item id='123456#coven@mix.shakespeare.example/8765'>
<presence xmlns='jabber:client'>
<show>dnd</show>
<status>Making a Brew</status>
</presence>
</item>
</items>
]]></example>
</section3>
<section3 topic="Information Node" anchor="info-node">
<p>The Information node holds information about the channel. The information node contains a single item with the current information.
The information node is named by the date/time at which the item was created. The information node is accessed and managed using standard pubsub. The Information node is a permanent node with a maximum of one item. Users MAY subscribe to this node to receive information updates. The Information node item MAY contain the following attributes, each of which is OPTIONAL:
</p>
<table caption="Information Node Attributes">
<tr><th>Name</th><th>Description</th><th>Field Type</th><th>Values</th><th>Default</th></tr>
<tr><td>'Name'</td><td>A short string providing a name for the channel. For example "The Coven". Typical uses of this value will be to present a user with the name of this channel in a list of channels to select from or as the header of UI display of the channel. It is intended for use where a short string is needed to represent the channel.</td><td>text-single</td><td>-</td><td>-</td></tr>
<tr><td>'Description'</td><td>A longer description of the channel. For example "The Place where the Macbeth Witches Meet up". A typical use would be to provide a user with more information about the channel, for example in a tool tip.</td><td>text-single</td><td>-</td><td>-</td></tr>
<tr><td>'Contact'</td><td>The JID or JIDs of the person or role responsible for the channel.</td><td>jid-multi</td><td>-</td><td>-</td></tr>
<tr><td>'JID Visibility'</td><td>Specified JID visibility of the channel.</td><td>list-single</td><td>'jid-hidden'; 'jid-maybe-visible'; 'jid-visible'</td><td>'jid-hidden'</td></tr>
</table>
<p>
Name and Description of the channel apply to the whole channel and will usually be changed infrequently.
</p>
<p>
JID visibility is included in the Information Node as this is information that will be useful for participant clients and may also be important when choosing to join a channel.
</p>
<p>The name and description values MUST contain a "text" element and MAY contain additional text elements. Where multiple text elements are provided, each MUST posses an xml:lang attribute that describes the natural language of the element. The format of the Information node follows &xep0004;. This allows configuration to be updated by MIX defined commands and that the results of update commands are the same as the PubSub node.
The following example shows the format of a item in the information node for the example coven@mix.shakespeare.example channel.
</p>
<example caption="Information Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:info'>
<item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:0'>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0</value>
</field>
<field var='Name'>
<value>Witches Coven</value>
</field>
<field var='Description'>
<value>A location not far from the blasted heath where
the three witches meet</value>
</field>
<field var='Contact'>
<value>greymalkin@shakespeare.lit</value>
</field>
<field var='JID Visibility'>
<value>jid-visible</value>
</field>
</x>
</item>
</items>
]]></example>
</section3>
<section3 topic="Allowed" anchor="allowed-node">
<p>
This node represents a list of JIDs that are allowed to become participants. If the Allowed node is not present, all JIDs are allowed. This node is accessed and managed using standard pubsub. The Allowed list is always considered in conjunction with the banned list, stored in the banned node. Only Administrators and Owners have write permission to the Allowed node and are also the only roles that are allowed to subscribe to this node. The Allowed node is a permanent node. Each item contains a real bare JID. The following example shows how the Allowed list can specify single JIDs and domains.
</p>
<example caption="Allowed Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:allowed'>
<item id='shakespeare.lit'/>
<item id='alice@wonderland.lit'/>
</items>
]]></example>
</section3>
<section3 topic="Banned" anchor="banned-node">
<p>
This node represents a list of JIDs that are explicitly not allowed to become participants. The values in this list take priority over values in the Allowed node. This node is accessed and managed using standard pubsub Only Administrators and Owners have write permission to the Banned node and are also the only roles that are allowed to subscribe to this node. Each item contains a real bare JID. The Banned node can contain bare JIDs and/or domains. The Banned node is a permanent node.
</p>
<example caption="Banned Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:banned'>
<item id='lear@shakespeare.lit'/>
<item id='macbeth@shakespeare.lit'/>
</items>
]]></example>
</section3>
<section3 topic="Configuration Node" anchor="config-node">
<p>
The Configuration node holds the configuration of the channel as a single item, named by the date-time of the last update to the configuration. The Configuration node is a permanent node with a maximum of one item. Previous configuration history MAY be accessed by MAM. Users with read access to the configuration node MAY subscribe to the configuration node to get notification of configuration change. This node is accessed and managed using standard pubsub. The configuration node is OPTIONAL for a MIX channel. For example, configuration choices could be fixed and not exposed. A subset of the defined configuration options MAY be used and additional non-standard configuration options MAY be added. JIDs in the configuration MUST be real bare JIDs and not proxy JIDs. If configuration options to control functionality of the nature described here are provided, the options defined in this standard MUST be used. The following configuration attributes are defined:
</p>
<table caption="Configuration Node Attributes">
<tr><th>Name</th><th>Description</th><th>Field Type</th><th>Values</th><th>Default</th></tr>
<tr><td>'Last Change Made By'</td><td>Bare JID of the user making the last change.</td><td>jid-single</td><td>-</td><td>-</td></tr>
<tr><td>'Owner'</td><td>Bare JIDs with Owner rights as defined in ACL node. When a channel is created, the JID creating the channel is configured as an owner, unless this attribute is explicitly configured to another value.</td><td>jid-multi</td><td>-</td><td>-</td></tr>
<tr><td>'Administrator'</td><td>Bare JIDs with Administrator rights.</td><td>jid-multi</td><td>-</td><td>-</td></tr>
<tr><td>'End of Life'</td><td>The date and time at which the channel will be automatically removed by the server. If this is not set, the channel is permanent.</td><td>text-single</td><td>-</td><td>-</td></tr>
<tr><td>'Nodes Present'</td><td>Specifies which nodes are present. Presence of config nodes is implicit. Jidmap node MUST be present if participants node is present. 'avatar' means that both Avatar Data and Avatar Metadata nodes are present.</td><td>list-multi</td><td>'participants'; 'presence'; 'information'; 'allowed'; 'banned'; 'jidmap2'; 'avatar'</td><td>-</td></tr>
<tr><td>'Messages Node Subscription'</td><td>Controls who can subscribe to messages node.</td><td>list-single</td><td>'participants'; 'allowed'; 'anyone'</td><td>'participants'</td></tr>
<tr><td>'Presence Node Subscription'</td><td>Controls who can subscribe to presence node.</td><td>list-single</td><td>'participants'; 'allowed'; 'anyone'</td><td>'participants'</td></tr>
<tr><td>'Participants Node Subscription'</td><td>Controls who can subscribe to participants node.</td><td>list-single</td><td>'participants'; 'allowed'; 'anyone'; 'nobody'; 'admins'; 'owners'</td><td>'participants'</td></tr>
<tr><td>'Information Node Subscription'</td><td>Controls who can subscribe to the information node.</td><td>list-single</td><td>'participants'; 'allowed'; 'anyone'</td><td>'participants'</td></tr>
<tr><td>'Allowed Node Subscription'</td><td>Controls who can subscribe to allowed node.</td><td>list-single</td><td>'participants'; 'allowed'; 'nobody'; 'admins'; 'owners' </td><td>'admins'</td></tr>
<tr><td>'Banned Node Subscription'</td><td>Controls who can subscribe to banned node.</td><td>list-single</td><td>'participants'; 'allowed'; 'nobody'; 'admins'; 'owners' </td><td>'admins'</td></tr>
<tr><td>'Configuration Node Access'</td><td>Controls who can subscribe to configuration node and who has read access to it.</td><td>list-single</td><td>'participants'; 'allowed'; 'nobody'; 'admins'; 'owners' </td><td>'owners'</td></tr>
<tr><td>'Information Node Update Rights'</td><td>Controls who can make changes to the information node</td><td>list-single</td><td>'participants'; 'admins'; 'owners' </td><td>'admins'</td></tr>
<tr><td>'Avatar Nodes Update Rights'</td><td>Controls who can make changes to the avatar data and metadata nodes</td><td>list-single</td><td>'participants'; 'admins'; 'owners' </td><td>'admins'</td></tr>
<tr><td>'Open Presence'</td><td>If selected, any client MAY register presence. If not selected, only clients with bare JID in the participants list are allowed to register presence.</td><td>boolean</td><td>-</td><td>false</td></tr>
<tr><td>'Participants Must Provide Presence'</td><td>If selected, all channel participants are REQUIRED to share presence information with the channel.</td><td>boolean</td><td>-</td><td>false</td></tr>
<tr><td>'User Message Retraction'</td><td>If this option is selected users will be able to retract messages that they have sent to the MIX channel.</td><td>boolean</td><td>-</td><td>false</td></tr>
<tr><td>'Administrator Message Retraction Rights'</td><td>This controls which group is able to retract any message sent to the MIX channel.</td><td>list-single</td><td>'nobody'; 'admins'; 'owners'</td><td>'owners'</td></tr>
<tr><td>'Participation Addition by Invitation from Participant'</td><td>This option extends a channel so that a channel participant has rights to invite and enable other users as participants.</td><td>boolean</td><td>-</td><td>false</td></tr>
<tr><td>'Private Messages'</td><td>If this option is selected, private messages MAY be used with the channel.</td><td>boolean</td><td>-</td><td>true</td></tr>
</table>
<p>
The configuration node is in &xep0004; format and includes all of the options used by the channel, including values for options using default values. This means that the value in the form can be directly mapped with the form returned by configuration administration commands. Configuration nodes will typically have a large number of elements. The following short example is provided to illustrate the syntax of the configuration node.
</p>
<example caption="Configuration Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:config'>
<item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:0'>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0</value>
</field>
<field var='Owner'>
<value>hecate@shakespeare.lit</value>
</field>
<field var='Owner'>
<value>greymalkin@shakespeare.lit</value>
</field>
<field var='Messages Node Subscription'>
<value>allowed</value>
</field>
<field var='No Private Messages'>
<value>true</value>
</field>
</x>
</item>
</items>
]]></example>
</section3>
</section2>
<section2 topic="Non-Standard Nodes" anchor="non-standard-nodes">
<p>
The MIX standard allows channels to use non-standard nodes, using names that do no conflict with the standard nodes. Non-Standard nodes MUST NOT duplicate or otherwise provide capability that can be provided by standard nodes.
</p>
</section2>
</section1>
<section1 topic="Error Handling" anchor="error-handling">
<p>
The MIX specification is built on layered services that have defined errors. This enables the core MIX specification to reflect primarily the successful use case, as in almost all cases the error reporting of the layer service provides what is needed. A message sender MUST be prepared to handle any valid error from the layer services. When a message receiver encounters an error situation, it MUST use the most appropriate layer server error to report this issue back to the sender. For example a message receiver might use the "not authorized" IQ error in response to a MIX disco that is not authorized. Errors for the following layer services need to be handled for MIX:
</p>
<ol>
<li>IQ. All of the IQ errors of &rfc6120; MUST be supported.</li>
<li>Messages. If a message is received and an error situation is encountered, a message of type error MUST be sent back to the message sender. This message format is specified in &rfc6121; containing an error defined in &rfc6120;, which is the same error set as for IQs.</li>
<li>Presence. Any responses to presence messages MUST follow the rules of &rfc6121;.</li>
<li>PubSub. Where MIX protocol messages use PubSub protocol, the errors defined in &xep0060; MUST be used and supported.</li>
</ol>
</section1>
<section1 topic='Discovery' anchor='discovery'>
<section2 topic='Discovering a MIX service' anchor='disco-service'>
<p>
An entity MAY discover a MIX service or MIX services by sending a Service Discovery items ("disco#items") request to its own server.
</p>
<example caption="Entity queries Server for associated services" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-c8y/1573'
id='lx09df27'
to='shakespeare.example'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
<iq from='shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#items'>
<item jid='mix.shakespeare.example'
name='Shakespearean Chat Service'/>
<item jid='mix2.shakespeare.example'
name='Another Shakespearean Chat Service'/>
</query>
</iq>
]]></example>
<p>To determine if a domain hosts a MIX service, a &xep0030; info query is sent in the usual manner to determine capabilities.</p>
<example caption="Entity queries a service" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-c8y/1573'
id='lx09df27'
to='mix.shakespeare.example'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
]]></example>
<p>The MIX service then MUST return its identity and the features it supports, which MUST include the 'urn:xmpp:mix:0' feature, and the identity MUST have a category of 'conference' and a type of 'text', as shown in the following example: </p>
<example caption="Service responds with Disco Info result" ><![CDATA[
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity
category='conference'
name='Shakespearean Chat Service'
type='text'/>
<feature var='urn:xmpp:mix:0'/>
<feature var='urn:xmpp:mix:0#searchable'>
</query>
</iq>
]]></example>
<p>
A MIX service MUST return the 'urn:xmpp:mix:0' feature and MAY return the other features listed here:
</p>
<ul>
<li>'urn:xmpp:mix:0': This indicates support of MIX, and is returned by all MIX services.</li>
<li>'urn:xmpp:mix:0#searchable': This is shown in the above example and indicates that a the MIX Service MAY be searched for channels. This presence of this feature can be used by a client to guide the user to search for channels in a MIX service.</li>
<li>'urn:xmpp:mix:0#create-channel': This is described in <link url='#usecase-admin-check-create'> Checking for Permission to Create a Channel</link> in support of channel administration. When an end user client needs to create channels, perhaps for short term usage, this feature helps the client to identify an MIX service to use. It enables a configuration where permanent (searchable) channels are placed in one MIX service and clients will be able to create channels in another MIX service which is not searchable.</li>
</ul>
<p>A MIX service MUST NOT advertise support for &xep0313;, as MAM is supported by the channels and not by the service. A MIX service MUST NOT advertise support for generic &xep0060;, as although MIX makes use of PubSub it is not a generic PubSub service.</p>
</section2>
<section2 topic='Discovering the Channels on a Service' anchor='disco-channel-list'>
<p>The list of channels supported by a MIX service is obtained by a disco#items command. The MIX service MUST only return channels that exist and that the user making the query has rights to subscribe to. </p>
<example caption='Client Queries for Channels on MIX Service'><![CDATA[
<iq from='hag66@shakespeare.example/UUID-c8y/1573'
id='kl2fax27'
to='mix.shakespeare.lit'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#items'/>
</iq>
]]></example>
<example caption='MIX Service Returns Disco Items Result'><![CDATA[
<iq from='mix.shakespeare.lit'
id='kl2fax27'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#items'>
<item jid='coven@mix.shakespeare.example' />
<item jid='spells@mix.shakespeare.example' />
<item jid='wizards@mix.shakespeare.example' />
</query>
</iq>
]]></example>
</section2>
<section2 topic='Discovering Channel Information' anchor='disco-channel-info'>
<p>In order to find out more information about a given channel, a user can send a disco#info query to the channel. </p>
<example caption='Entity Queries for Information about a Specific Channel'><![CDATA[
<iq from='hag66@shakespeare.example/UUID-c8y/1573'
id='ik3vs715'
to='coven@mix.shakespeare.lit'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info' node='mix'/>
</iq>
]]></example>
<p>If the querying user is allowed to subscribe, the channel MUST return its identity and the features it supports. Note that a MIX channel MUST support MAM and so the response will always include both MIX and MAM support. All disco queries on a MIX channel and results returned MUST include the attribute node='mix'. The reason for this is to facilitate MIX channels and &xep0045; MUC rooms sharing the same JID. This extra parameter will enable a server to return appropriate information.</p>
<example caption='Channel Returns Disco Info Result'><![CDATA[
<iq from='coven@mix.shakespeare.lit'
id='ik3vs715'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info' node='mix'>
<identity
category='conference'
name='A Dark Cave'
type='mix'/>
<feature var='urn:xmpp:mix:0'/>
<feature var='urn:xmpp:mam:1'/>
</query>
</iq>
]]></example>
</section2>
<section2 topic='Discovering Nodes at a Channel' anchor='disco-channel-nodes'>
<p>Use disco#items to find the nodes associated with a channel. Discovering nodes in MIX MUST use the node='mix' attribute. The MIX service MUST only return nodes that exist and that the user making the query has rights to subscribe to. </p>
<example caption='Entity Queries for Nodes at a Channel'><![CDATA[
<iq from='hag66@shakespeare.example/UUID-c8y/1573'
id='kl2fax27'
to='coven@mix.shakespeare.lit'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#items'/ node='mix'>
</iq>
]]></example>
<example caption='Channel Returns Disco Items Result'><![CDATA[
<iq from='coven@mix.shakespeare.lit'
id='kl2fax27'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#items' node='mix'>
<item jid='coven@mix.shakespeare.example'
node='urn:xmpp:mix:nodes:presence'/>
<item jid='coven@mix.shakespeare.example'
node='urn:xmpp:mix:nodes:participants'/>
<item jid='coven@mix.shakespeare.example'
node='urn:xmpp:mix:nodes:messages'/>
<item jid='coven@mix.shakespeare.example'
node='urn:xmpp:mix:nodes:config'/>
</query>
</iq>
]]></example>
</section2>
<section2 topic="Determining Information about a Channel" anchor="find-channel-info">
<p>The Information Node contains various information about the channel that can be useful to the user, that the client can access using PubSub, as shown below.</p>
<example caption='Client Requests Channel Information'><![CDATA[
<iq from='hag66@shakespeare.example/UUID-c8y/1573'
id='kl2fax27'
to='coven@mix.shakespeare.lit'
type='get'>
<pubsub xlns='http://jabber.org.protocol.pubsub'>
<items node='urn:xmpp:nodes:info'/>
</pubsub>
</iq>
]]></example>
<example caption='MIX Service Returns Channel Information'><![CDATA[
<iq from='coven@mix.shakespeare.lit'
id='kl2fax27'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<pubsub xlns='http://jabber.org.protocol.pubsub'>
<items node='urn:xmpp:nodes:info>>
<item>
<item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:0'>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0</value>
</field>
<field var='Name'>
<value>Witches Coven</value>
</field>
<field var='Description'>
<value>A location not far from the blasted heath where
the three witches meet</value>
</field>
<field var='Contact'>
<value>greymalkin@shakespeare.lit</value>
</field>
</x>
</item>
</items>
</pubsub>
</iq>
]]></example>
</section2>
<section2 topic='Determining the Participants in a Channel' anchor='find-channel-participants'>
<p>
Participants in the channel are determined using PubSub retrieval of the Participants Node which will give proxy JID and nick. </p>
<example caption='User&apos;s Client Requests Participant List'><![CDATA[
<iq from='hag66@shakespeare.example/UUID-c8y/1573'
id='kl2fax27'
to='coven@mix.shakespeare.lit'
type='get'>
<pubsub xlns='http://jabber.org.protocol.pubsub'>
<items node='urn:xmpp:nodes:participants'/>
</pubsub>
</iq>
]]></example>
<example caption='MIX Service Returns Participant List'><![CDATA[
<iq from='coven@mix.shakespeare.lit'
id='kl2fax27'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<pubsub xlns='http://jabber.org.protocol.pubsub'>
<items node='urn:xmpp:nodes:participants'>
<item jid='123456#coven@mix.shakespeare.example' nick='thirdwitch'>
<item jid='87123#coven@mix.shakespeare.example' nick='top witch'>
</items>
</pubsub>
<items>
</iq>
]]></example>
<p>
Online clients in the channel can be looked up in a similar manner by PubSub query of the Presence node.
</p>
</section2>
<section2 topic="Discovering Client MIX Capability" anchor="mix-client-discovery">
<p>
Where a client supports MIX, it MUST advertise this capability in response to a Disco request. This will enable other entities to determine if a client supports MIX, and in particular it facilitates the client's server to determine client support. This can be optimized by use of CAPS. The following example shows a Disco request to and response from a client that supports both MIX and MUC.
</p>
<example caption='Disco Query for MIX support'><![CDATA[
<iq from='juliet@capulet.lit/UUID-e3r/9264'
id='d1rt87mr4w'
to='romeo@montague.lit/UUID-m2t/3945'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
<iq from='romeo@montague.lit/UUID-m2t/3945'
id='d1rt87mr4w'
to='juliet@capulet.lit/UUID-e3r/9264'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<feature var='http://jabber.org/protocol/caps'/>
<feature var='http://jabber.org/protocol/disco#info'/>
<feature var='http://jabber.org/protocol/disco#items'/>
<feature var='http://jabber.org/protocol/muc'/>
<feature var='http://jabber.org/protocol/mix'/>
</query>
</iq>
]]></example>
</section2>
</section1>
<section1 topic='Use Cases' anchor='usecases'>
<section2 topic='Common User Use Cases' anchor='usecases-user'>
<section3 topic='Joining a Channel' anchor='usecase-user-join'>
<p>A user joins a channel by sending a MIX "join" command. There is no default set of nodes, so the user MUST specify the set of nodes to be subscribed to. To achieve the equivalent service to MUC, a user would subscribe to messages, and presence.
This will lead to the server subscribing the user to each of the requested nodes associated with the channel. The MIX service will also add the user to the participant list by injecting a new item into the "urn:xmpp:mix:nodes:participants" node automatically.
</p>
<p>The default MIX model is that only channel participants are allowed to subscribe to nodes. A MIX channel MAY allow non-participant subscription. This will be handled by clients directly subscribing to the desired PubSub nodes.</p>
<p>
The user's server needs to make roster changes as part of the join functionality. Because of this, the join and leave operations need to operate indirectly.
For this reason the initial join request is sent to the local server with the MIX channel specified as an attribute to the join.
</p>
<example caption="Client sends request to Local Server to Join a Channel"><![CDATA[
<iq type='set'
from='hag66@shakespeare.example/UUID-a1j/7533'
to='hag66@shakespeare.example'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<join xmlns='urn:xmpp:mix:0'
channel='coven@mix.shakespeare.example'>
<subscribe node='urn:xmpp:mix:nodes:messages'/>
<subscribe node='urn:xmpp:mix:nodes:presence'/>
<subscribe node='urn:xmpp:mix:nodes:participants'/>
<subscribe node='urn:xmpp:mix:nodes:config'/>
</join>
</iq>
]]></example>
<p>
The user’s server will then pass the request to the MIX channel, with the request coming from the user's bare JID.
</p>
<example caption="User's Server sends Join request to MIX Channel"><![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'/>
<subscribe node='urn:xmpp:mix:nodes:participants'/>
<subscribe node='urn:xmpp:mix:nodes:config'/>
</join>
</iq>
]]></example>
<p>The channel responds to the user's sever with an IQ-result addressed to the user's bare JID. This stanza includes the nodes to which the user has been successfully subscribed, as well as the bare JID that will be used for the user in this channel and added to the participant list. The JID returned in the join is the user's bare proxy JID. The following example shows the result of the above request when the request is completed in full. </p>
<example caption="Channel responds to User's Server"><![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='123456#coven@mix.shakespeare.example'>
<subscribe node='urn:xmpp:mix:nodes:messages'/>
<subscribe node='urn:xmpp:mix:nodes:presence'/>
<subscribe node='urn:xmpp:mix:nodes:participants'/>
<subscribe node='urn:xmpp:mix:nodes:config'/>
</join>
</iq>
]]></example>
<p>
The user's server will then send the join response back to the client that made the join request. The only change is that the incoming message is addressed to bare JID and the outgoing message is addressed to client's full JID. Prior to sending this response, the user's server will make roster modifications as set out in the next section.
</p>
<example caption="User's Server sends response to Client"><![CDATA[
<iq type='result'
from='coven@mix.shakespeare.example'
to='hag66@shakespeare.example/UUID-a1j/7533'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<join xmlns='urn:xmpp:mix:0' jid='123456#coven@mix.shakespeare.example'>
<subscribe node='urn:xmpp:mix:nodes:messages'/>
<subscribe node='urn:xmpp:mix:nodes:presence'/>
<subscribe node='urn:xmpp:mix:nodes:participants'/>
<subscribe node='urn:xmpp:mix:nodes:config'/>
</join>
</iq>
]]></example>
<p>
If a user cannot be subscribed to one or more of the requested nodes (e.g., because the node does not exist), but can be subscribed to some the response simply lists the nodes successfully subscribed. If none of the nodes requested are successfully subscribed to, an error response is sent indicating the reason that the first node requested was not subscribed to. This error response will also include other nodes requested where subscription failed for the same reason. </p>
<p>
The following response example shows a successful response to the initial request example where
the participant is not subscribed to all nodes associated with the channel (in this case only messages, participants, and information). This example shows the message from the MIX channel to the user's server, which will be modified and sent to the client.
</p>
<example caption="Channel Processes Join With Some Nodes Not Subscribed To"><![CDATA[
<iq type='result'
from='hag66@shakespeare.example'
to='coven@mix.shakespeare.example'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<join xmlns='urn:xmpp:mix:0' jid='123456#coven@mix.shakespeare.example'>
<subscribe node='urn:xmpp:mix:nodes:messages'/>
<subscribe node='urn:xmpp:mix:nodes:participants'/>
<subscribe node='urn:xmpp:mix:nodes:info'/>
</join>
</iq>
]]></example>
<p>The channel also adds the user to the participants node and sends a notification to subscribers of the participants node. The following example shows such a notification.</p>
<example caption="Channel Adds User to Participants Node"><![CDATA[
<message from='coven@mix.shakespeare.example'
to='hecate@shakespeare.example'
id='5A9C7398-DB13-4BFA-A091-2D466C710AAF'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='urn:xmpp:mix:nodes:participants'>
<item id='123456#coven@mix.shakespeare.example'>
<participant xmlns='urn:xmpp:mix:0'/>
</item>
</items>
</event>
</message>
]]></example>
<p>The user that has been added to the channel is identified by the item id of the item added to the Participants node, which is the proxy JID of the new channel participant. Note that the &lt;participant&gt; element MUST NOT include a nick of the user being added. The nick MAY be set after the join.</p>
<p>
At the same time the participant MUST be added to the JID Map node, to map from proxy JID to real JID. For a JID Maybe Visible channel, the participant MUST be added to the JID Maybe Visible Map node. The value in this node MUST reflect the user's visibility preference for the channel and MUST be updated to reflect any changes to this preference.
</p>
<p>
A user MAY subsequently modify subscription to nodes in a channel by sending a subscription modification request, as shown in the following example. This modification goes directly from client to MIX channel, as this change does not impact the roster and so does not need any local action.
</p>
<example caption="User Modifies Subscription Request"><![CDATA[
<iq type='set'
from='hag66@shakespeare.example/UUID-a1j/7533'
to='coven@mix.shakespeare.example'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<update-subscription xmlns='urn:xmpp:mix:0'>
<subscribe node='urn:xmpp:mix:nodes:messages'/>
</update-subscription>
</iq>
<iq type='result'
from='coven@mix.shakespeare.example'
to='hag66@shakespeare.example/UUID-a1j/7533'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<update-subscription xmlns='urn:xmpp:mix:0' jid='hag66@shakespeare.example'>
<subscribe node='urn:xmpp:mix:nodes:messages'/>
</update-subscription>
</iq>
]]></example>
</section3>
<section3 topic="Roster Management" anchor="usecase-roster-management">
<p>
As part of the channel joining process, the user's server MUST add the MIX channel to the user's roster. This is done to share the user's presence status with the channel and channel participants subscribing to presence, when the user wishes this presence to be shared. These roster entries also enables the user's client to quickly determine which channels the user has joined.
This roster entry will lead to the user's server correctly sending user's presence from all the user's MIX clients to the MIX channel. Where the user wishes to share presence, the roster subscription is configured with one way presence, as presence is sent to the MIX channel but no presence information is sent about the MIX channel to the user.
</p>
<p>
If the user does not wish to publish presence information to the channel, the user's server will add the roster entry with mode subscription=none. The roster entry will be present to record that the user has joined the channel, but it will not send presence information to the channel. The user's server MUST do this when the user has chosen Presence preference of 'Not Share' as described below. If the user changes the value of the preference, the server MUST modify subscription mode to reflect this.
</p>
<p>
The user's server MUST remove this roster entry when the user leaves the channel.
</p>
<p>
A channel MAY publish an Avatar following &xep0084;. A client MAY make use of this information to associate an Avatar with the roster entry for a channel.
</p>
</section3>
<section3 topic="User Preferences and Additional Information" anchor="usecase-visibilty-pref">
<p>A channel MAY store user preferences and parameters with each user. A user JID visibility preference has the following values:
</p>
<ol>
<li>'Default'. In this setting, the channel default value will be used. This value is used if another value is not explicitly set. This means JID is visible for a JID Visible channel and JID is hidden for JID Hidden and JID Maybe Visible channels.</li>
<li>'Never'. If this is set, JID will never be shared and user will be removed from the channel if its mode changes to JID Visible.</li>
<li>'Always'. If this is set, JID will always be shared and users will be removed from the channel if its mode changes to JID Hidden.</li>
<li>'Prefer Not'. If this is set, JID will only be shared if mode is JID Visible.</li>
</ol>
<p>
The user MAY specify that no Private Messages are to be sent from the channel, and allow vCard retrieval.
</p>
<p>
The user MAY specify that presence is not to be shared, which will prevent the MIX Channel from sending a presence probe for the user on channel start-up. The user will also choose to not include the MIX channel in the user's roster, so that presence will not be updated. Where the channel configuration sets 'Participants Must Provide Presence', this variable MUST be set to 'Share'.
</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>'Default', 'Never', 'Always', 'Prefer Not'</td> <td>'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>
<tr><td>'Presence'</td><td>'Share', 'Not Share'</td><td>'Share'</td></tr>
</table>
<p>When joining a channel, the client MAY specify one or more preference options as a &xep0004; form. 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. The following example shows the message sent from the user's server to the MIX channel, which will have been preceded by a message from the user's client to the user's server.</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'/>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0</value>
</field>
<field var='JID Visibility'>
<value>Never</value>
</field>
</x>
</join>
</iq>
]]></example>
<p>The following example shows the result of a successful join, which also reports all the user preferences. This example shows the message coming from the MIX channel to the user's server, which will be sent on to the user.</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'/>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0</value>
</field>
<field var='JID Visibility'>
<value>Never</value>
</field>
<field var='Private Messages'>
<value>Allow</value>
</field>
<field var='vCard'>
<value>Block</value>
</field>
</x>
</join>
</iq>
]]></example>
<p>The client MAY also query the channel in order to find out which user preferences are supported and the options available. This will allow users to set options not specified in the standard, by providing a form template in the result. This query is direct from the client to the MIX channel.</p>
<example caption="User Requests and Recieves Preferences Template Form"><![CDATA[
<iq type='get'
from='hag66@shakespeare.example/UUID-a1j/7533'
to='coven@mix.shakespeare.example'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<user-preference xmlns='urn:xmpp:mix:0'/>
</iq>
<iq type='result'
from='coven@mix.shakespeare.example'
to='hag66@shakespeare.example/UUID-a1j/7533'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<user-preference xmlns='urn:xmpp:mix:0'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0</value>
</field>
<field type='list-single' label='Preference for JID Visibility'
var='JID Visibility'>
<option label='JID Never Shown'><value>Never</value></option>
<option label='Default Behaviour'>
<value>Default</value></option>
<option label='Try not to show JID'>
<value>Prefer Not</value></option>
</field>
<field type='list-single' label='Example Custom Preference'
var='Custom Preference'>
<option label='One Option'><value>A</value></option>
<option label='Another Option'><value>B</value></option>
</field>
</x>
</user-preference>
</iq>
]]></example>
<p>
A user MAY modify preferences using the corresponding set operation. The set MAY specify values for some or all attributes. All attributes are returned in the result.
</p>
<example caption="User Updates Preferences"><![CDATA[
<iq type='set'
from='hag66@shakespeare.example/UUID-a1j/7533'
to='coven@mix.shakespeare.example'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<user-preference xmlns='urn:xmpp:mix:0'/>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0</value>
</field>
<field var='JID Visibility'>
<value>Never</value>
</field>
<field var='Private Messages'>
<value>Allow</value>
</field>
<field var='vCard'>
<value>Block</value>
</field>
</x>
</iq>
<iq type='result'
from='coven@mix.shakespeare.example'
to='hag66@shakespeare.example/UUID-a1j/7533'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<user-preference xmlns='urn:xmpp:mix:0'>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0</value>
</field>
<field var='JID Visibility'>
<value>Never</value>
</field>
<field var='Private Messages'>
<value>Allow</value>
</field>
<field var='vCard'>
<value>Block</value>
</field>
</x>
</user-preference>
</iq>
]]></example>
</section3>
<section3 topic='Leaving a Channel' anchor='usecase-user-leaving'>
<p>Users generally remain in a channel for an extended period of time. In particular the user remains as a participant the channel when the user goes offline. Note that this is different to &xep0045;, where the client leaves a room when going offline. So, leaving a MIX channel is a permanent action for a user across all clients. In order to leave a channel, a user sends a MIX "leave" command to the channel. When a user leaves the channel, the user's server will remove the channel from the user's roster. Leave commands are sent indirectly through the user's server, to enable roster removal. Leaving is initiated by a client request, as shown in the following example.</p>
<example caption="Client Requests to Leave a Channel"><![CDATA[
<iq type='set'
from='hag66@shakespeare.example/UUID-a1j/7533'
to='hag66@shakespeare.example'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<leave xmlns='urn:xmpp:mix:0'
channel=`coven@mix.shakespeare.example`/>
</iq>
]]></example>
<p>
The user's server will then generate a matching request to the MIX channel.
</p>
<example caption="User's Server sends Leave Request to a Channel"><![CDATA[
<iq type='set'
from='hag66@shakespeare.example'
to='coven@mix.shakespeare.example'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<leave xmlns='urn:xmpp:mix:0'/>
</iq>
]]></example>
<p>
The MIX channel will then remove the user from the channel, as described below. A response is sent to the user's server.
</p>
<example caption="Channel Confirms Leave to User's Server"><![CDATA[
<iq type='result'
from='coven@mix.shakespeare.example'
to='hag66@shakespeare.example'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<leave xmlns='urn:xmpp:mix:0'/>
</iq>
]]></example>
<p>
After receiving the confirmation that the user has left the MIX channel, the user's server will remove the MIX channel entry from the user's roster. The user's server will then notify the client that requested to leave.
</p>
<example caption="User's Server Confirms Leave to Client"><![CDATA[
<iq type='result'
from='coven@mix.shakespeare.example'
to='hag66@shakespeare.example/UUID-a1j/7533'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<leave xmlns='urn:xmpp:mix:0'/>
</iq>
]]></example>
<p>When the user leaves the channel, the MIX service is responsible for unsubscribing the user from all nodes in the channel and for removing the user from the participants and presence list. If the user has online presence when the user leaves the channel, the change of presence status caused by removing the user's entry or entries from the presence node will ensure that subscribers to the presence node are correctly updated on presence status.
Deletion from the participants and presence functions as if the item (channel participant) had been deleted using the PubSub retract mechanism with notification set to true. Notification of the deletion is sent to clients subscribed to the participants PubSub nodes, as shown in the example below.
</p>
<example caption="Reporting when User Leaves a Channel"><![CDATA[
<message from='coven@mix.shakespeare.example'
to='hecate@shakespeare.example' id='f5pp2toz'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='urn:xmpp:mix:nodes:participants'>
<retract id='123456#coven@mix.shakespeare.example'/>
</items>
</event>
</message>
<message from='coven@mix.shakespeare.example'
to='other-witch@shakespeare.example' id='bar'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='urn:xmpp:mix:nodes:presence'>
<retract id='123456#coven@mix.shakespeare.example/8765'/>
</items>
</event>
</message>
]]></example>
</section3>
<section3 topic="Setting a Nick" anchor="usecase-setting-nick">
<p>
Each participant of a channel MAY have a nick, which is how other users in the channel will see the user. In some cases a nick is not needed, for example where a user reads messages in a channel but does not send messages or share presence information. A nick MUST be present for a user to send a message to a channel or for a user's presence to be shared on a channel. There are four ways that a user's nick can be obtained. The choice of mechanism or mechanisms is dependent on channel policy:
</p>
<ol>
<li>The nick is registered with the user account in some way, for example as part of user provisioning with nick configured as an attribute in a directory service. For example, this could be chosen by corporate services that wish to ensure consistent nick values for a set of users and channels.</li>
<li>The nick is registered with the MIX service, as described in <link url='#usecase-user-register'> Registering a Nick </link>.</li>
<li>The user explicitly sets the nick, as described in this section.</li>
<li>The MIX service generates the nick. In this case it is RECOMMENDED that the assigned nick is a UUID following &rfc4122;.</li>
</ol>
<p>
A user will typically set a nick when joining a channel and MAY update this nick from time to time. The user does this by sending a command to the channel to set the nick. If the user wishes the channel to assign a nick (or knows that the channel will assign a nick) the nick field can be left blank, so that the user can see what is assigned in the result.
</p>
<example caption="User sets Nick on Channel"><![CDATA[
<iq type='set'
from='hag66@shakespeare.example/UUID-a1j/7533'
to='coven@mix.shakespeare.example'
id='7nve413p'>
<query xmlns='urn:xmpp:mix:0'>
<nick>thirdwitch</nick>
</query>
</iq>
]]></example>
<p>
The channel will return the nick that is to be used, noting that this MAY be different to the requested nick. MIX services SHOULD apply the "nickname" profile of the PRECIS OpaqueString class, as defined in &rfc7700;.
</p>
<example caption="Channel informs user of Nick"><![CDATA[
<iq type='result'
from='coven@mix.shakespeare.example'
to'hag66@shakespeare.example/UUID-a1j/7533'
id='7nve413p'>
<query xmlns='urn:xmpp:mix:0'>
<nick>thirdwitch</nick>
</query>
</iq>
]]></example>
</section3>
<section3 topic='Registering a Nick' anchor='usecase-user-register'>
<p>A nick MAY be associated with the user's bare JID. A user can register a nick with the MIX service. Nick registration can be used ensure that a user is able to use the same nick in all channels in the service and to prevent other users from using a registered nick. This can help achieve a consistent experience across a set of channels and prevent user confusion. Support for nick registration by a MIX service is OPTIONAL. Where nick registration is supported, nick registration MAY be OPTIONAL or MANDATORY.
Where a user has registered a Nick with the MIX service, it MAY be used by each channel according to policy for the channel. A channel MAY enforce use of a registered nick. A channel MUST NOT use a registered nick for any other participant.
</p>
<p>
In order to determine if a Nick is allowed to be registered, the user MAY use disco to determine capabilities of the MIX service.
</p>
<example caption="User Determines features of the MIX service"><![CDATA[
<iq type='get'
from='hag66@shakespeare.example/UUID-a1j/7533'
to='mix.shakespeare.example'
id='7nve413p'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
<iq type='result'
to='hag66@shakespeare.example/UUID-a1j/7533'
from='mix.shakespeare.example'
id='7nve413p'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
<feature var='urn:xmpp:mix:0#mix_nick_register'/>
</query>
</iq>
]]></example>
<p>
The response will be a list of features of the MIX channel. If Nick Registration is supported, then the result set will include &lt;feature var="urn:xmpp:mix:0#mix_nick_register"/&gt;.
</p>
<p>
To register a nick with the MIX service the user sends
a &lt;register/&gt; command to the service. </p>
<example caption="User Registers with Service"><![CDATA[
<iq type='set'
from='hag66@shakespeare.example/UUID-a1j/7533'
to='mix.shakespeare.example'
id='7nve413p'>
<register xmlns='urn:xmpp:mix:0'>
<nick>thirdwitch</nick>
</register>
</iq>
]]></example>
<p>On success, the service informs the user of its nick. MIX SHOULD apply the "nickname" profile of the PRECIS OpaqueString class, as defined in &rfc7700; to the requested nick. This means that nick that is issued might be different from the nick that was requested.</p>
<example caption="Service Returns User of Nick"><![CDATA[
<iq type='result'
to='mix.shakespeare.example'
from='hag66@shakespeare.example/UUID-a1j/7533'
id='7nve413p'>
<register xmlns='urn:xmpp:mix:0'>
<nick>thirdwitch</nick>
</register>
</iq>
]]></example>
<p>If the requested nick is already taken, the MIX service returns a &lt;conflict/&gt; error:</p>
<example caption="Nick is Taken">
<![CDATA[<iq type='error'
to='mix.shakespeare.example'
from='hag66@shakespeare.example/UUID-a1j/7533'
id='7nve413p'>
<error type='cancel'>
<conflict xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>
</error>
</iq>
]]></example>
<p>If the register request does not contain a &lt;nick/&gt; element, then the MIX service assigns one. It is RECOMMENDED that the assigned nick is a UUID following &rfc4122;.
</p>
</section3>
<section3 topic='Setting User Presence' anchor='usecase-user-presence'>
<p>
A user joins a channel over an extended period, and participation in a channel does not generally change when user goes online or offline. The user's participation in a channel is reflected by the user's bare JID in the participant node. All messages to the channel are sent to this JID.
</p>
<p>
A user MAY share presence information with the channel, for one or more online clients. Where a user shares presence information with a channel, the channel is entered by the user's server into the user's roster when the user subscribes to the channel. When an XMPP client comes online or changes presence status, this will be communicated by the user to the user's server using broadcast presence. The user's XMPP server is then responsible to share this presence information to each entry in the roster and in particular to each MIX channel in the roster. The MIX channel will update the "urn:xmpp:mix:nodes:presence" node with any change of status and the updated presence information and then share this updated presence with users subscribed to this node, as described below. When the user sets an explicit status, this is used to modify the presence node in the channel. When a client being used by the user goes offline, the associated server will send presence status "unavailable" to the MIX channel, which will cause the full JID for that client to be removed from the presence node.
</p>
<p>
A channel MAY require that all channel participants share presence information with the channel, which is represented in the "urn:xmpp:mix:nodes:presence" node. If sharing presences is needed by the channel, an XMPP client conforming to this specification MUST share presence with the channel by including the channel in the user's roster. Note that the MIX service cannot generally enforce this, but it can require and enforce that when a message is sent to the channel, that the sender of the message is in the presence list.
</p>
<p>
Presence status and availability is set in a MIX channel by standard presence stanzas sent to the MIX channel by the user's server. Users wishing to receive presence updates will subscribe to the MIX channel presence node. Presence updates are sent out to subscribing participants using standard presence stanzas.
</p>
<p>
A user setting status is now used as an example. Unlike in &xep0045; where coming online is a special action, coming online in MIX is implicit when presence status is set. Going offline is a achieved by setting presence status to unavailable, which removes the client full JID entry from the presence node. When a user sets a presence status, the user's server sends updated presence to the MIX channel, and the MIX service then publishes the user's availability to the "urn:xmpp:mix:nodes:presence" node. If there is not an item named by the full JID of the client with updated presence status, this item is created.</p>
<example caption="User Setting Presence Status">
<![CDATA[<presence xmlns='jabber:client' from=‘hag66@shakespeare.example/UUID-a1j/7533’
to='coven@mix.shakespeare.example'>
<show>dnd</show>
<status>Making a Brew</status>
</presence>]]></example>
<p>The user's presence information is then published by the service to the "urn:xmpp:mix:nodes:presence" node, with the 'publisher' attribute set to the user's participant identifier (the proxy JID). The MIX channel then broadcasts the presence change to all users who are subscribed to the "urn:xmpp:mix:nodes:presence" node. The presence stanza is sent from the full proxy JID of the user.
Note that presence is associated with a client and so will have a full JID as it comes directly from the client and not from the user's server.</p>
<example caption="Channel Distributes Presence">
<![CDATA[<presence from='123435#coven@mix.shakespeare.example/678'
to='coven@mix.shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'>
<nick xmlns='http://jabber.org/protocol/nick'>thirdwitch</nick>
<show>dnd</show>
<status>Making a Brew</status>
</presence>]]></example>
<p>
The presence is distributed to those subscribing to the MIX channel presence node using a standard XMPP presence stanza. The presence change is recorded on the "urn:xmpp:mix:nodes:presence" node. The history of this node will be held as PubSub format in the MAM archive, so that presence history can be viewed.
</p>
</section3>
<section3 topic="Client Coming Online and Obtaining Presence from the Local Server" anchor="usecase-obtaining-presence">
<p>
The presence information for a channel is stored in the urn:xmpp:mix:nodes:presence node and distributed using standard presence stanzas to the server of each user subscribing to this presence node. The user's local server will then pass this presence information on to all online clients. This ensures that an online client is kept updated with presence.
When a client goes offline, it will cease getting presence updates. Presence updates will continue to flow to the user's local server, and so the local server is able maintain up to date presence state for the channel.
</p>
<p>
When the client comes online, it will activate use of the MIX. The user's server will then send full presence status to the client using standard presence messages. This will enable the client to update presence information for the channel. Note that this does not need any interaction with the channel.
</p>
</section3>
<section3 topic="Updating Presence on User&apos;s Server" anchor="usecase-server-presence-update">
<p>
In normal operation a MIX participant's server will hold accurate presence status for the channel which it provides to clients when they are activated. Incoming presence updates are immediately sent to active MIX clients.
</p>
<p>
There are two situations where a MIX participant's server will need to get presence status from the channel. The first time is when a user joins the channel as a participant and subscribes to presence. Upon this subscription the MIX channel will send to the participant's server (using the user's bare JID) presence for all of the items in the presence node using standard presence stanzas. This will give the participant's full current presence for the channel.
</p>
<p>
The second scenario is when the MIX participant's server needs to load or refresh presence status for a channel. This will be needed when the participant's server is started. This MIX participant's server requests presence update by sending a directed presence stanza to the MIX channel from the user's bare JID. The MIX channel can distinguish this from a presence update, which will always be sent from the clients full JID. This special presence stanza will send to the participant's server (using the user's bare JID) presence for all of the items in the presence node using standard presence stanzas.
</p>
</section3>
<section3 topic="Determining Real JIDs" anchor="usecase-real-jids">
<p>
Presence information will provide a MIX client with the nicks and proxy JIDs for participants in a channel. Messages sent to a channel and retrieved from MAM archives will show the proxy JID and nick of the sender. It is sometimes useful to determine the real JID associated with proxy JID. This can always be done for JID Visible channels and can sometimes be done for JID Maybe Visible channels.
</p>
<p>
For current users JID visible rooms, the real JID is found by a PubSub lookup on the JID Map node. This is shown in the following example:
</p>
<example caption='Client looks up Real JID from Proxy JID'><![CDATA[
<iq from='hag66@shakespeare.example/UUID-c8y/1573'
id='kl2fax27'
to='coven@mix.shakespeare.lit'
type='get'>
<pubsub xlns='http://jabber.org.protocol.pubsub'>
<items node='urn:xmpp:nodes:jidmap'>
<item id='123456#coven@mix.shakespeare.example'/>
</items>
</pubsub>
</iq>
<iq from='coven@mix.shakespeare.lit'
id='kl2fax27'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<pubsub xlns='http://jabber.org.protocol.pubsub'>
<items node='urn:xmpp:nodes:jidmap'>
<item id='123456#coven@mix.shakespeare.example'>
<participant xmlns='urn:xmpp:mix:0'
jid='hecate@mix.shakespeare.example'/>
</item>
</items>
</pubsub>
<items>
</iq>]]> </example>
<p>For JID Maybe Visible rooms the lookup is performed on the JID Maybe Visible Map node. Note that where a user prefers to not share real JID, the result of this lookup of proxy JID will be the (same) proxy JID. </p>
<p>
When an older message is considered, it is possible that the proxy JID of the sender is not current. Such a JID can be looked up in the MAM Archive of the JID Map Node. This is shown in the following example:
</p>
<example caption='Client looks up Real JID from Proxy JID in MAM Archive'><![CDATA[
<iq from='hag66@shakespeare.example/UUID-c8y/1573'
id='kl2fax27'
to='coven@mix.shakespeare.lit'
type='set'>
<query xlns='urn:xmpp:mam:2'
queryid='f28'
node='urn:xmpp:nodes:jidmap'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mam:2</value>
</field>
<field var='id'>
<value>123456#coven@mix.shakespeare.example</value>
</field>
</x>
</query>
</iq>
<message id='iasd208' to='hag66@shakespeare.example/UUID-c8y/1573'>
<result xmlns='urn:xmpp:mam:2' queryid='f28' id='28482-20987-73623'>
<forwarded xmlns='urn:xmpp:forward:0'>
<delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:08:25Z'/>
<message xmlns="jabber:client">
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='urn:xmpp:nodes:jidmap'>
<item id='123456#coven@mix.shakespeare.example'>
<participant xmlns='urn:xmpp:mix:0'
jid='hecate@mix.shakespeare.example'/>
</item>
</items>
</event>
</message>
</forwarded>
</result>
</message>
<iq from='coven@mix.shakespeare.lit'
to='hag66@shakespeare.example/UUID-c8y/1573'
id='kl2fax27'
type='result'>
</iq>]]> </example>
</section3>
<section3 topic="Coming Online: Synchronizing Message History" anchor="usecase-sync-history">
<p>
A MIX client will typically display message history of the channel to the user. When a client comes online it will need to obtain this message history from the MAM archive associated with the channel. There are three basic approaches a client will take:
</p>
<ol>
<li>If the client has previously displayed message history and has been offline for a reasonably small time, the client MAY wish to retrieve all messages since the last one displayed to the user.</li>
<li>The client MAY wish to display a fixed number of messages, perhaps finding more messages if the user subsequently requests.</li>
<li>The client MAY wish to display messages from a recent time period, perhaps finding more messages if the user subsequently requests.</li>
</ol>
<p>To achieve this, the client will query the user's own MAM archive using &xep0313;, with the query filtered by the channel JID. This gives the client flexibility to retrieve and display message history in a manner appropriate to the client implementation.</p>
<p>
The only exception to this is when a user wishes to access message history in the channel prior to when the user joined the channel. To achieve this, the client will use MAM to retrieve message history directly from the MAM Archive of the MUX channel.
</p>
</section3>
<section3 topic='Going Offline' anchor='usecase-user-offline'>
<p>When a client goes offline, this presence update is sent by the client's server to the MIX channel. From the client perspective, this is the same as any other presence change. Handling by the MIX channel is slightly different.</p>
<example caption="Client Goes Offline in the Channel"><![CDATA[
<presence type='unavailable'
from='hag66@shakespeare.example/UUID-a1j/7533'
to='coven@mix.shakespeare.example'/>
]]></example>
<p>The MIX channel will retract (remove) the item in the presence node of the MIX channel identified by the client's full JID. The MIX channel will notify subscribers to the presence node of the user going offline by sending a presence stanza to the full proxy JID of each client.</p>
<example caption="Channel Distributes Notification of Client going Offline">
<![CDATA[<presence from='12345#coven@mix.shakespeare.example/678'
to='hecate@shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
type='unavailable'/>]]></example>
<p>
There is the possibility that the message associated with the user going offline will be lost. If this happens, "ghost" entries will appear in the presence node. A MIX service MAY take steps to address this, for example by probing client with a disco for presence items that remain unchanged for a long period.
</p>
<p>
It is desirable to prevent clients from going offline briefly and then coming back online again, as this will lead to "flapping presence". The RECOMMENDED approach to achieve this is use of &xep0198; to maintain an XMPP client connection in the event of short term TCP failure.
</p>
</section3>
<section3 topic='Sending a Message' anchor='usecase-user-message'>
<p>A client sends a message directly to a MIX channel as a standard groupchat message, in exactly the same way as for &xep0045;. Messages are sent directly to the MIX channel from the user's client. The message id is selected by the client.</p>
<example caption="User Sends Message to Channel"><![CDATA[
<message from='hag66@shakespeare.example/UUID-a1j/7533'
to='coven@mix.shakespeare.example'
id='92vax143g'
type='groupchat'>
<body>Harpier cries: 'tis time, 'tis time.</body>
</message>
]]></example>
<p>The MIX channel then puts a copy of the message into the MAM archive for the channel and sends a copy of the message to each participant in
standard groupchat format. These messages sent by the channel are addressed to the bare JID of each participant and this will be handled by the participant's local server. The message from value is the JID of the channel. To enable sender identification, the Nick and bare proxy JID of the sender are included in the message as MIX parameters. The id of the message is the ID from the MAM archive and NOT the id used by the sender. The message placed in the MAM archive is the reflected message without a 'to' element.</p>
<example caption="Channel Puts Message in MAM Archive"><![CDATA[
<message from='coven@mix.shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
type='groupchat'>
<body>Harpier cries: 'tis time, 'tis time.</body>
<nick xmlns='urn:xmpp:mix:0'>thirdwitch</nick>
<jid xmlns='urn:xmpp:mix:0'>123456#coven@mix.shakespeare.example</jid>
</message>
]]></example>
<example caption="Channel Reflects Message to Participants"><![CDATA[
<message from='coven@mix.shakespeare.example'
to='hecate@shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
type='groupchat'>
<body>Harpier cries: 'tis time, 'tis time.</body>
<nick xmlns='urn:xmpp:mix:0'>thirdwitch</nick>
<jid xmlns='urn:xmpp:mix:0'>123456#coven@mix.shakespeare.example</jid>
</message>
]]></example>
<p>
The messages sent to participants have a different message id to the originally submitted message. This does not impact most recipients, but it does not allow the message originator to correlate the message with the submitted message. To address this the MIX channel MUST include an additional element of the message copy going back to the originator's bare JID that includes the original id. This enables the originator to correlate the received message with the message submitted.
</p>
<example caption="Channel Reflects Message back to Originator"><![CDATA[
<message from='coven@mix.shakespeare.example'
to='hag66@shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
type='groupchat'>
<body>Harpier cries: 'tis time, 'tis time.</body>
<nick xmlns='urn:xmpp:mix:0'>thirdwitch</nick>
<jid xmlns='urn:xmpp:mix:0'>123456#coven@mix.shakespeare.example</jid>
<submission-id xmlns='urn:xmpp:mix:0'>92vax143g</submission-id>
</message>
]]></example>
</section3>
<section3 topic="Retracting a Message" anchor="usecase-retract">
<p>
A MIX channel MAY support message retraction, where the sender of a messages or an authorized administrator deletes a message. If this is done the original message MAY be replaced by a tombstone. The protocol to request retraction does this by a message with a &lt;retract&gt; element as shown in the following example.
</p>
<example caption="User Retracts a Message"><![CDATA[
<message from='hag66@shakespeare.example/UUID-a1j/7533'
to='coven@mix.shakespeare.example'
id='92vax143g'>
<retract id='28482-98726-73623' xmlns='urn:xmpp:mix:0'/>
</message>
]]></example>
<p>
The MIX channel will allow a user to retract a message sent by the user if the 'Allow User Message Retraction' option is configured. The MIX channel will allow an administrative user to retract any message if the user is in the group specified by the 'Administrator Message Retraction Rights' option.
</p>
<p>
If the retraction message is accepted, it will be distributed to channel participants. This will allow retraction to happen in the MAM archive of each channel participant and to reflect the retraction in client GUI. A client receiving a retraction message SHOULD ensure that the retracted message is no longer displayed to the end user.
</p>
<p>
Two approaches to message retraction can be used. In the first approach, the retracted message is simply removed. This is appropriate where retraction is provided as a user service and the user has rights to remove messages sent from the record.
</p>
<p>
The second approach is to leave a tombstone, which if taken MUST be done in the following manner. This is appropriate where it is desired to leave a record of the message that was redacted.
With this approach, the original message &lt;body&gt; is removed and replaced with a tombstone using the &lt;retracted&gt; element that shows the JID of user performing the retraction and the time of the retraction.
</p>
<example caption="Retracted message tombstone in a MAM result"><![CDATA[
<message id='aeb213' to='juliet@capulet.lit/UUID-e3r/9264'>
<result xmlns='urn:xmpp:mam:1' queryid='f27' id='28482-98726-73623'>
<forwarded xmlns='urn:xmpp:forward:0'>
<delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:08:25Z'/>
<message xmlns='jabber:client' from="hag66@shakespeare.example"
to="macbeth@shakespeare.lit">
<retracted xmlns='urn:xmpp:mix:0' by='hag66@shakespeare.example'
time='2010-07-10T23:08:25Z'/>
</message>
</forwarded>
</result>
</message>
]]></example>
</section3>
<section3 topic='Telling another User about a Channel' anchor='usecase-user-tell'>
<p>
A convenient way to reference another channel is to use &xep0372; which enables the JID of a channel to be shared. This might be used simply to inform the message recipient about the channel or as mechanism to invite the user to join the channel. This is useful as an invitation mechanism to a channel that any user can join or where the invitee knows that the user is allowed to join (e.g., because the channel is for all users in an organization).
</p>
</section3>
<section3 topic='Inviting another User to join a Channel that the user does not have Permission to Join' anchor='usecase-user-invite'>
<p> Invitation by reference, as described in the previous section, is a convenient approach to invite a user to join a channel that the user has permission to join. This section describes the approach used when the inviter has permission to grant rights for the invitee to become a channel participant. This might be because the inviter is an administrator of the channel or the channel has a special mode where channel participants are allowed to grant rights for other users to join a channel enabled ('Participation Addition by Invitation from Participant'). This approach is used to avoid cluttering the allowed node with JIDs of users who are invited to join, but do not accept the invitation.
When a channel participant(the inviter) invites another user (the invitee) to join a channel, the following sequence of steps is followed:
</p>
<ol>
<li>The inviter checks with disco that the invitee supports MIX.</li>
<li>The channel inviter sends to the channel requesting an invite for the invitee.</li>
<li>The channel sends an invitation to the inviter.</li>
<li>The inviter sends the invitation to the invitee.</li>
<li>The invitee MAY use the invitation to join the channel.</li>
<li>The invitee MAY send a response to the inviter, indicating if the invitation was accepted or declined.</li>
</ol>
<p>
The first step is for the inviter to request an invitation from the channel. The invitation contains inviter, invitee and a token. The channel will evaluate if the inviter has rights to issue the invitation. This will be because the inviter is a channel administrator or if the inviter is a channel participant and the channel has 'Participation Addition by Invitation from Participant' mode enabled. If the inviter has rights to make the invitation, the channel will return a token. The token is a string that the channel can subsequently use to validate an invitation. The format of the token is not specified in this standard. The encoded token MAY reflect a validity time.
</p>
<example caption='Inviter Requests and Receives Invitation'><![CDATA[
<iq from='hag66@shakespeare.lit/UUID-h5z/0253'
id='kl2fax27'
to='coven@mix.shakespeare.lit'
type='get'>
<invite xmlns='urn:xmpp:mix:0'>
<invitee>cat@shakespeare.lit</invitee>
</invite>
</iq>
<iq from='coven@mix.shakespeare.lit'
id='kl2fax27'
to='hag66@shakespeare.lit/UUID-h5z/0253'
type='result'>
<invite xmlns='urn:xmpp:mix:0'>
<invitation>
<inviter>hag66@shakespeare.lit</inviter>
<invitee>cat@shakespeare.lit</invitee>
<channel>coven@mix.shakespeare.lit</channel>
<token>ABCDEF</token>
</invitation>
<invite/>
</iq>
]]></example>
<p>
The inviter can now send the invitee a message containing the invitation, as shown in the following example.
</p>
<example caption='Inviter sends Invitation to Invitee'><![CDATA[
<message from='hag66@shakespeare.lit/UUID-h5z/0253'
id='f5pp2toz'
to='cat@shakespeare.lit'>
<body>Would you like to join the coven?<body>
<invitation xmlns='urn:xmpp:mix:0'>
<inviter>hag66@shakespeare.lit</inviter>
<invitee>cat@shakespeare.lit</invitee>
<channel>coven@mix.shakespeare.lit</channel>
<token>ABCDEF</token>
</invitation>
</iq>
]]></example>
<p>The invitation can now be used by the invitee to join a channel. The invitation is simply added to the standard channel join, so that the channel can validate the invitation using the token. If the allowed node is present and the invitee is not matched against any item, the channel MUST add the invitee to the allowed node as part of the join.</p>
<example caption="User Joins a Channel with an Invitation"><![CDATA[
<iq type='set'
from='cat@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'/>
<invitation>
<inviter>hag66@shakespeare.lit</inviter>
<invitee>cat@shakespeare.lit</invitee>
<channel>coven@mix.shakespeare.lit</channel>
<token>ABCDEF</token>
</invitation>
</join>
</iq>
]]></example>
<p>The invitee MAY send an acknowledgement back to the inviter, noting the status of the invitation. Values are:</p>
<ul>
<li>'Joined': The invitee has joined the channel.</li>
<li>'Declined': The invitee is not taking up the invitation.</li>
<li>'Acknowledged': The invitation is acknowledged, without information on action taken or planned.</li>
</ul>
<example caption='Invitee sends Acknowledgement to Inviter'><![CDATA[
<message from='cat@shakespeare.lit/UUID-l1w/8813'
id='b6p9llze'
to='hag66@shakespeare.lit/UUID-h5z/0253'>
<body>No Thanks - too busy chasing mice....<body>
<invitation-ack xmlns='urn:xmpp:mix:0'>
<value>Declined</value>
<invitation>
<inviter>hag66@shakespeare.lit</inviter>
<invitee>cat@shakespeare.lit</invitee>
<channel>coven@mix.shakespeare.lit</channel>
<token>ABCDEF</token>
</invitation>
</invitation-ack>
</iq>
]]></example>
</section3>
<section3 topic='Sending Private Messages' anchor='usecase-user-private-messages'>
<p>
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 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>
<tr><td>First Message from MIX Channel to responder's server</td><td>Proxy full JID of initiator's client</td><td>Bare JID of responder</td></tr>
<tr><td>First Message from responder's server to one or more of the responder's clients</td><td>Proxy full JID of initiator</td><td>Full JID of responder's client</td></tr>
<tr><td>Messages from responder's client to MIX Channel</td><td>Full JID of responder's client</td><td>Proxy full JID of initiator's client</td></tr>
<tr><td>Messages from MIX channel to initiator's client</td><td>Proxy full JID of responder's client</td><td>Full JID of initiator's client</td></tr>
<tr><td>Messages from initiator's client to MIX Channel</td><td>Full JID of initiator's client</td><td>Proxy full JID of responder's client</td></tr>
<tr><td>Message from MIX Channel to responder's client</td><td>Proxy full JID of initiator's client</td><td>Full JID of responder's client</td></tr>
</table>
<p>Private Messages MAY be archived using MAM by the XMPP servers associated with initiator and responder. Private Messages MUST NOT be archived by the MIX channel.</p>
</section3>
<section3 topic="Requesting vCard" anchor="usecase-vcard">
<p>A user MAY request the vCard of a channel participant by sending a request through the channel. The request MAY be sent directly by the client or MAY be sent by the user's server on behalf of the user. The MIX channel MAY pass this request on or MAY block it. vCard requests MAY use &xep0054; (vcard-temp) or &xep0292; (vCard4 over XMPP). Where a MIX service supports one or both of these protocols, the protocol MUST be advertised as a feature of the MIX service. In the following example, using vcard-temp, the requesting client sends a message to the bare proxy JID of the channel participant for which the vCard is desired.</p>
<example caption="Client directly requests vCard through channel" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-c8y/1573'
id='lx09df27'
to='989898#coven@mix.shakespeare.example'
type='get'>
<vCard xmlns='vcard-temp'/>
</iq>
]]></example>
<p>The MIX channel MAY pass on the vCard request or MAY reject with an error, dependent on channel policy. The MIX service will then address the vCard request to the user's server (using bare JID) using a full proxy JID to hide the requester. </p>
<example caption="Channel passes on vCard request to the User&apos;s Server" ><![CDATA[
<iq from='123456#coven@mix.shakespeare.example/6789'
id='lx09df27'
to='peter@shakespeare.lit'
type='get'>
<vCard xmlns='vcard-temp'/>
</iq>
]]></example>
<p>
The user's server, on behalf of the user, MAY send a response or reject with an error. The user's server will send the vCard back to the channel.
</p>
<example caption="User's Server sends vCard Response via MIX channel" ><![CDATA[
<iq from='peter@shakespeare.lit'
id='lx09df27'
to='123456#coven@mix.shakespeare.example/6789'
type='result'>
<vCard xmlns='vcard-temp'>
<FN>Peter Saint-Andre</FN>
<N>
<FAMILY>Saint-Andre</FAMILY>
<GIVEN>Peter</GIVEN>
<MIDDLE/>
</N>
<NICKNAME>stpeter</NICKNAME>
<URL>http://www.xmpp.org/xsf/people/stpeter.shtml</URL>
</vCard>
<query xmlns='http://jabber.org/protocol/disco#info'>
</iq>
]]></example>
<p>
The MIX channel will then send the vCard response to the requesting client on behalf of the client sending the response.
</p>
<example caption="MIX Channel sends vCard responst to Client" ><![CDATA[
<iq from='989898#coven@mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<vCard xmlns='vcard-temp'>
<FN>Peter Saint-Andre</FN>
<N>
<FAMILY>Saint-Andre</FAMILY>
<GIVEN>Peter</GIVEN>
<MIDDLE/>
</N>
<NICKNAME>stpeter</NICKNAME>
<URL>http://www.xmpp.org/xsf/people/stpeter.shtml</URL>
</vCard>
</iq>
]]></example>
</section3>
</section2>
<section2 topic="Presence Initializion" anchor="use-presence-initialize">
<p>
For an active MIX Channel, the presence node is updated as channel participants change status and presence information is sent to the channel. When a MIX channel starts, typically when the associated MIX Service and Server start, there is a need to initialize the presence node. This is done by the XMPP server associated with the MIX channel sending out a presence probe for each channel participant, following the presence probe process specified in &rfc6121;. A presence probe MUST NOT be sent for users who have set presence preference to not sharing.
</p>
</section2>
<section2 topic="Ensuring Message Delivery" anchor="use-ensure-delivery">
<p>
It is important that messages are all transferred from the MIX channel to the server associated with the each channel participant. Transfer between servers will typically happen quickly and &xep0198; will deal with short connection failures between servers. Longer connection failures could lead to message loss. This would lead to online users (who remain connected to their servers) missing messages, and to messages being missed out of the user archive. This section describes how MIX addresses this.
</p>
<p>
When there is a long term connection failure, the MIX channel will receive an error from the XMPP server indicating that a message failed to transfer to a recipient. When this happens, the MIX channel MUST take responsibility to ensure that the message is retransmitted and delivered. When the MIX channel detects a failure it will make use of an IQ Marker message to determine when the connection to the peer server is working again. Once the channel has received a response to the marker IQ it will retransmit the pending messages.
</p>
<example caption="Channel Sends Marker Message" ><![CDATA[
<iq from='coven@mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example'
type='get'>
<marker xmlns='urn:xmpp:mix:0'/>
</iq>
<iq from='hag66@shakespeare.example'
id='lx09df27'
to='coven@mix.shakespeare.example'
type='result'>
<marker xmlns='urn:xmpp:mix:0'/>
</iq>
]]></example>
</section2>
<section2 topic="Use of MAM" anchor="use-mam">
<p>
All messages sent to a MIX channel MUST be archived using MAM in association with the MIX channel. All messages MUST also be archived on the server associated with each channel participant receiving the message, which enables clients to always retrieve messages from the clients MAM archive. Other channel nodes MAY be archived.
</p>
<section3 topic="Archive of Messages" anchor="use-mam-messages">
<p>
Messages sent to participants MUST be archived by both the MIX channel and by the user's server. This MAY include presence messages. Correct MIX operation relies on messages being archived.
</p>
</section3>
<section3 topic="Retrieving Messages" anchor="use-mam-retrieve">
<p>
Clients will retrieve MIX messages using standard MAM protocol from the user's archive. The MAM query will filter based on the channel JID to enable access to messages from a given channel. This gives the user a simple mechanism to access all messages sent to the channel. MAM can be used to retrieve older messages that have not been cached by the client.
</p>
<p>
Messages can also be retrieved from the channel by addressing MAM queries to the channel JID. This will behave like a standard MAM archive. This can be useful for administrators to access archived messages. It can also be useful for new channel participants to access the historical archives.
</p>
</section3>
<section3 topic="MAM Use with other Channel Nodes" anchor="use-mam-other-nodes">
<p>
A MIX Channel MAY use MAM to archive nodes other than message nodes. Clients with rights to access these archives MAY use MAM to do this, specifying the PubSub node in the MAM query addressed to the channel.
</p>
</section3>
</section2>
<section2 topic='Administrative Use Cases' anchor='usecases-admin'>
<section3 topic='Checking For Permission To Create a Channel' anchor='usecase-admin-check-create'>
<p>
MIX does not standardize an access control model for creating and deleting MIX channels. The choice is left to the MIX implementer, and could be a very simple or complex approach. A client can determine if it has permission to create a channel on a MIX service, which MAY be used to control options presented to the user. This is achieved by a disco command on the MIX service. If the 'urn:xmpp:mix:0#create-channel' feature is returned, the user is able to create a channel.
</p>
<example caption="Client determines Capability to Create a Channel" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-c8y/1573'
id='lx09df27'
to='mix.shakespeare.example'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity
category='conference'
name='Shakespearean Chat Service'
type='text'/>
<feature var='urn:xmpp:mix:0'/>
<feature var='urn:xmpp:mix:0#create-channel'>
</query>
</iq>
]]></example>
</section3>
<section3 topic='Creating a Channel' anchor='usecase-admin-create'>
<p>
A client creates a channel by sending a simple request to the MIX service. A channel MAY be created with default parameters, as shown in the following example. The result MUST include the name of the channel which MUST match the channel name in the request (if present). Creating and destroying a channel is done direct from a client.
</p>
<example caption="Creating a Channel with Default Parameters" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
id='lx09df27'
to='mix.shakespeare.example'
type='set'>
<create channel='coven' xmlns='urn:xmpp:mix:0'/>
</iq>
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-a1j/7533'
type='result'>
<create channel='coven' xmlns='urn:xmpp:mix:0'/>
</iq>
]]></example>
<p>
The client MAY also include parameters in &xep0004; format as part of channel creation. If the client wishes to inspect configuration, channel administration procedures SHOULD be used.
</p>
<example caption="Creating a Channel with Client Specified Parameters" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
id='lx09df27'
to='mix.shakespeare.example'
type='set'>
<create channel='coven' xmlns='urn:xmpp:mix:0'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0</value>
</field>
<field var='Owner'>
<value>hecate@shakespeare.lit</value>
<value>greymalkin@shakespeare.lit</value>
</field>
<field var='Messages Node Subscription'>
<value>allowed</value>
</field>
<field var='JID Visibility'>
<value>jid-mandatory-visible</value>
</field>
<field var='No Private Messages'>
<value>true</value>
</field>
</x>
</create>
</iq>
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-a1j/7533'
type='result'>
<create channel='coven' xmlns='urn:xmpp:mix:0'/>
</iq>
]]></example>
</section3>
<section3 topic='Creating a Channel for Ad Hoc Use' anchor='usecase-admin-create-adhoc'>
<p>
Channels MAY be created for ad hoc use between a set of users. Channels of this nature will have channel name created by the server and will not be addressable or discoverable. Here a channel is created without specifying the channel name. Parameters for the channel MAY also be specified.
</p>
<example caption="Creating a Channel for Ad Hoc Use" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
id='lx09df27'
to='mix.shakespeare.example'
type='set'>
<create xmlns='urn:xmpp:mix:0'/>
</iq>
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-a1j/7533'
type='result'>
<create channel='A1B2C345' xmlns='urn:xmpp:mix:0'/>
</iq>
]]></example>
</section3>
<section3 topic="Converting a 1:1 Conversation to a Channel" anchor="usecase-admin-converting-chat">
<p>
A common use case for an ad hoc channel is where two users are engaged in a 1:1 chat and wish to broaden the discussion. Prior to bringing more users into a channel, using standard invitation process, there is a need to create and populate a channel. The first step is for one of the two users to create an ad hoc channel, as described in the previous section. The other user will then be invited, and can switch to the new channel.
</p>
<p>
It can also be useful to share some or all of the messages from the 1:1 discussion into the new channel. The mechanism to do this is to forward messages to be shared in the MUC using &xep0297;. A body SHOULD NOT be used in the outer message.
This will generally be done by the user creating the channel before the other user is invited, but MAY be sent by either the user creating the channel or the 1:1 chat partner at any time subsequently.
</p>
<example caption="Forwarding a message to create History" ><![CDATA[
<message from='hag66@shakespeare.example/UUID-a1j/7533'
to='A1B2C345@mix.shakespeare.example'
id='92vax143g'
type='groupchat'>
<forwarded xmlns='urn:xmpp:forward:0'>
<delay xmlns='urn:xmpp:delay' stamp='2010-07-10T23:08:25Z'/>
<message from='hag67@shakespeare.example/pda'
id='0202197'
to='hag66@shakespeare.example/UUID-a1j/7533'
type='chat'
xmlns='jabber:client'>
<body>Harpier cries: 'tis time, 'tis time.</body>
</message>
</forwarded>
</message>
]]></example>
</section3>
<section3 topic='Destroying a Channel' anchor='usecase-admin-destroy'>
<p>
MIX channels are always explicitly destroyed by an owner of the channel or by a server operator. There is no concept of temporary channel, equivalent to &xep0045; temporary room which is automatically destroyed by the server when the users leave. However, channels MAY be configured with an explicit lifetime, after which the channel MUST be removed by the MIX service. Where a channel is created for ad hoc use, it MAY be desirable to keep the channel for history reference or for re-use by the same set of users. Note that the owner of the channel does not need to have presence registered in the channel in order to destroy it.
</p>
<p>
A client destroys a channel using a simple set operation, as shown in the following example.
</p>
<example caption="Client Destroys a Channel" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
id='lx09df27'
to='mix.shakespeare.example'
type='set'>
<destroy channel='coven' xmlns='urn:xmpp:mix:0'/>
</iq>
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-a1j/7533'
type='result'>
</iq>
]]></example>
</section3>
<section3 topic='Server Destroying a Channel' anchor='usecase-server-destroy'>
<p>
A server MUST destroy a channel that has exceeded its specified explicit lifetime.
Servers MAY destroy channels which have no participants and/or presence according to local policy. There will often be good reasons to not destroy rooms in these scenarios, in particular to facilitate channel re-use and history access.
</p>
</section3>
<section3 topic='Modifying Channel Information' anchor='usecase-admin-information'>
<p>Authorized users, typically owners and sometimes administrators, MAY modify the channel information. The client MAY issue a pubsub get command to obtain a form that will facilitate update of the information node. The values in the form show current values, which be defaults or MAY have been explicitly set. In the following example, the channel name was previously set, but other values were not. </p>
<example caption="Getting Information Form" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
id='lx09df27'
to='mix.shakespeare.example'
type='get'>
<pubsub xmlns='http://jabber.org/protocol/'>
<items node='urn:xmpp:mix:nodes:info'/>
</pubsub>
</iq>
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-a1j/7533'
type='result'>
<pubsub xmlns='http://jabber.org/protocol/'>
<items node='urn:xmpp:mix:nodes:info'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0</value>
</field>
<title>Information Node Modification</title>
<field type='text-multi'
label='Channel Name'
var='Name'>
<value>Witches Coven</value>
</field>
<field type='text-multi'
label='Channel Description'
var='Description'/>
<field type=jid-single'
label='Channel Administrative Contact'
var='Contact'/>
</x>
</items>
</pubsub>
</iq>
]]></example>
<p> Updating the information node is done using a pubsub set command. The MIX channel MUST update the fields with values provided, leaving other fields unchanged. The result returns the id used in the information node item, which is the date/time of the modification. </p>
<example caption="Modifying Channel Information" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
id='lx09df27'
to='mix.shakespeare.example'
type='set'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:mix:nodes:info'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0</value>
</field>
<field var='Name'>
<value>Witches Coven</value>
</field>
<field var='Description'>
<value>A location not far from the blasted heath where
the three witches meet</value>
</field>
<field var='Contact'>
<value>greymalkin@shakespeare.lit</value>
</field>
</x>
</publish>
</pubsub>
</iq>
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-a1j/7533'
type='result'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:mix:nodes:info'>
<item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:0'/>
</publish>
</pubsub>
</iq>
]]></example>
</section3>
<section3 topic='Modifying Channel Configuration' anchor='usecase-admin-information'>
<p>Channel owners are allowed to modify the channel configuration. The client MAY issue a pubsub get command to obtain a form that will facilitate update of the configuration node. Other clients MAY be authorized to use this command to see the channel configuration, but only owners MAY update the configuration. The values in the form show current values, which MAY be defaults or MAY have been explicitly set. The following example shows a short form returned to illustrate the syntax. A typical configuration form will be much larger with many fields. Modifying channel configuration is done directly by a client.
</p>
<example caption="Getting Configuration Form" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
id='lx09df27'
to='mix.shakespeare.example'
type='get'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:mix:nodes:config'/>
</pubsub>
</iq>
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-a1j/7533'
type='result'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items xmlns='urn:xmpp:mix:0' node='urn:xmpp:mix:nodes:config'>
<x xmlns='jabber:x:data' type='form'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0</value>
</field>
<title>Configuration Node Modification</title>
<field type=jid-multi'
label='Channel Administrator'
var='Administrator'/>
</x>
</items>
</pubsub>
</iq>
]]></example>
<p> Updating the information node is done using a pubsub set command. The MIX channel MUST update the fields with values provided, leaving other fields unchanged. The result returns the id used in the configuration node item, which is the date/time of the modification. </p>
<example caption="Modifying Channel Configuration" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
id='lx09df27'
to='mix.shakespeare.example'
type='set'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:mix:nodes:config'>
<x xmlns='jabber:x:data' type='submit'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0</value>
</field>
<field var='Owner'>
<value>hecate@shakespeare.lit</value>
<value>greymalkin@shakespeare.lit</value>
</field>
<field var='Messages Node Subscription'>
<value>allowed</value>
</field>
<field var='JID Visibility'>
<value>jid-mandatory-visible</value>
</field>
<field var='No Private Messages'>
<value>true</value>
</field>
</x>
</publish>
</pubsub>
</iq>
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-a1j/7533'
type='result'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:mix:nodes:config'>
<item id='2016-05-30T09:00:00' xmlns='urn:xmpp:mix:0'/>
</publish>
</pubsub>
</iq>
]]></example>
</section3>
<section3 topic='Controlling Channel Partipcipants' anchor='usecase-admin-participants'>
<p>
Owners and Administrators are allowed to control which users can participate in a channel by use of Allowed and Banned lists using PubSub. These operations follow &xep0060; which sets out detailed protocol use and error handling.
Allowed and Banned lists MAY be read by PubSub get of the Banned and Allowed Nodes. This operation MAY be used by users as controlled by 'Allowed Node Subscription' and 'Banned Node Subscription' configuration node options (default Administrators).
</p>
<example caption="Client Reads Allowed Node" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
id='lx09df27'
to='mix.shakespeare.example'
type='get'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:mix:nodes:allowed'/>
</pubsub>
</iq>
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-a1j/7533'
type='result'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:mix:nodes:allowed'>
<item id='shakespeare.lit'/>
<item id='alice@wonderland.lit'/>
</items>
</pubsub>
</iq>
]]></example>
<p>
JIDs can be added to the Allowed and Banned nodes by a pubsub set command. This is used to add one item to a node.
</p>
<example caption="Client Adds a JID to the Allowed Node" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
id='lx09df27'
to='mix.shakespeare.example'
type='set'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:mix:nodes:allowed'>
<item id='marlow.lit'/>
</items>
</pubsub>
</iq>
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-a1j/7533'
type='result'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'/>
</iq>
]]></example>
<p>
JIDs can be removed from the Allowed and Banned nodes by pubsub retract command.
</p>
<example caption="Client Removes a JID to the Banned Node" ><![CDATA[
<iq from='hag66@shakespeare.example/UUID-a1j/7533'
id='lx09df27'
to='mix.shakespeare.example'
type='set'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<retract node='urn:xmpp:mix:nodes:banned'>
<item id='lear@shakespeare.lit'/>
</items>
</pubsub>
</iq>
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-a1j/7533'
type='result'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'/>
</iq>
]]></example>
<p>
When the MIX channel adds a JID to the banned node, other nodes in the MIX channel will be appropriately updated to reflect this change. In particular, the participants nodes and presence nodes will be updated to remove matching JIDs. This will have the effect of immediately removing the user from the channel. For this reason, there is no requirement to have the "kick" functionality of MUC, as this is achieved by banning the user.
</p>
</section3>
</section2>
</section1>
<section1 topic="MIX Requirements on Participant's Server" anchor="mix-requirements-participant-server">
<p>
This section defines behaviour REQUIRED by MIX for servers supporting MIX participants. This provides the full MIX specification for clients and servers is set out in a single document. This functionality MUST be provided by servers used by clients that participate in MIX channels. In future, the specifications in this section MAY be moved to a separate XEP or it MAY be incorporated into
&xep0376; (PAM) which follows a similar model.
</p>
<section2 topic="Server Identification of MIX Capabable Clients" anchor="server-identification-mix-clients">
<p>
A MIX User's server MUST determine which online clients support MIX. This will enable the server to send MIX traffic to all MIX capable clients. A MIX capable client MAY choose to come online and not advertise MIX capability. The mechanism for a server to discover client capability is described in <link url="#mix-client-discovery">Discovering Client MIX Capability</link>.
</p>
</section2>
<section2 topic="Messages From MIX Channels" anchor="mix-from">
<p>
Messages from a MIX channel will usually go to the participant's server. The only exception to this is where the MIX channel is responding directly to messages from the client. Messages and presence distributed but a MIX channel will always be sent to the participant's server and addressed to the user's bare JID. The participant's server will simply send on the messages from the channel to each of the user's online clients which advertise MIX capability. If there are no such clients activated, the message is dropped.
</p>
<p>
Messages sent to the participant's sever will always be addressed to the user's bare JID. The participant’s server will modify the recipient to the full JID of each client to which the message is forwarded. The participant's server MUST NOT make any other modifications to each message. The following example, repeated from earlier, shows a message distributed by a MIX channel and directed to the participant’s server with the participant's bare JID.
</p>
<example caption="Channel Reflects Message to Participants"><![CDATA[
<message from='coven@mix.shakespeare.example'
to='hecate@shakespeare.example'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
type='groupchat'>
<body>Harpier cries: 'tis time, 'tis time.</body>
<nick xmlns='urn:xmpp:mix:0'>thirdwitch</nick>
<jid xmlns='urn:xmpp:mix:0'>123456#coven@mix.shakespeare.example</jid>
</message>
]]></example>
<p>
The following example shows how the participant's server modifies the inbound message to replace the bare JID in the 'to' with a full JID for each of two active MIX clients.
</p>
<example caption="Participant's Server Sends Modified Message to two Clients"><![CDATA[
<message from='coven@mix.shakespeare.example'
to='hecate@shakespeare.example/UUID-x4r/2491'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
type='groupchat'>
<body>Harpier cries: 'tis time, 'tis time.</body>
<nick xmlns='urn:xmpp:mix:0'>thirdwitch</nick>
<jid xmlns='urn:xmpp:mix:0'>123456#coven@mix.shakespeare.example</jid>
</message>
<message from='coven@mix.shakespeare.example'
to='hecate@shakespeare.example/UUID-b5b/0114'
id='77E07BB0-55CF-4BD4-890E-3F7C0E686BBD'
type='groupchat'>
<body>Harpier cries: 'tis time, 'tis time.</body>
<nick xmlns='urn:xmpp:mix:0'>thirdwitch</nick>
<jid xmlns='urn:xmpp:mix:0'>123456#coven@mix.shakespeare.example</jid>
</message>
]]></example>
</section2>
<section2 topic="Messages To MIX Channels" anchor="user-server-to">
<p>
Messages sent by a MIX channel participant to the MIX channel are always sent from a MIX client directly to the channel. The participant's server relays the message but does not modify the messages.
</p>
</section2>
<section2 topic="MIX Management and Discovery" anchor="user-server-disco">
<p>
Most interaction between a MIX client and a MIX channel is directly between the client and the channel. The participant's server relays the message but does not modify the messages. In particular configuration management and discovery is direct. Interaction will be direct, unless explicitly stated otherwise.
</p>
</section2>
<section2 topic="IQ Support on Local Server" anchor="mix-diso">
<p>
Channel Join and Leave functions operate indirectly through the participant's server. The reason for this is that where a channel shares user presence, the channel is included in the user's roster which is managed in the local server. The Join and Leave functions lead to roster changes and so they MUST go through the participant's server. This is included in each of the operations that work in this manner. The general mechanism to achieve this is illustrated by example in this section.
The client addresses indirect messages to the user's own bare JID, indicating the channel with the channel attribute. This is illustrated below.
</p>
<example caption="Client sends request to local server to Join a MIX Channel"><![CDATA[
<iq type='set'
from='hag66@shakespeare.example/UUID-a1j/7533'
to='hag66@shakespeare.example'
id='E6E10350-76CF-40C6-B91B-1EA08C332FC7'>
<join xmlns='urn:xmpp:mix:0'
channel='coven@mix.shakespeare.example'>
<subscribe node='urn:xmpp:mix:nodes:messages'/>
<subscribe node='urn:xmpp:mix:nodes:presence'/>
<subscribe node='urn:xmpp:mix:nodes:participants'/>
<subscribe node='urn:xmpp:mix:nodes:config'/>
</join>
</iq>
]]></example>
<p>This is then modified by the local server and sent to the MIX channel. This is shown in the following example, repeated from the earlier specification of channel behaviour. </p>
<example caption="Participant's Server sends Join to MIX Channel"><![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'/>
<subscribe node='urn:xmpp:mix:nodes:participants'/>
<subscribe node='urn:xmpp:mix:nodes:config'/>
</join>
</iq>
]]></example>
<p>
The MIX service will send the IQ response to indirect messages to the user's server using the user's bare JID. The user's server will then route the response back to the user's client.
</p>
</section2>
<section2 topic="Roster Management" anchor="proxy-roster">
<p>
The participant's server is responsible for ensuring that MIX channels are correctly entered into the user's roster when user's join MIX channels and for removing them when they leave.
</p>
<p>
The participant's server MUST ensure that only presence information from clients that advertise MIX capability is sent to the MIX channel. So, if a user has two online clients, but only one is MIX capable, then the channel will only receive presence information relating to the MIX client.
</p>
</section2>
<section2 topic="MIX Roster Item Capability Sharing" anchor="mix-roster-capability-sharing">
<p>It will be useful for a MIX client to know which roster members are MIX channels, as this will facilitate convenient presentation of subscribed MIX channels to the user. A standard roster item is encoded as follows.</p>
<example caption="Standard Roster Item Encoding"><![CDATA[
<item jid='romeo@example.net'/>
]]></example>
<p>
MIX channels in the roster have an attribute 'channel' set to true.
</p>
<example caption="Roster Item Encoding of a MIX Channel"><![CDATA[
<item jid='romeo@example.net'>
<channel xmlns=‘urn:xmpp:mix:0'/>
</item>
]]></example>
<p>
When sending roster information to a client that advertises MIX capability, the server MUST return all MIX channels and MUST use this encoding. Presence of MIX roster items MUST be set to offline (unavailable).
</p>
<p>
Where a client does not advertise MIX capability, the server MAY choose to not return MIX channels as roster items. If this is done care needs to be taken, in particular around support of roster versioning &xep0237;.
</p>
</section2>
<section2 topic="MAM Archive Support" anchor="proxy-mam">
<p>
Archive of MIX channel messages is done by the participant's server. Where a message is sent to the participant's server and discarded because there are no active clients, it will still be archived. This means that the messages will be available in the local archive and can be picked up by clients when they come online.
</p>
</section2>
</section1>
<section1 topic="Supporting MIX and MUC together" anchor="mix-and-muc-together">
<p>
MIX is specified as a service that can be used independent of MUC and a MIX service MAY be implemented without MUC. If both MIX and MUC are implemented, three approaches are noted.
</p>
<ol>
<li>Entirely separate MIX and MUC implementation, with MIX and MUC using separate domains and MIX channels being completely separate from MUC rooms.</li>
<li>Fully integrated MIX and MUC implementation, with MIX and MUC sharing a single domain and rooms/channels equivalent.</li>
<li>Partially integrated MIX and MUC implementation, with MIX and MUC using separate domains, but rooms/channel are common. This means that each MIX channel will have MUC room of the same name and same participants.</li>
</ol>
<p>The fully integrated approach would be transparent to clients. The following example shows how a MIX service that also supported MUC would respond:</p>
<example caption="Service responds with Disco Info result showing MIX and MUC support" ><![CDATA[
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity
category='conference'
name='Shakespearean Chat Service'
type='text'/>
<feature var='urn:xmpp:mix:0'/>
<feature var='http://jabber.org/protocol/muc'/>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0#serviceinfo</value>
</field>
</x>
</query>
</iq>
]]></example>
<p>In the fully integrated service item discovery on the MIX/MUC service determines a list of channels. The protocol used for this is the same in MUC and MIX. Discovery actions on a channel in MIX MUST use 'node=mix' attribute in the discovery which will lead to the return of MIX channel specific information, as mandated for this discovery in MIX. If is not set, MUC room specific information is returned.
</p>
<p>For the partially integrated service, it will be useful for clients that support both MIX and MUC to be able to determine that the server supports both protocols. For a MIX client, it will be useful to know the MUC service, so that this information can be shared with a MUC client invitation. This information is provided by the initial service discovery:</p>
<example caption="MIX Service responds with Disco Info result sharing MUC service location" ><![CDATA[
<iq from='mix.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity
category='conference'
name='Shakespearean Chat Service'
type='text'/>
<feature var='urn:xmpp:mix:0'/>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0#serviceinfo</value>
</field>
<field var='muc-mirror'
type='jid-single'
label='Location of MUC mirror service'>
<value>chat.shakespeare.example</value>
</field>
</x>
</query>
</iq>
]]></example>
<p>The result is returned in an extended disco results in a form whose type value is 'urn:xmpp:mix:0#serviceinfo'. The field with var='muc-mirror' is the value of which is the mirrored MUC domain's JID. </p>
<p>Where a client supporting both MIX and MUC is given a reference to a MUC room, it is desirable that the client can determine the MIX channel and join using MIX. This is achieved by an equivalent extension to MUC service discover.</p>
<example caption="MUC Service responds with Disco Info result sharing MIX service location" ><![CDATA[
<iq from='chat.shakespeare.example'
id='lx09df27'
to='hag66@shakespeare.example/UUID-c8y/1573'
type='result'>
<query xmlns='http://jabber.org/protocol/disco#info'>
<identity
category='conference'
name='Shakespearean Chat Service'
type='text'/>
<feature var='http://jabber.org/protocol/muc'/>
<x xmlns='jabber:x:data' type='result'>
<field var='FORM_TYPE' type='hidden'>
<value>urn:xmpp:mix:0#serviceinfo</value>
</field>
<field var='mix-mirror'
type='jid-single'
label='Location of MUC mirror service'>
<value>mix.shakespeare.example</value>
</field>
</x>
</query>
</iq>
]]></example>
<p>The result is returned in an extended disco results in a form whose type value is 'urn:xmpp:mix:0#serviceinfo'. The field with var='mix-mirror' is the value of which is the mirrored MIX domain's JID. </p>
<section2 topic="Choosing Which Invite to Send" anchor="mix-muc-invite-choice">
<p>
Where a client supports MUC and MIX and has determined that for a channel that the server also supports a MUC room, the client has a choice as to which type of invite to send. This SHOULD be done by determining if the client support MIX using the mechanism specified in
<link url='#mix-client-discovery'>Discovering Client MIX Capability</link>. If the client supports MIX a MIX invite SHOULD be sent.
</p>
</section2>
</section1>
<section1 topic="Capabilities not provided in MIX" anchor="not-included-from45">
<p>This section lists a number of capabilities not specified in the core MIX which are provided in &xep0045;. These capabilities will not be added to core MIX but they could in the future be specified as independent XEPs.</p>
<section2 topic="Password Controlled Channels" anchor="password-control">
<p>
&xep0045; provides a mechanism to control access to MUC rooms using passwords. An equivalent mechanism is not included in core MIX, as it has a number of security issues. Control of access to channels is better achieved using an explicit list of participants.
</p>
</section2>
<section2 topic="Voice Control" anchor="voice-control">
<p>
&xep0045; defines a mechanism so that MUC moderators can control who is able to send messages to a MUC room using a "voice" mechanism. MIX does not provide an exact functional equivalent, although access control to channels enables some of the goals of voice control to be achieved in a different manner.
</p>
</section2>
<section2 anchor="not-subject" topic="Subject">
<p>&xep0045; provide a Subject capability to enable setting of the current topic of discussion. The Name and Description attributes provided by MIX enable descriptive information to be associated with a channel. These attributes can replace Subject in the way it is used in many MUC rooms, but they do not reflect the more limited topic nature of Subject.</p>
<p>It is likely that a new XEP to be used with MIX will be written, perhaps using a "Sticky Messages" approach to fulfil the Subject capability using a different approach. </p>
</section2>
</section1>
<section1 topic='Internationalization Considerations' anchor='i18n'>
<p>MIX allows specification of a number of human readable strings associated with a MIX channel, in particular the name and description information of a MIX channel. These strings MAY have language set using an xml:lang attribute, and multiple values MAY be set provided that each one is distinguished using xml:lang.
</p>
<p>Nicknames SHOULD be normalized using the "nickname" profile of the PRECIS OpaqueString class, as defined in &rfc7700;. </p>
</section1>
<section1 topic='Security Considerations' anchor='security'>
<p>MIX is built over MAM and PubSub and the security considerations of &xep0313; and &xep0060; MUST be considered. These services protect MIX channel information, which can be sensitive and needs appropriate protection.</p>
<p>MIX channels MAY be JID Hidden, in order to hide the JIDs of channel participants from those accessing the channel. Care MUST be taken to ensure that JIDs are fully hidden. In particular when proxy JIDs are prepared, this MUST be done in a manner which ensure that the real JIDs cannot be determined. Where nicks are assigned by a channel, this MUST be done in a way that does not expose the JID.</p>
<p>
There is no MIX equivalent to &xep0045; password controlled rooms, which avoids a number of security issues.
</p>
<p>
MIX provides flexible access control options, which MUST be used in a manner appropriate to the security requirements of MIX users and services.
</p>
</section1>
<section1 topic='IANA Considerations' anchor='iana'>
<p>None.</p>
</section1>
<section1 topic='XMPP Registrar Considerations' anchor='registrar'>
<p>The urn:xmpp:mix namespace needs to be registered.</p>
</section1>
<section1 topic='XML Schema' anchor='schema'>
<p>To be supplied when MIX progresses to proposed standard.</p>
</section1>
<section1 topic='Acknowledgements' anchor='ack'>
<p>Thanks to the following who have made contributions: Dave Cridland, Philipp Hancke, Waqas Hussain, Timothée Jaussoin, Evgeny Khramtsov, Georg Lukas, Tobias Markmann, Ralph Meijer, Edwin Mons, Emmanuel Gil Peyrot, Florian Schmaus, Lance Stout, Sam Whited, Jonas Wielicki, Matthew Wild and one anonymous reviewer.</p>
</section1>
</xep>
Reference in New Issue View Git Blame Copy Permalink