moparisthebest/xeps
1
0
Fork 0
mirror of https://github.com/moparisthebest/xeps synced 2024-11-21 16:55:07 -05:00
Code Issues Releases Wiki Activity

Editorial Review of Doc

Browse Source
This commit is contained in:
Steve Kille 2017-02-13 11:42:19 +00:00 committed by Sam Whited
parent 7d914b34bf
commit 4876eb89aa
1 changed files with 113 additions and 85 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

198
xep-0369.xml
View File

@ -38,7 +38,7 @@
&stpeter;
<revision>
<version>0.8</version>
<date>2017-02-XX</date>
<date>2017-02-12</date>
<initials>sek</initials>
<remark><p>
Update after Brussels Summit;
@ -52,6 +52,7 @@
Use example JIDs aligned to anticipated BIND2 specification;
Clarify PubSub Node Type;
Add Error handling section;
Substantial Editorial Review;
</p></remark>
</revision>
<revision>
@ -222,7 +223,7 @@
<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 focus) without undesirable adaptations.</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>
@ -231,7 +232,7 @@
<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. The MIX service SHOULD include a reference to the MUC mirror, so that clients understanding both protocols can choose to show only one copy of the service.</p>
<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'>
@ -249,8 +250,8 @@
<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>To enable sharing of messages on a channel without requiring sharing of presence.</li>
<li>To enable sharing of presence without requiring message sending.</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>
@ -265,25 +266,26 @@
<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 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> 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 old MUC issue of either receiving duplicate messages when rejoining a room or potentially missing messages.</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 all participants using bare JID, whether or not the user has an online client. </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>MIX requires client support and server support from the server providing the MIX service. 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 client support and server support from the server providing the MIX service. </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' and the fact that it is a subdomain of a 'shakespeare.example' service are purely for example.</p>
<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>
@ -306,7 +308,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<li>The MIX participant's server will only send messages to online clients and will discard messages if no clients are online.
This means that a MIX client needs to resynchronize with the MIX service 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 the MUST be done except where specifically noted. </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 and is sharing presence. 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>
@ -318,7 +320,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</section2>
<section2 topic="User Presence in MIX" anchor="concepts-presence">
<p>
MIX channels store presence in the presence node using the proxy JID of each online client for a user. User presence MAY be included for all or selected clients of a given user, based on client choice to publish presence. Where a user publishes presence for multiple clients, this information is available to all users subscribing to the channel presence.
MIX channels store presence in the presence node using the proxy JID of each online client for a user. User presence MAY be included based on client choice to publish presence. Where a user publishes presence for multiple clients, this information is available to all users subscribing to the channel presence.
</p>
<p>
External XMPP entities can direct stanzas to clients publishing their presence by sending them to the appropriate full proxy JID 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.
@ -332,9 +334,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
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>
<p>
Private messages MAY also be sent to specific clients identified by the full proxy JID of the client in the participants list, if allowed by channel policy.
</p>
</section2>
<section2 topic="Proxy JIDs and JID Visibility" anchor="proxy-jid">
<p>
@ -379,7 +379,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<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 combinations of these nodes.
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, shown in the last two columns of the table.
</p>
<p>
@ -406,7 +406,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<tr><td>Anyone</td><td>Any user, including users in the banned node.</td></tr>
</table>
<p>
There will always be at least one owner and "anyone" will always have role occupants. Other roles MAY NOT have any role occupants. Rights are defined in a strictly hierarchical manner, so that for example Owners will always have rights that Administrators have.
There MUST always be at least one owner and "anyone" will always have role occupants. Other roles MAY NOT have any role occupants. Rights are defined in a strictly hierarchical manner, so that for example Owners will always have rights that Administrators have.
</p>
</section3>
@ -416,8 +416,11 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</p>
</section3>
<section3 topic="Messages Node" anchor="messages-node">
<p>Items in this node will contain a message identified by the MAM ID used for the message in the channels MAM archive. &xep0313; rules MUST be used to ensure this ID is unique. A MIX implementation SHOULD NOT make messages available for retrieval from this node using pubsub and MUST NOT allow direct pubsub publishing to this node. Messages are published by sending messages to the channel. The Messages node is a transient node and so no PubSub items are held. Message 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.</p>
<p>Private Messages are not stored in the messages node.</p>
<p>
The Message 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">
@ -441,7 +444,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<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 channels, only administrators can subscribe. The JID MAP node is a permanent node with one item per participant.</p>
In JID visible channels, all participants MAY subscribe to this node. In JID hidden 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='coven+123456@mix.shakespeare.example'>
@ -453,7 +456,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</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 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 can be set to enforce that for each of the full JIDs in this list, the bare JID MUST be in the participants list.
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>
@ -516,7 +519,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</p>
<example caption="Allowed Node"><![CDATA[
<items node='urn:xmpp:mix:nodes:allowed'>
<item id='@shakespeare.lit'/>
<item id='shakespeare.lit'/>
<item id='alice@wonderland.lit'/>
</items>
]]></example>
@ -613,7 +616,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<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. This MUST come directly from a MIX client.
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/e0def5dc-3282-4d00-840a-0292622ba804/ba70bd0f-96fe-442d-872a-96ef3b168613'
@ -635,7 +638,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</query>
</iq>
]]></example>
<p>To determine if a domain hosts a MIX service, a &xep0030; info query SHOULD be sent in the usual manner to determine capabilities.</p>
<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/e0def5dc-3282-4d00-840a-0292622ba804/ba70bd0f-96fe-442d-872a-96ef3b168613'
id='lx09df27'
@ -644,7 +647,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<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'. </p>
<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'
@ -661,7 +664,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</iq>
]]></example>
<p>
A MIX service MUST return the first feature listed and MAY return the other features listed:
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>
@ -671,8 +674,8 @@ This approach enables flexible support of multiple clients for a MIX channel pa
<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 channel that exist and that the user making the query has rights to subscribe to. This query MUST be made directly by a client.</p>
<example caption='User&apos;s Server Queries for Channels on MIX Service'><![CDATA[
<p>The list of channels supported by a MIX service is obtained by a disco#items command. The MIX service MUST only return channel 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/e0def5dc-3282-4d00-840a-0292622ba804/ba70bd0f-96fe-442d-872a-96ef3b168613'
id='kl2fax27'
to='mix.shakespeare.lit'
@ -694,16 +697,16 @@ This approach enables flexible support of multiple clients for a MIX channel pa
]]></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. This query MUST be made directly by a client.</p>
<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='hhag66@shakespeare.example/e0def5dc-3282-4d00-840a-0292622ba804/ba70bd0f-96fe-442d-872a-96ef3b168613'
<iq from='hag66@shakespeare.example/e0def5dc-3282-4d00-840a-0292622ba804/ba70bd0f-96fe-442d-872a-96ef3b168613'
id='ik3vs715'
to='coven@mix.shakespeare.lit'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
<query xmlns='http://jabber.org/protocol/disco#info' node='mix'/>
</iq>
]]></example>
<p> 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 rad results returned MUST include 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>
<p> 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'
@ -721,7 +724,7 @@ This approach enables flexible support of multiple clients for a MIX channel pa
]]></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. The MIX service MUST only return nodes that exist and that the user making the query has rights to subscribe to. This query MUST be made directly by a client.</p>
<p>Use disco#items to find the nodes associated with a channel. Discovering nodes in MIX MUST user 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/e0def5dc-3282-4d00-840a-0292622ba804/ba70bd0f-96fe-442d-872a-96ef3b168613'
id='kl2fax27'
@ -749,13 +752,15 @@ This approach enables flexible support of multiple clients for a MIX channel pa
]]></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. This query MUST be made directly by a client.</p>
<example caption='User&apos;s Server Requests Channel Information'><![CDATA[
<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/e0def5dc-3282-4d00-840a-0292622ba804/ba70bd0f-96fe-442d-872a-96ef3b168613'
id='kl2fax27'
to='coven@mix.shakespeare.lit'
type='get'>
<query xmlns='urn:xmpp:mix:0#channel-info'/ node='mix'>
<pubsub xlns='http://jabber.org.protocol.pubsub'>
<items node='urn:xmpp:nodes:info'/>
</pubsub>
</iq>
]]></example>
<example caption='MIX Service Returns Channel Information'><![CDATA[
@ -763,35 +768,42 @@ This approach enables flexible support of multiple clients for a MIX channel pa
id='kl2fax27'
to='hag66@shakespeare.example/e0def5dc-3282-4d00-840a-0292622ba804/ba70bd0f-96fe-442d-872a-96ef3b168613'
type='result'>
<query xmlns='urn:xmpp:mix:0#channel-info' node='mix'>
<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>
</query>
<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>
Online clients in the channel are determined from the presence node. Participants in the channel are determined from the Participants Node which will give proxy JID and nick. The jidmap node is used to map to real JIDs. An operation is provided to list channel participants. For JID Hidden channels, only the nicks are returned. For JID Visible channels, nicks and real JIDs are returned. This query MUST be made directly by a client.</p>
Online clients in the channel are determined from the presence node using PubSub. Participants in the channel are determined from the Participants Node which will give proxy JID and nick. The jidmap node is used to map to real JIDs. For JID Hidden channels, only the nicks are returned. For JID Visible channels, nicks and real JIDs are returned. This query MUST be made directly by a client.</p>
<example caption='User&apos;s Server Requests Participant List'><![CDATA[
<iq from='hag66@shakespeare.example/e0def5dc-3282-4d00-840a-0292622ba804/ba70bd0f-96fe-442d-872a-96ef3b168613'
id='kl2fax27'
to='coven@mix.shakespeare.lit'
type='get'>
<query xmlns='urn:xmpp:mix:0#get-participants'/ node='mix'>
<pubsub xlns='http://jabber.org.protocol.pubsub'>
<items node='urn:xmpp:nodes:participants'/>
</pubsub>
</iq>
]]></example>
<example caption='MIX Service Returns Participant List for JID Visible Room'><![CDATA[
@ -799,19 +811,29 @@ This approach enables flexible support of multiple clients for a MIX channel pa
id='kl2fax27'
to='hag66@shakespeare.example/e0def5dc-3282-4d00-840a-0292622ba804/ba70bd0f-96fe-442d-872a-96ef3b168613'
type='result'>
<query xmlns='urn:xmpp:mix:0#get-participants' node='mix'>
<pubsub xlns='http://jabber.org.protocol.pubsub'>
<items node='urn:xmpp:nodes:participants'>
<item jid='hag66@shakespeare.lit' nick='thirdwitch'>
<item jid='hag01@shakespeare.lit' nick='top witch'>
</items>
</pubsub>
<items>
<item jid='hag66@shakespeare.lit' nick='thirdwitch'>
<item jid='hag01@shakespeare.lit' nick='top witch'>
</items>
</iq>
]]></example>
</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 response from a client that supports both MIX and MUC.
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 Response showing MIX support'><![CDATA[
<example caption='Disco Query for MIX support'><![CDATA[
<iq from='juliet@capulet.lit/46be1261-200b-4eea-8f82-e4fae46eec56/d6a85bb6-669f-471b-b55b-9a3930f5512e'
id='disco1'
to='romeo@montague.lit/14e8cb74-9082-4782-9275-8918ee5d8fcd/6983052d-3fdc-4e32-8221-79571a5210fe'
type='get'>
<query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>
<iq from='romeo@montague.lit/14e8cb74-9082-4782-9275-8918ee5d8fcd/6983052d-3fdc-4e32-8221-79571a5210fe'
id='disco1'
to='juliet@capulet.lit/46be1261-200b-4eea-8f82-e4fae46eec56/d6a85bb6-669f-471b-b55b-9a3930f5512e'
@ -909,8 +931,12 @@ This approach enables flexible support of multiple clients for a MIX channel pa
</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 response will also include other nodes requested where subscription failed for the same reason. The following response example shows a response to the initial request example where
the participant is not be subscribed to all nodes associated with the channel (in this case only messages, participants, and information). The following example is the message from the MIX channel to the user's server, which will be modified and sent to the client.</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 be 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'
@ -923,7 +949,7 @@ the participant is not be subscribed to all nodes associated with the channel (i
</join>
</iq>
]]></example>
<p>The channel also adds the user to the participants node and sends a notification to subscribers to the participants node. The following example shows such a notification.</p>
<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'
@ -963,7 +989,7 @@ the participant is not be subscribed to all nodes associated with the channel (i
</section3>
<section3 topic="Roster Management" anchor="usecase-roster-management">
<p>
As part of the channel joining process, the user's server MAY add the MIX channel to the user's roster using standard XMPP to update the roster. This is done to share the user's presence status with the channel and so the MIX channel will get presence information from the user. This roster entry will lead to the user's server correctly sending user's presence from all clients to the MIX channel. 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. The user's server MUST remove this roster entry after the user leaves the channel.
As part of the channel joining process, the user's server MAY add the MIX channel to the user's roster using standard XMPP to update the roster. This is done to share the user's presence status with the channel and so the MIX channel will get presence information from the user. This roster entry will lead to the user's server correctly sending user's presence from all clients to the MIX channel. 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. The user's server MUST remove this roster entry after the user leaves the channel.
</p>
<p>
If the user does not wish to publish presence information to the channel, the user will not add the roster entry. A channel MAY require presence to be provided by all channel participants, which is controlled by the 'Participants Must Provide Presence' option. The channel MAY check that channel participants have done this and MAY remove participants that do not do this.
@ -974,7 +1000,7 @@ the participant is not be subscribed to all nodes associated with the channel (i
</section3>
<section3 topic="User Preferences and Additional Information" anchor="usecase-visibilty-pref">
<p>A channel MAY store user preferences and parameters with each user. There are two preference options.
<p>A channel MAY store user preferences and parameters with each user. There are several standard preference options.
</p>
<p>
A user JID visibility preference have the following values:
@ -1148,7 +1174,7 @@ the participant is not be subscribed to all nodes associated with the channel (i
The user's server will then generate a matching request to the MIX channel.
</p>
<example caption="User Leaves a Channel"><![CDATA[
<example caption="User's Server sends Leave Request to a Channel"><![CDATA[
<iq type='set'
from='hag66@shakespeare.example'
to='coven@mix.shakespeare.example'
@ -1198,7 +1224,7 @@ the participant is not be subscribed to all nodes associated with the channel (i
</message>
<message from='coven@mix.shakespeare.example'
to='hecate@shakespeare.example' id='bar'>
to='other-witch@shakespeare.example' id='bar'>
<event xmlns='http://jabber.org/protocol/pubsub#event'>
<items node='urn:xmpp:mix:nodes:presence'>
<retract id='coven+123456@mix.shakespeare.example/8765'/>
@ -1250,8 +1276,8 @@ the participant is not be subscribed to all nodes associated with the channel (i
]]></example>
</section3>
<section3 topic='Registering a Nick' anchor='usecase-user-register'>
<p>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 nick is associated with the user's bare JID.
<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.
@ -1327,20 +1353,20 @@ the participant is not be subscribed to all nodes associated with the channel (i
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 SHALL 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.
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. User's 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.
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. If there is not an item named by the full JID of the client with updated presence status, then an item is created.</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/d104f6a7-97e9-477f-8947-e4a37691d7ee/7533375f-2cd1-4455-a311-494bab21f9f0’
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 proxy (anonymized) full JID of the user.
<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 proxy (anonymized) full 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='coven+123435@mix.shakespeare.example/678'
@ -1351,7 +1377,7 @@ the participant is not be subscribed to all nodes associated with the channel (i
<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 in the item for the full JID of the client to which the presence relates. The history of this node will be held as PubSub format in the MAM archive, so that presence history can be viewed.
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>
@ -1506,7 +1532,7 @@ the participant is not be subscribed to all nodes associated with the channel (i
</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 ('Participation Addition by Invitation from Participant' enabled). 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.
<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>
@ -1518,15 +1544,16 @@ the participant is not be subscribed to all nodes associated with the channel (i
<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 enable. 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.
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/d1781be2-2b2d-4cd8-8886-bdc0e1087873/2183ee64-9c97-4eeb-bdc0-c35138b9c2b1'
id='kl2fax27'
to='coven@mix.shakespeare.lit'
type='get'>
<query xmlns='urn:xmpp:mix:0#request-invitation'/>
<invitee>cat@shakespeare.lit</invitee>
<invite xmlns='urn:xmpp:mix:0'>
<invitee>cat@shakespeare.lit</invitee>
</invite>
</iq>
@ -1534,13 +1561,14 @@ the participant is not be subscribed to all nodes associated with the channel (i
id='kl2fax27'
to='hag66@shakespeare.lit/d1781be2-2b2d-4cd8-8886-bdc0e1087873/2183ee64-9c97-4eeb-bdc0-c35138b9c2b1'
type='result'>
<query xmlns='urn:xmpp:mix:0#request-invitation'>
<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>
@ -1834,7 +1862,7 @@ the participant is not be subscribed to all nodes associated with the channel (i
<section3 topic='Creating a Channel for Ad Hoc Use' anchor='usecase-admin-create-adhoc'>
<p>
Rooms 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.
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/d104f6a7-97e9-477f-8947-e4a37691d7ee/7533375f-2cd1-4455-a311-494bab21f9f0'
@ -1854,7 +1882,7 @@ the participant is not be subscribed to all nodes associated with the channel (i
</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 move a dialogue. 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.
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.
@ -2082,7 +2110,7 @@ the participant is not be subscribed to all nodes associated with the channel (i
type='result'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<items node='urn:xmpp:mix:nodes:allowed'>
<item id='@shakespeare.lit'/>
<item id='shakespeare.lit'/>
<item id='alice@wonderland.lit'/>
</items>
</pubsub>
@ -2098,7 +2126,7 @@ the participant is not be subscribed to all nodes associated with the channel (i
type='set'>
<pubsub xmlns='http://jabber.org/protocol/pubsub'>
<publish node='urn:xmpp:mix:nodes:allowed'>
<item id='@marlow.lit'/>
<item id='marlow.lit'/>
</items>
</pubsub>
</iq>
@ -2330,7 +2358,7 @@ the participant is not be subscribed to all nodes associated with the channel (i
</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 will use 'node=mix' in the discovery which will lead to the return of MIX channel specific information. If is not set, MUC room specific information is returned.
<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[